Skip to main content
POST

Authorizations

x-tenant-api-key
string
header
required

Tenant API key for authentication. Keys are scoped to specific environments (LIVE or SANDBOX). Obtain keys from the admin dashboard.

Headers

Idempotency-Key
string

Optional idempotency key to safely retry the same purchase event. Use a stable identifier (for example an order ID) to prevent duplicate commission creation.

Maximum string length: 255

Body

application/json
user_id
string<uuid>
required

The buyer's user ID

amount
number<double>
required

Purchase amount in the specified currency

Required range: x >= 0.01
currency
string

ISO 4217 currency code. If omitted, the tenant base currency is used.

Pattern: ^[A-Z]{3}$
provider_transaction_id
string

Optional upstream payment provider transaction identifier (for audit/reconciliation)

metadata
object

Additional metadata to store with the event and downstream commission ledger entries

Response

Purchase event accepted

Response returned when a purchase event is accepted for processing.

message
string
required

Human-readable status message

ledgerPayload
object
required
idempotency_key
string | null

Echoed idempotency key if one was provided via the Idempotency-Key header