# Revenue Payment API Reference

> Send custom purchases, renewals, refunds, and subscription events with idempotency and optional journey identifiers.

Canonical page: [https://attribiq.com/guides/payment-api-reference](https://attribiq.com/guides/payment-api-reference)

Category: API Reference

Last updated: 2026-09-04

Topics: payment api, revenue api, idempotency, custom billing

## Summary

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.

## What this guide covers

- 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

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

## Request body

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

## 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:

- `purchase`
- `subscription_started`
- `renewal`
- `upgrade`
- `downgrade`
- `refund`
- `cancellation`
- `churn`

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](https://attribiq.com/guides/generic-payment-api-revenue-tracking) for implementation guidance, or [browser attribution API](https://attribiq.com/guides/browser-attribution-api) to pass visitor context into custom checkout.

## Frequently asked questions

### 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.