# Webhooks

> For the complete documentation index, see [llms.txt](https://docs.banxa.com/llms.txt). Append `.md` to any page URL for its markdown version.


Banxa sends webhook notifications to your callback endpoint whenever a ramp's status changes or a customer's account is blocked. This eliminates the need to poll for status updates and allows you to track the complete transaction lifecycle in real time.

## Setup

Configure your webhook endpoint URL in the [Partner Dashboard](https://dashboard.banxa.com/). You can set separate URLs for sandbox and production.

The webhook URL must:

- Be publicly accessible over HTTPS.
- Return a `200` HTTP response to acknowledge receipt.


Use **Send test** next to the URL in the dashboard to send a signed test request to your endpoint and see the HTTP status it returned.

## Available Webhooks

### 1. Ramp Webhooks

Ramp webhooks are triggered on all ramp status transitions. Banxa sends an HTTP `POST` request with a JSON body.

**Payload example:**

```json
{
  "order_id": "fd04c5780062121628e05324003eef30",
  "transfer_id": "fd04c5780062121628e05324003eef30",
  "status": "FULFILLED",
  "status_date": "2023-06-0519:53:08",
  "created_at": "2023-06-0214:44:00",
  "updated_at": "2023-06-0913:53:08",
  "internal_reason": "Order has been completed.",
  "external_reason": "Your payment was successfully received. Your order is now being processed.",
  "order_type": "ONRAMP",
  "crypto_coin": "ETH",
  "crypto_blockchain": "ETH",
  "crypto_amount": "0.228632",
  "fiat_currency": "AUD",
  "fiat_amount": "100",
  "asset_price": "0.018656",
  "payment": "payid-bank-transfer",
  "processing_fee": "1.95",
  "network_fee": "2.33",
  "usd_exchange_rate": "1.36",
  "transaction_hash": "0x9401a7173d7bd2ad73e8b798fdc30c83fb0529e6edbad163c549a5ad136407be"
}
```

| Field | Description |
|  --- | --- |
| `order_id` | The unique Banxa identifier for the ramp. |
| `transfer_id` | The same identifier as `order_id`. |
| `status` | The new ramp status. See the status table below. |
| `status_date` | Timestamp of the most recent status transition. See [Timestamps](#timestamps). |
| `created_at` | Timestamp of when the ramp was initially created. |
| `updated_at` | Timestamp of the last update to the ramp record. |
| `internal_reason` | Internal system description of the status — for your records. |
| `external_reason` | User-facing message you can surface to your customer. |
| `order_type` | Transaction direction: `ONRAMP` (fiat to crypto) or `OFFRAMP` (crypto to fiat). |
| `crypto_coin` | Ticker symbol of the cryptocurrency (e.g., `ETH`, `BTC`). |
| `crypto_blockchain` | Blockchain network used for the transaction. |
| `crypto_amount` | Amount of cryptocurrency involved. |
| `fiat_currency` | ISO code of the fiat currency (e.g., `USD`, `AUD`). |
| `fiat_amount` | Fiat amount of the transaction. |
| `asset_price` | Price of one unit of the cryptocurrency in the source fiat currency. |
| `payment` | The payment method used for the ramp (e.g., `payid-bank-transfer`). |
| `original_payment_method` | The payment method the ramp started with. Differs from `payment` if the payment was retried with another method. Can be `null`. |
| `is_retry` | `true` if the payment was retried with a different payment method; otherwise `false`. |
| `processing_fee` | Banxa processing fee in the source fiat currency. |
| `network_fee` | Blockchain network (gas) fee in the source fiat currency. |
| `usd_exchange_rate` | Exchange rate: 1 unit of source fiat to USD at order creation time. |
| `transaction_hash` | On-chain transaction identifier (TXID) for the crypto transfer. Only included when `status` is `FULFILLED`. For an off-ramp, it is the customer's deposit transaction. Can be `null`. |


The payload never includes the off-ramp deposit address. Read it from `sourceDepositInstructions` in the create response or `GET /eapi/v0/ramps/{id}`.

**Ramp status values:**

Events marked (on-ramp) or (off-ramp) are only sent for that direction.

| Status | Description |
|  --- | --- |
| `IN_PROGRESS` | Ramp is in progress. |
| `PAYMENT_READY` | Payment is ready to be processed. |
| `PAYMENT_ACCEPTED` | Payment has been accepted (on-ramp). The off-ramp equivalent is `COIN_DEPOSIT_CONFIRMED`. |
| `PAYMENT_RECEIVED` | Payment has been received by Banxa. |
| `PAYMENT_DECLINED` | Payment was declined. |
| `PAYMENT_CANCELLED` | Payment was cancelled. |
| `COIN_DEPOSIT_READY` | Crypto deposit address is ready (off-ramp). |
| `COIN_DEPOSIT_CONFIRMED` | Crypto deposit has been confirmed (off-ramp). |
| `COIN_TRANSFERRED` | Crypto has been transferred to the customer's wallet (on-ramp). |
| `FIAT_TRANSFERRED` | Fiat has been transferred to the customer's bank account (off-ramp). |
| `FULFILLED` | Ramp has been completed successfully. |
| `REFUNDED` | Ramp has been refunded. |
| `EXPIRED` | Ramp has expired. |
| `EXTRA_VERIFICATION` | Customer requires additional verification before the ramp can proceed. |
| `ACCOUNT_BLOCKED` | Customer account is blocked. A separate identity webhook will also be sent. |


#### Off-ramp event sequence

A successful off-ramp typically sends these events, in this order:

| Event | When |
|  --- | --- |
| `PAYMENT_READY` | Sometimes sent first, when the deposit address is still being prepared. |
| `COIN_DEPOSIT_READY` | The deposit address is ready, so the customer can send. Also sent again if the deposit window is extended (for example after an underpayment). |
| `COIN_DEPOSIT_CONFIRMED` | The crypto deposit has been received and confirmed. |
| `FIAT_TRANSFERRED` | The fiat payout has been sent to the customer's bank. |
| `FULFILLED` | The ramp is complete. |


`COIN_DEPOSIT_READY` is not guaranteed: it isn't sent if the deposit address was already available when the ramp was created. Don't wait for a specific event — act on the latest status you receive.

An off-ramp can also end or pause with `EXPIRED`, `PAYMENT_CANCELLED`, `EXTRA_VERIFICATION`, `ACCOUNT_BLOCKED` or `REFUNDED`. Crypto that arrives after a ramp has expired is not picked up automatically; contact Banxa Support.

#### Ramp status vs webhook event

`GET /eapi/v0/ramps/{id}` returns a ramp `status` that uses different names from webhook events. The same statuses are used in both directions, but `FUNDS_RECEIVED` and `PAYMENT_SUBMITTED` mean different things:

| Ramp status (`GET`) | On-ramp | Off-ramp | Off-ramp webhook event(s) |
|  --- | --- | --- | --- |
| `INITIALIZED` | Ramp created. Only returned in the create response. | Ramp created. Only returned in the create response. | None |
| `AWAITING_FUNDS` | Waiting for the customer's fiat payment. | Waiting for the customer's crypto deposit. | `PAYMENT_READY`, `COIN_DEPOSIT_READY` |
| `FUNDS_RECEIVED` | Fiat payment received. | Crypto deposit received. | `COIN_DEPOSIT_CONFIRMED` |
| `PAYMENT_SUBMITTED` | Crypto sent to the customer's wallet. | Fiat payout sent to the customer's bank account. | `FIAT_TRANSFERRED` |
| `COMPLETED` | Ramp complete. | Ramp complete. | `FULFILLED` |
| `CANCELLED` | Ramp expired, cancelled, declined, or needs extra verification. | Ramp expired, cancelled, declined, or needs extra verification. | `EXPIRED`, `PAYMENT_CANCELLED`, `EXTRA_VERIFICATION`, and declined ramps |
| `REFUNDED` | Ramp refunded. | Crypto returned to the customer's wallet. | `REFUNDED` |


Because `CANCELLED` covers several outcomes, polling alone can't tell you why a ramp stopped. Use webhooks if you need the reason.

#### Timestamps

`status_date`, `created_at` and `updated_at` are sent as `YYYY-MM-DDhh:mm:ss`, with no separator between the date and the time (for example `2023-06-0519:53:08`). Parse them with that exact format rather than as ISO 8601.

### 2. Identity Webhooks

Identity webhooks are triggered when a customer's account is blocked due to compliance or risk policies, or when a customer is held for additional verification (Enhanced Due Diligence, a verification phone call, a questionnaire, proof of address or source of funds). Please reach out to your Banxa contact if you would like the additional verification webhook enabled.

**Payload example:**

```json
{
  "identity_reference": "partner-customer-123",
  "status": "ACCOUNT_BLOCKED",
  "status_date": "2023-06-0519:53:08",
  "order_id": "",
  "internal_reason": "Customer account is blocked.",
  "external_reason": "Your order could not be processed."
}
```

| Field | Description |
|  --- | --- |
| `identity_reference` | Your stable identifier for the customer, as provided during ramp creation. |
| `status` | The identity status: `ACCOUNT_BLOCKED` or `EXTRA_VERIFICATION`. |
| `status_date` | Timestamp of the status update. See [Timestamps](#timestamps). |
| `order_id` | The ramp that triggered the webhook, or an empty string when it is not tied to a ramp. |
| `internal_reason` | Internal system description — for your records. |
| `external_reason` | User-facing message you can surface to your customer. |


### 3. KYC Webhooks

KYC webhooks are triggered whenever a customer's identity verification state changes. This allows you to track verification progress and prompt customers to take action when required.

KYC webhooks are also how you learn the result of a [Standalone KYC](/products/native-api/docs/how-it-works/standalone-kyc) session.

Please reach out to your Banxa contact if you would like to have this webhook enabled.

**Payload example:**

```json
{
  "identity_reference": "customer-12345",
  "account": {
    "exists": true,
    "blocked": false,
    "createdAt": "2023-06-05 19:53:08"
  },
  "kyc": {
    "status": "VERIFIED"
  }
}
```

| Field | Description |
|  --- | --- |
| `identity_reference` | Your `identityReference` for the customer. Standalone KYC webhooks use this same field: the value you sent as `externalCustomerId` when you created the session comes back here. |
| `account.exists` | Whether the customer profile exists in the Banxa system. |
| `account.blocked` | Whether the customer account has been blocked. |
| `account.createdAt` | Timestamp of account creation, as `YYYY-MM-DD hh:mm:ss`. `null` if the identity does not yet exist. |
| `kyc.status` | The verification outcome of the customer's submitted identity documents (liveness check + document). See status table below. |


**`kyc.status` values:**

| Status | Description |
|  --- | --- |
| `PENDING` | No identity documents have been submitted yet. |
| `UNDER_REVIEW` | Documents are being reviewed. |
| `ACTION_REQUIRED` | Additional action is required from the customer. |
| `VERIFIED` | Document and liveness verification passed. For a Standalone KYC `express` session, which collects no document or selfie, `VERIFIED` means the customer has provided everything that level asks for. |
| `REJECTED` | Verification was unsuccessful. |


The webhook doesn't say why verification didn't pass. For `ACTION_REQUIRED` or `REJECTED`, call `GET /eapi/v0/identities/{identityReference}` and read `kyc.rejectionReasons`. For a failed Sumsub token share, see [When a token share fails](/products/native-api/docs/how-it-works/kyc-token-sharing#when-a-token-share-fails).

> **Important:** `kyc.status` reflects document and liveness verification only — it does not account for Lite tier data, supplementary fields (e.g. purpose of transaction, occupation), or overall transaction eligibility. A `VERIFIED` status means the identity documents passed review; it does not mean the customer is eligible to transact. Always use the eligibility endpoint to determine whether a customer can proceed with a ramp.


## Retry behaviour

If your endpoint does not respond with `200 OK`, Banxa will automatically retry delivery with the same payload.

Retries follow a **Fibonacci sequence**: 1s, 2s, 3s, 5s, 8s, 13s, and so on — for a maximum of **2 hours**.

Respond with `200 OK` immediately and process the event asynchronously to avoid unnecessary retries.

Implement idempotent webhook handling. In rare cases your endpoint may receive the same event more than once. Use `order_id` and `status` as a deduplication key.

## Securing Webhooks

Banxa signs every webhook it sends using HMAC-SHA256. You verify this signature to confirm the request genuinely came from Banxa.

> **Webhook verification is the reverse of request signing.** When you sign outbound API requests to Banxa, you use a Banxa API path in the canonical string. When you verify an incoming webhook, you use the URI path of **your own webhook endpoint** — for example `/webhooks/banxa` — not a Banxa API path. Everything else follows the same algorithm described in [Authentication](/products/native-api/docs/getting-started/authentication).


Webhooks are signed with your API key pair. If you have more than one active key pair, Banxa uses the oldest one that has not been revoked; the Webhooks page in the dashboard shows which key that is.

Each webhook includes an `Authorization` header:

```
Authorization: Bearer {API_KEY}:{SIGNATURE}:{NONCE}
```

Banxa constructs the signature from:

```
POST\nYOUR_WEBHOOK_PATH\nNONCE\nPAYLOAD
```

The nonce Banxa sends is 16 digits
Banxa generates the webhook nonce as a Unix timestamp in **microseconds — 16 digits**, not the 13 digits of a millisecond timestamp:

|  | Value | Digits |
|  --- | --- | --- |
| What Banxa sends | `1785804345837761` | 16 |
| A millisecond timestamp | `1785804345837` | 13 |


A real header looks like this:

```
Authorization: Bearer pk_2f8c91ab4d7e:4a7f2c9e81b3d6058f1e2a7c4b9d3e6f8a1c5b2d7e4f9a3c6b8d1e5f2a7c4b9d:1785804345837761
```

Treat the nonce as an **opaque string**: read it from the `Authorization` header and pass it into the canonical string exactly as received. Do not parse it as a date, truncate it, convert it, or regenerate it — and do not validate it against a fixed digit length. Doing any of these produces a signature mismatch.

### Verification flow

1. Extract the `Authorization` header from the incoming request
2. Strip the `Bearer ` prefix and split on `:` to get `receivedKey`, `receivedSignature`, `nonce`
3. Recompute the expected signature using the same algorithm, your secret, and `YOUR_WEBHOOK_PATH`
4. Use a **timing-safe comparison** to check that `receivedSignature` matches — never use `==`


### Code examples

```python Python
import hmac

MY_WEBHOOK_PATH = '/webhooks/banxa'
KEY = '[YOUR_API_KEY]'
SECRET = '[YOUR_API_SECRET]'

def verify_webhook(auth_header, request_body):
    _, token = auth_header.split('Bearer ', 1)
    received_key, received_signature, nonce = token.split(':')

    data = f"POST\n{MY_WEBHOOK_PATH}\n{nonce}\n{request_body}"
    expected = hmac.new(SECRET.encode('utf-8'), data.encode('utf-8'), 'sha256').hexdigest()

    return hmac.compare_digest(received_signature, expected)
```

```javascript Node.js
const crypto = require('crypto');

const MY_WEBHOOK_PATH = '/webhooks/banxa';
const KEY = '[YOUR_API_KEY]';
const SECRET = '[YOUR_API_SECRET]';

function verifyWebhook(authHeader, requestBody) {
    const token = authHeader.replace('Bearer ', '');
    const [receivedKey, receivedSignature, nonce] = token.split(':');

    const data = `POST\n${MY_WEBHOOK_PATH}\n${nonce}\n${requestBody}`;
    const expected = crypto.createHmac('sha256', SECRET).update(data).digest('hex');

    const a = Buffer.from(receivedSignature);
    const b = Buffer.from(expected);
    // timingSafeEqual throws unless both buffers are the same length.
    return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```

```typescript TypeScript
import { createHmac, timingSafeEqual } from 'node:crypto';

const MY_WEBHOOK_PATH = '/webhooks/banxa';
const SECRET = '[YOUR_API_SECRET]';

export function verifyWebhook(authHeader: string, requestBody: string): boolean {
    const token = authHeader.replace('Bearer ', '');
    const [, receivedSignature, nonce] = token.split(':');
    if (!receivedSignature || !nonce) return false;

    const data = `POST\n${MY_WEBHOOK_PATH}\n${nonce}\n${requestBody}`;
    const expected = createHmac('sha256', SECRET).update(data).digest('hex');

    const a = Buffer.from(receivedSignature);
    const b = Buffer.from(expected);
    // timingSafeEqual throws unless both buffers are the same length.
    return a.length === b.length && timingSafeEqual(a, b);
}
```

```php PHP
<?php
$MY_WEBHOOK_PATH = '/webhooks/banxa';
$KEY = '[YOUR_API_KEY]';
$SECRET = '[YOUR_API_SECRET]';

function verifyWebhook($authHeader, $requestBody, $myWebhookPath, $key, $secret) {
    $token = str_replace('Bearer ', '', $authHeader);
    [$receivedKey, $receivedSignature, $nonce] = explode(':', $token);

    $data = implode("\n", ['POST', $myWebhookPath, $nonce, $requestBody]);
    $expected = hash_hmac('sha256', $data, $secret);

    return hash_equals($expected, $receivedSignature);
}
```

```java Java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.MessageDigest;
import java.util.Formatter;

private static final String MY_WEBHOOK_PATH = "/webhooks/banxa";
private static final String SECRET = "[YOUR_API_SECRET]";

public boolean verifyWebhook(String authHeader, String requestBody) throws Exception {
    String token = authHeader.replace("Bearer ", "");
    String[] parts = token.split(":");
    String nonce = parts[2];
    String receivedSignature = parts[1];

    String data = "POST\n" + MY_WEBHOOK_PATH + "\n" + nonce + "\n" + requestBody;
    SecretKeySpec signingKey = new SecretKeySpec(SECRET.getBytes(), "HmacSHA256");
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(signingKey);
    Formatter formatter = new Formatter();
    for (byte b : mac.doFinal(data.getBytes())) formatter.format("%02x", b);
    String expected = formatter.toString();

    return MessageDigest.isEqual(receivedSignature.getBytes(), expected.getBytes());
}
```

```csharp .NET
using System;
using System.Security.Cryptography;
using System.Text;

public static class BanxaWebhook
{
    private const string MyWebhookPath = "/webhooks/banxa";
    private const string Secret = "[YOUR_API_SECRET]";

    public static bool VerifyWebhook(string authHeader, string requestBody)
    {
        var token = authHeader.Replace("Bearer ", string.Empty);
        var parts = token.Split(':');
        if (parts.Length != 3) return false;

        var receivedSignature = parts[1];
        var nonce = parts[2];

        var data = $"POST\n{MyWebhookPath}\n{nonce}\n{requestBody}";
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(Secret));
        var expected = Convert.ToHexString(hmac.ComputeHash(Encoding.UTF8.GetBytes(data)))
                              .ToLowerInvariant();

        // FixedTimeEquals returns false on a length mismatch rather than throwing.
        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(receivedSignature),
            Encoding.UTF8.GetBytes(expected));
    }
}
```

```swift Swift
import CryptoKit

let MY_WEBHOOK_PATH = "/webhooks/banxa"
let SECRET = "[YOUR_API_SECRET]"

func verifyWebhook(authHeader: String, requestBody: String) -> Bool {
    let token = authHeader.replacingOccurrences(of: "Bearer ", with: "")
    let parts = token.split(separator: ":")
    guard parts.count == 3 else { return false }
    let nonce = String(parts[2])
    let receivedSignature = String(parts[1])

    let data = "POST\n\(MY_WEBHOOK_PATH)\n\(nonce)\n\(requestBody)"
    let secretKey = SymmetricKey(data: SECRET.data(using: .utf8)!)
    let expected = HMAC<SHA256>.authenticationCode(for: data.data(using: .utf8)!, using: secretKey)
        .map { String(format: "%02hhx", $0) }.joined()

    // Constant-time comparison — never use == on a signature.
    let a = Array(receivedSignature.utf8), b = Array(expected.utf8)
    guard a.count == b.count else { return false }
    var diff: UInt8 = 0
    for (x, y) in zip(a, b) { diff |= x ^ y }
    return diff == 0
}
```

```ruby Ruby
require 'openssl'

MY_WEBHOOK_PATH = '/webhooks/banxa'
SECRET = '[YOUR_API_SECRET]'

def verify_webhook(auth_header, request_body)
    token = auth_header.sub('Bearer ', '')
    received_key, received_signature, nonce = token.split(':')

    data = "POST\n#{MY_WEBHOOK_PATH}\n#{nonce}\n#{request_body}"
    expected = OpenSSL::HMAC.hexdigest('sha256', SECRET, data)

    ActiveSupport::SecurityUtils.secure_compare(received_signature, expected)
end
```