Payments API

Any payment provider: send each sale from your server, and DataBull credits it to the visit that brought the buyer.

Stripe, Polar, Dodo Payments and Creem connect with a key. For anything else (Lemon Squeezy, Paddle, Gumroad, PayPal, your own billing), post each payment from your webhook handler. The body is the same as DataFast's payments API, so moving over is a URL and key change.

1. Create a payments key

Website settings → Revenue attribution → Another provider? Send payments from your server → Create a payments key. It works for that one website and can only send sales: it can't read your analytics. Keep it on your server; requests from a browser are refused.

2. Pass the visitor id to your checkout

The script stores the visitor id in the first-party cookie datacheap_visitor_id (or call window.datacheap.getVisitorId()). Put it in your checkout's custom data so it comes back with the payment, e.g. Lemon Squeezy checkout_data.custom, Paddle customData.

3. Send the payment

curl -X POST https://YOUR-DATABULL-URL/api/v1/payments \
  -H "Authorization: Bearer dbk_YOUR_PAYMENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id":"order_1001","amount":29.99,"currency":"USD","databull_visitor_id":"VISITOR_ID","email":"buyer@example.com"}'

Field
`transaction_id`	Required. Your provider's id for the payment. Sending it again is safe: nothing is counted twice.
`amount`, `currency`	Required. Major units (`29.99`) and an ISO code (`USD`). `0` is a free trial: not revenue, but it links the visitor to the email for the paid sale that follows.
`databull_visitor_id`	The visitor id (`datafast_visitor_id` and `visitor_id` work too). Without it, the sale is matched by email, then by checkout timing.
`email`, `name`, `customer_id`	Optional. Who paid.
`renewal`, `subscription_id`	Optional. Renewals inherit the source of the subscription's (or customer's) first payment.
`product_name`, `product_id`, `tax`, `timestamp`, `metadata`	Optional. `timestamp` is ISO 8601 or Unix time; it defaults to now.

The reply says how the sale was attributed, with its source. A visitor id sent later for the same transaction_id links the sale then.

Refunds

Send the original transaction_id with "refunded": true for a full refund, or "refunded_amount": 10 for a partial one. Resending the original payment never undoes a refund.

Check or remove a sale

curl https://YOUR-DATABULL-URL/api/v1/payments/order_1001 -H "Authorization: Bearer dbk_YOUR_PAYMENTS_KEY"
curl -X DELETE https://YOUR-DATABULL-URL/api/v1/payments/order_1001 -H "Authorization: Bearer dbk_YOUR_PAYMENTS_KEY"

Errors come back as {"error": "…"} with a plain explanation: 400 for a bad field, 401 for a missing or revoked key, 403 for a key of another website, 404 for an unknown transaction, 409 when a transaction_id was already recorded with a different amount.

Next: Goals & funnels →