Payment API reference
Reference for sending custom revenue events to AttribIQ with idempotency, normalized event types, and attribution identifiers.
The Payment API accepts normalized revenue events from custom billing systems and unsupported providers. Send stable transaction IDs, event type, amount, currency, timestamp, and AttribIQ visitor or session identifiers.
- Send a revenue event to /v1/revenue
- Use idempotency keys safely
- Choose supported event types
- Connect custom payments to attribution identifiers
The Payment API is for sending revenue events from custom billing systems and payment providers that are not connected natively yet.
Stripe users should usually prefer the Stripe webhook integration. Use this API when you already have normalized payment events in your own backend.
Endpoint
POST /v1/revenue
Authorization: Bearer sk_project_...
Idempotency-Key: txn_123
Content-Type: application/json
Request body
{
"provider": "custom",
"transaction_id": "txn_123",
"event_type": "purchase",
"amount": 2900,
"currency": "EUR",
"occurred_at": "2026-05-20T10:30:00Z",
"visitor_id": "v_abc",
"session_id": "s_def",
"customer_id_hash": "hash_123",
"metadata": {
"plan": "builder",
"product": "monthly_subscription"
}
}
Fields
| Field | Required | Notes |
|---|---|---|
provider | Yes | Use custom or your provider key. |
transaction_id | Yes | Stable provider or billing event ID. |
event_type | Yes | One of the supported normalized event types. |
amount | Yes | Integer in minor currency units. |
currency | Yes | ISO currency code such as EUR or USD. |
occurred_at | Recommended | ISO timestamp. Defaults to receive time if omitted. |
visitor_id | Optional | AttribIQ visitor ID from the browser attribution object. |
session_id | Optional | AttribIQ session ID from the browser attribution object. |
customer_id_hash | Optional | Stable one-way customer identifier. |
metadata | Optional | Small debugging context such as plan or product. |
Event types
Supported event types:
purchasesubscription_startedrenewalupgradedowngraderefundcancellationchurn
Use stable event names. Reporting becomes harder when integrations invent provider-specific names for the same business event.
Idempotency
Retries are normal. Send the same Idempotency-Key for the same logical payment event and keep provider + transaction_id stable.
Do not generate a fresh random transaction ID on each retry. That creates duplicate revenue.
Next steps
Read generic Payment API revenue tracking for implementation guidance, or browser attribution API to pass visitor context into custom checkout.
FAQ
Should amount be in cents?
Send amount in minor currency units. For EUR and USD, 2900 means 29.00.
What should the idempotency key be?
Use the same stable transaction, invoice, or billing event ID every time you retry the same event.
Can I send events without visitor_id?
Yes. They will be recorded as unattributed revenue if no attribution identifiers are present.
What content type should I use?
Use application/json with a project API key in the Authorization header.
Connect payments to the dashboard
Install the tracker, pass attribution into checkout, and report revenue by source, campaign, landing page, and path.
Related guides
Web tracker reference
Install the AttribIQ browser tracker and collect sessions, pageviews, referrers, UTMs, custom events, goals, and checkout context.
AttribIQ browser attribution API
Reference for reading AttribIQ visitor, session, landing page, referrer, and UTM context before checkout starts.
AttribIQ CLI reports
Run AttribIQ overview, revenue, campaign, goal, and funnel reports from scripts, release checks, and internal tools.