Generic Payment API revenue tracking

The generic Payment API lets any backend send revenue events into AttribIQ.

Use it when you do not use Stripe, when your payment provider is not supported yet, or when your billing system already normalizes payment activity internally.

Event shape

The event should describe what happened, when it happened, how much money changed, and which AttribIQ visitor or session should receive attribution context.

POST /v1/revenue
Authorization: Bearer sk_project_...
Idempotency-Key: txn_123
Content-Type: application/json

{
  "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"
  }
}

Amounts should be sent in minor units. For EUR and USD, 2900 means 29.00.

Supported event types

Start with a small vocabulary:

• purchase
• subscription_started
• renewal
• upgrade
• downgrade
• refund
• cancellation
• churn

Keep event names stable. If every integration invents new names, the dashboard becomes hard to compare.

Idempotency

Payment systems retry. Your backend may retry too. AttribIQ should receive a stable transaction ID and an idempotency key so duplicate submissions do not create duplicate revenue.

Good transaction IDs are provider object IDs, invoice IDs, charge IDs, or your own durable billing event IDs.

Avoid generated random IDs for every retry. They defeat idempotency.

Attribution identifiers

The browser tracker exposes an attribution object. Your app should pass it to your backend when a checkout, upgrade, or purchase begins.

At minimum, send:

• visitor_id
• session_id
• customer_id_hash when an authenticated customer exists

The customer hash should be a stable one-way identifier, not raw email. That keeps reporting useful without turning analytics into a customer database.

Processing rules

A robust receiver should:

1. Validate the project API key.
2. Validate the event type, amount, currency, and timestamp.
3. Enforce idempotency with provider plus transaction ID.
4. Store accepted events for debugging.
5. Write normalized revenue events into analytics storage.
6. Join the event to prior visitor and session data.

If attribution fields are missing, accept the revenue as unattributed. Totals must stay correct even when attribution is incomplete.

Next steps

Read what revenue attribution is for the model, or use Stripe revenue attribution if Stripe is your payment provider.