Events

Webhook Events

We send webhook events whenever important activity happens (for example: transaction updates). Each webhook has two top-level keys:

meta — metadata about the event
data — details about the transaction

Supported Events

Event	When it’s sent
`transaction.success`	The transaction was successfully processed and confirmed.
`transaction.failed`	The transaction could not be completed (payment declined, blockchain error, etc.).

Example Event Payload

{
  "meta": {
    "version": "1.0",
    "server_time": 1735303290,
    "event": "transaction.success"
  },
  "data": {
    "id": "12345",
    "provider_transaction_id": "abc-789",
    "partner_context": "order-12345",
    "type": "BUY",
    "sender_address": null,
    "recipient_address": "0x456...",
    "exchange_rate": "1.05",
    "transaction_hash": "0xdeadbeef...",
    "provider_fee": "2.50",
    "provider_fee_currency": "USD",
    "client_fee": "0.25",
    "client_fee_currency": "USD",
    "orki_fee": "0.50",
    "orki_fee_currency": "USD",
    "network_fee": "0.20",
    "network_fee_currency": "USD",
    "fiat_amount": "100.00",
    "crypto_amount": "0.0023",
    "fiat_currency": "USD",
    "crypto_currency": "ETH",
    "network": "ETHEREUM",
    "payment_method": "credit_debit_card",
    "status": "success",
    "provider": "stripe",
    "created_at": "2025-08-26T10:00:00Z"
  }
}

Meta object reference

Field	Type	Description
`version`	string	Webhook format version (currently `1.0`).
`server_time`	integer	Unix timestamp when event was created.
`event`	enum	Event type (`transaction.success`, `transaction.failed`).

Data object reference

Field	Type	Description
`id`	string	Internal event ID.
`provider_transaction_id`	string	ID from the payment provider.
`partner_context`	string \| null	Partner-supplied reconciliation value, or `null` when omitted.
`type`	string	Transaction type (`buy`, `sell`).
`sender_address`	string	Blockchain address of sender.
`recipient_address`	string \| null	Blockchain destination address. The field is always included; successful BUY events contain the provider-confirmed address or the address supplied for the transaction. It is `null` when no blockchain recipient applies.
`exchange_rate`	string	Fiat-to-crypto rate applied.
`transaction_hash`	string	Blockchain transaction hash.
`provider_fee`	string \| null	Fee charged by provider, or `null` when unavailable.
`provider_fee_currency`	string \| null	Currency or asset code for `provider_fee`, or `null` when the fee is unavailable.
`client_fee`	string \| null	Partner fee applied to the transaction.
`client_fee_currency`	string \| null	Currency code for `client_fee`. This is `USD` when a client fee is supplied, or `null` when unavailable.
`orki_fee`	string \| null	Our platform fee, or `null` when unavailable.
`orki_fee_currency`	string \| null	Currency code for `orki_fee`. This is `USD` when an Orki fee is supplied, or `null` when unavailable.
`network_fee`	string \| null	Network (gas) fee, or `null` when unavailable.
`network_fee_currency`	string \| null	Currency or asset code for `network_fee`, or `null` when the fee is unavailable.
`fiat_amount`	string	Provider-reported base fiat transaction amount before separately itemized fees are deducted or added.
`crypto_amount`	string	Amount in crypto.
`fiat_currency`	string	ISO code of fiat currency (e.g. `USD`, `EUR`).
`crypto_currency`	string	Symbol of crypto asset (e.g. `ETH`, `BTC`).
`network`	string	Blockchain network (e.g. `ethereum`, `bitcoin`).
`payment_method`	string	Method used (e.g. `credit_debit_card`, `bank_transfer`).
`status`	string	Transaction status (`pending`, `success`, `failed`).
`provider`	string	Payment provider name.
`created_at`	string	ISO timestamp of creation.

partner_context is included in the data object for transaction webhooks. Store your own transaction or order identifier in this field when creating the transaction; if you omit it, the webhook returns null.

recipient_address is always present in the webhook data object. For new BUY transactions created with wallet_address, it remains populated on success: Orki uses a nonblank provider-reported destination and preserves the submitted wallet when the provider omits it or returns null, an empty string, or whitespace. A BUY without a submitted wallet, including an older record that did not save one, may still return null if the provider omits the address.

Use provider_fee_currency, client_fee_currency, orki_fee_currency, and network_fee_currency when reconciling fees. Provider and network fee denominations can vary by provider and route; do not infer them from fiat_currency or crypto_currency.

fiat_amount is not reduced by provider_fee, client_fee, orki_fee, or network_fee. For a transaction with a base fiat amount of 100.00 EUR and a separately reported provider fee of 2.50 EUR, the webhook returns fiat_amount: "100.00" and provider_fee: "2.50", not fiat_amount: "97.50".

Fee denominations

Amount field	Denomination
`provider_fee`	The provider’s reported fee denomination, returned in `provider_fee_currency`.
`client_fee`	USD, returned as `client_fee_currency: "USD"`.
`orki_fee`	USD, returned as `orki_fee_currency: "USD"`.
`network_fee`	The provider’s reported network-fee denomination, returned in `network_fee_currency`. Depending on the provider and route, this can be fiat or a crypto asset.

When a fee amount is null, its companion currency is also null. For example, Stripe reports its transaction and network fees in the source fiat currency, while Guardarian and Coinify can report the provider fee in fiat and the network fee in a crypto asset.

Getting started

Authentication

Integration Guide

Widget Integration

API Integration

Ramp Providers

Supported Assets

Webhooks

Webhook Events

Supported Events

Example Event Payload

Meta object reference

Data object reference

Fee denominations

​Webhook Events

​Supported Events

​Example Event Payload

​Meta object reference

​Data object reference

​Fee denominations

Webhook Events

Supported Events

Example Event Payload

Meta object reference

Data object reference

Fee denominations