> For the complete documentation index, see [llms.txt](https://developers.unigox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.unigox.com/api-reference/webhooks.md).

# Webhooks

Signed notifications for orders, KYC/KYB, fiat accounts, business customers and wallet deposits. The system sends a signed HTTP POST to your configured webhook URL on every relevant event.

**Event model**

These event types are delivered:

| Event type                         | Fired when                                                                                                                                                                                                                                     |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `order.status.changed`             | An order transitions to a new status                                                                                                                                                                                                           |
| `order.refund.required`            | An order's crypto is stuck in escrow and only your signature can return it                                                                                                                                                                     |
| `user.kyc.updated`                 | A user's KYC verification is approved, declined or put on manual review                                                                                                                                                                        |
| `fiat_account.updated`             | An issued fiat account changes status. No money moved.                                                                                                                                                                                         |
| `fiat_account.deposit.received`    | Money arrived on an issued fiat account. Not sent for a credit matched to exactly one off-ramp paid through that account, which `order.own_account_payout.updated` covers. A business customer's account sends it with `holder_type: business` |
| `fiat_account.payment.sent`        | Money left a business customer's account                                                                                                                                                                                                       |
| `fiat_account.payment.updated`     | A transfer on a business customer's account reached a new status (`pending`, `confirmed`, `sent`, `blocked`, `refused`, `refunded`…)                                                                                                           |
| `business_customer.kyb.updated`    | A business customer's KYB status changed                                                                                                                                                                                                       |
| `order.own_account_payout.updated` | An off-ramp paid through the customer's own fiat account was sent on to the bank, or stopped on the account                                                                                                                                    |
| `wallet.linked`                    | An external-wallet customer linked their address                                                                                                                                                                                               |
| `wallet.deposit.received`          | A bridge payment was credited to a linked customer wallet on XAI                                                                                                                                                                               |
| `wallet.withdrawal.status.changed` | A customer withdrawal from an external wallet changed status                                                                                                                                                                                   |

**Customer wallet events**

`wallet.linked` carries `user_uuid`, `address` and `linked_at`. The link response and `GET /api/v1/partner/users/{user_uuid}/wallet` confirm the link even if that notification is not delivered. This event has no automatic delivery retry.

`wallet.deposit.received` reports the credited XAI token and amount, with the source transaction and XAI settlement transaction. It reports supported bridge credits to linked wallets, not every transfer into that wallet. It does not include a memo or memo-lock ID.

```json
{
  "event_id": "evt_dep_42_12345",
  "event_type": "wallet.deposit.received",
  "created_at": "2026-10-18T10:01:00Z",
  "data": {
    "deposit_id": "intent:12345",
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "address": "0x1111111111111111111111111111111111111111",
    "chain_id": "660279",
    "crypto_currency": "USDC",
    "token_address": "0x37bf70ee0dc89a408de31b79cccc3152f0c8af43",
    "amount": "1",
    "amount_atomic": "1000000",
    "source_chain_id": "8453",
    "source_tx_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "tx_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "credited_at": "2026-10-18T10:00:00Z"
  }
}
```

Register and enable your webhook before accepting deposits. Deposit notifications retry failed delivery with the same `event_id` (first retry after 30 s, the wait doubling up to 6 h, at most 10 attempts); `data.deposit_id` identifies the credited payment. Process each deposit once within your partner account and environment. Return a 2xx after accepting the event. Delivery is bounded; disabling a webhook does not queue a later replay. Both wallet events use the partner signature scheme described below. `created_at` and the delivery signature can change on retry; `credited_at` is the settlement time.

**Payload shape — the fiat account events**

```json
{
  "event_id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "fiat_account.deposit.received",
  "created_at": "2026-09-18T10:04:23Z",
  "data": {
    "fiat_account_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "holder_type": "retail",
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "transaction_id": "5f1b2c9a-1d44-4f0e-9c1a-2b5f0d7e9a31",
    "amount": "500.00",
    "currency": "EUR",
    "order_id": null
  }
}
```

`order_id` is the on-ramp this deposit funded, or `null` when it matched no order. The event is not sent for a credit matched to exactly one off-ramp paid through the customer's own fiat account (`payout_via_own_account: true`); `order.own_account_payout.updated` reports that money instead. Any other credit still sends it, including one held for review because it cannot be tied to a single order. `fiat_account.updated` carries `fiat_account_id`, `user_uuid`, `status` and `currency`. A business customer's account sends `fiat_account.deposit.received` (with `holder_type: business`) and `fiat_account.payment.sent` / `fiat_account.payment.updated` with a different `data`; see Business customers, Webhooks.

**Payload shape — `order.own_account_payout.updated`**

Sent only on an off-ramp paid through the customer's own fiat account (`payout_via_own_account: true`), when the onward payment to the bank you named reaches `sent_to_bank`, `held`, `under_review` or `left_on_account`, once per change of state. It does not change the order's `status`. The provider's payment into the customer's account, once matched to the order, does not send `fiat_account.deposit.received`.

```json
{
  "event_id": "evt_own_account_payout_1234_sent_to_bank_3f9a1c0b7d2e4a55",
  "event_type": "order.own_account_payout.updated",
  "created_at": "2026-10-16T12:00:00Z",
  "data": {
    "order_id": "9f1c6b7e-0000-4000-8000-000000000042",
    "user_uuid": "c0ffee00-0000-4000-8000-000000000001",
    "own_account_payout_status": "sent_to_bank",
    "fiat_account_id": "6b1d2c3e-0000-4000-8000-000000000007",
    "amount": "250.00",
    "currency": "EUR"
  }
}
```

`fiat_account_id` is omitted when the account is not one you can address by id. `amount` is a decimal string with at least two decimals.

All events share the same envelope (`event_id`, `event_type`, `created_at`, `data`) and the same signature scheme. The structure of the `data` object differs per event type.

**Payload shape — `order.status.changed`**

```json
{
  "event_id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "order.status.changed",
  "created_at": "2026-02-01T12:00:05Z",
  "data": {
    "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "crypto_received",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "crypto_amount": "101.5",
    "crypto_currency": "USDT",
    "partner_fee": "1",
    "partner_fee_pct": 1,
    "fiat_amount": "152880.00",
    "fiat_currency": "NGN",
    "provider": "p2p",
    "payment_details_id": "987"
  }
}
```

`user_id` is the customer's `user_uuid`.

**Payload shape — `order.refund.required`**

Fired when an off-ramp order has stopped without a payout and its crypto is still in escrow. This has its own event type because there is no status change to carry it: the order reads `cancelled` from the moment it stopped, exactly like an order whose refund was already paid out, so a listener filtering on status transitions would never learn that anything is owed. It is sent **at most once per order**, and the same information is on `GET /orders/{order_id}` for as long as it stays true.

The `data` object is the order.status.changed payload plus `action_required`.

```json
{
  "event_id": "evt_refund_required_b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "event_type": "order.refund.required",
  "created_at": "2026-09-09T09:14:00Z",
  "data": {
    "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "cancelled",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "crypto_amount": "1000.25",
    "crypto_currency": "USDT",
    "fiat_amount": "3070.50",
    "fiat_currency": "KWD",
    "provider": "p2p",
    "payment_details_id": "987",
    "action_required": {
      "type": "authorize_refund",
      "message": "This order ended without a payout and the crypto is still in escrow. ...",
      "endpoint": "POST /api/v1/partner/orders/{order_id}/authorize-refund"
    }
  }
}
```

Act on it with the refund pair: `GET /orders/{order_id}/refund-authorization-parameters` for the transaction to sign, then `POST /orders/{order_id}/authorize-refund` with the signature. Nobody else can produce that signature — the escrow needs two of its three owners, we hold one key and you hold the other.

**Payload shape — `user.kyc.updated`**

Fired when a user's KYC status changes — to `VERIFIED`, `REJECTED`, or to a manual compliance review hold (`UNDER_REVIEW`). Use this event to unlock order creation for the user on your side (only on `VERIFIED`; `UNDER_REVIEW` is not cleared).

```json
{
  "event_id": "evt_2d8418dd-e3a8-4463-a11e-6b54f354ca90",
  "event_type": "user.kyc.updated",
  "created_at": "2026-03-10T11:37:42Z",
  "data": {
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "kyc_status": "VERIFIED"
  }
}
```

When KYC is declined, `rejection_reasons` is included:

```json
{
  "event_id": "evt_fc75484d-b374-4d05-b54e-820f3dd80e6d",
  "event_type": "user.kyc.updated",
  "created_at": "2026-03-10T12:00:00Z",
  "data": {
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "kyc_status": "REJECTED",
    "rejection_reasons": ["Document expired", "Photo quality low"]
  }
}
```

When a customer is placed on a manual compliance review hold, `kyc_status` is `UNDER_REVIEW`:

```json
{
  "event_id": "evt_9a1c7f20-4d3b-4e88-9f2a-1b6d0c5e7a3f",
  "event_type": "user.kyc.updated",
  "created_at": "2026-03-10T12:05:00Z",
  "data": {
    "user_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "kyc_status": "UNDER_REVIEW"
  }
}
```

`kyc_status` values: `VERIFIED` | `REJECTED` | `UNDER_REVIEW`

`UNDER_REVIEW` is a manual compliance review: the customer is NOT cleared and can take up to 24 hours (unlike an automated check of a couple of minutes). Do not unlock order creation until `VERIFIED`.

**Signature verification**

Every delivery includes two headers for HMAC-SHA256 verification:

* `X-Unigox-Signature: sha256=<hex>` — HMAC of `"<timestamp>.<raw_body>"`
* `X-Unigox-Timestamp: <unix_seconds>`

Verification pseudocode:

```
expected = HMAC-SHA256(webhook_secret, "<timestamp>.<raw_body>")
valid    = constant_time_compare(expected, signature_from_header)
```

**Delivery guarantees**

* At-least-once delivery. Your endpoint may receive the same event more than once.
* De-duplicate by `event_id`.
* Respond with any 2xx status within 10 seconds to acknowledge receipt.

**Retry policy**

Failed deliveries (non-2xx or timeout) are retried with exponential backoff: 1 min → 5 min → 15 min → 1 h → 6 h → 12 h → 24 h (max 10 attempts over \~3.5 days).

**Partner-facing statuses** (`order.status.changed`)

| Status                                   | Description                                                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `created`                                | Order created                                                                                                 |
| `awaiting_liquidity_provider`            | Waiting for vendor match                                                                                      |
| `awaiting_crypto_transfer_authorization` | Partner must authorize crypto transfer                                                                        |
| `crypto_transfer_authorization_pending`  | Authorization submitted, awaiting on-chain confirmation                                                       |
| `price_changed_requote_needed`           | Slippage exceeded at initiation; create a new quote                                                           |
| `crypto_received`                        | Crypto received in escrow                                                                                     |
| `fiat_payment_started`                   | Buyer submitted fiat payment proof                                                                            |
| `fiat_payment_review_started`            | Payment proof under review                                                                                    |
| `awaiting_fiat_received_confirmation`    | Proof approved, awaiting seller confirmation                                                                  |
| `completed`                              | Order completed, crypto released                                                                              |
| `cancelled`                              | Order cancelled or payment declined                                                                           |
| `failed`                                 | Escrow error, or fiat-anchored safety bound exceeded (see below)                                              |
| `dispute_started`                        | Dispute opened                                                                                                |
| `settlement_in_progress`                 | Delayed settlement (T+1): the release of the crypto has started or is confirmed, and the fiat has not arrived |
| `returned`                               | Delayed settlement (T+1): the bank sent the payout back and no new attempt has been approved yet              |
| `awaiting_vendor_escrow_funding`         | On-ramp: vendor accepted, funding escrow with crypto                                                          |
| `awaiting_fiat_transfer`                 | On-ramp: crypto locked in escrow, waiting for the fiat payment                                                |
| `fiat_transfer_pending`                  | On-ramp: fiat payment confirmed, awaiting vendor confirmation of receipt                                      |
| `send_out_pending`                       | On-ramp send-out: cross-chain transfer in progress                                                            |
| `send_out_completed`                     | On-ramp send-out: delivered on the destination chain                                                          |
| `send_out_failed`                        | On-ramp send-out: cross-chain transfer failed; the on-ramp itself stays completed                             |

**Fiat-anchored safety bound failure**

For fiat-anchored off-ramp orders (`anchor_type: "fiat"`), if the crypto cost we quote exceeds 1.20× the expected amount at the time of settlement, the order moves to `failed` status asynchronously (not during `/initiate`). The deposit is automatically refunded from escrow back to the partner wallet. Create a new quote to retry the trade flow.

**Settlement notifications (recipient received the fiat)**

Some liquidity providers automatically confirm when the fiat payout reaches the recipient's bank account or mobile wallet. When the provider matched to an order supports this, the order moves to `completed` on its own and you receive an `order.status.changed` webhook with `status=completed` — that webhook is your signal that the recipient has actually received the money.

Whether the matched provider sends this is reported per order by the `has_fiat_settlement_notification` field on the **quote** and **order** responses:

* `true` — the matched provider sends an automatic settlement confirmation. You will receive the `completed` webhook once fiat is delivered; no manual action is needed.
* `false` — no automatic confirmation for this order. Confirm delivery yourself by calling `confirm-fiat-received` (or rely on your own banking/payment systems).

A delayed settlement (T+1) quote, and a T+1 order once a liquidity provider has accepted it, always read `true`: the fiat leg ends in the `completed` webhook, and `confirm-fiat-received` refuses it. Every order a liquidity provider has not accepted yet, T+1 included, reads `false`; read the flag again after acceptance.

To match **only** providers that send settlement notifications, pass `has_fiat_settlement_notification: true` in the quote request — providers that can't offer it are then excluded from matching.

Availability is provider- and corridor-dependent: not every currency has a provider that sends settlement notifications, so always read the flag on each quote rather than assuming it. Manual `confirm-fiat-received` and the automatic confirmation are mutually idempotent — whichever happens first wins and the other is a safe no-op.

## Get webhook config

> Returns the current webhook configuration for your partner account,\
> including the URL and whether the webhook is enabled.<br>

````json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Signed notifications for orders, KYC/KYB, fiat accounts, business customers and wallet deposits.\nThe system sends a signed HTTP POST to your configured webhook URL on every relevant event.\n\n**Event model**\n\nThese event types are delivered:\n\n| Event type | Fired when |\n|---|---|\n| `order.status.changed` | An order transitions to a new status |\n| `order.refund.required` | An order's crypto is stuck in escrow and only your signature can return it |\n| `user.kyc.updated` | A user's KYC verification is approved, declined or put on manual review |\n| `fiat_account.updated` | An issued fiat account changes status. No money moved. |\n| `fiat_account.deposit.received` | Money arrived on an issued fiat account. Not sent for a credit matched to exactly one off-ramp paid through that account, which `order.own_account_payout.updated` covers. A business customer's account sends it with `holder_type: business` |\n| `fiat_account.payment.sent` | Money left a business customer's account |\n| `fiat_account.payment.updated` | A transfer on a business customer's account reached a new status (`pending`, `confirmed`, `sent`, `blocked`, `refused`, `refunded`…) |\n| `business_customer.kyb.updated` | A business customer's KYB status changed |\n| `order.own_account_payout.updated` | An off-ramp paid through the customer's own fiat account was sent on to the bank, or stopped on the account |\n| `wallet.linked` | An external-wallet customer linked their address |\n| `wallet.deposit.received` | A bridge payment was credited to a linked customer wallet on XAI |\n| `wallet.withdrawal.status.changed` | A customer withdrawal from an external wallet changed status |\n\n**Customer wallet events**\n\n`wallet.linked` carries `user_uuid`, `address` and `linked_at`. The link response and\n`GET /api/v1/partner/users/{user_uuid}/wallet` confirm the link even if that notification\nis not delivered. This event has no automatic delivery retry.\n\n`wallet.deposit.received` reports the credited XAI token and amount, with the source\ntransaction and XAI settlement transaction. It reports supported bridge credits to linked\nwallets, not every transfer into that wallet. It does not include a memo or memo-lock ID.\n\n```json\n{\n  \"event_id\": \"evt_dep_42_12345\",\n  \"event_type\": \"wallet.deposit.received\",\n  \"created_at\": \"2026-10-18T10:01:00Z\",\n  \"data\": {\n    \"deposit_id\": \"intent:12345\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"address\": \"0x1111111111111111111111111111111111111111\",\n    \"chain_id\": \"660279\",\n    \"crypto_currency\": \"USDC\",\n    \"token_address\": \"0x37bf70ee0dc89a408de31b79cccc3152f0c8af43\",\n    \"amount\": \"1\",\n    \"amount_atomic\": \"1000000\",\n    \"source_chain_id\": \"8453\",\n    \"source_tx_hash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n    \"tx_hash\": \"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n    \"credited_at\": \"2026-10-18T10:00:00Z\"\n  }\n}\n```\n\nRegister and enable your webhook before accepting deposits. Deposit notifications retry\nfailed delivery with the same `event_id` (first retry after 30 s, the wait doubling up to 6 h, at most\n10 attempts); `data.deposit_id` identifies the credited payment.\nProcess each deposit once within your partner account and environment. Return a 2xx after\naccepting the event. Delivery is bounded; disabling a webhook does not queue a later replay.\nBoth wallet events use the partner signature scheme described below. `created_at` and the\ndelivery signature can change on retry; `credited_at` is the settlement time.\n\n**Payload shape — the fiat account events**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"fiat_account.deposit.received\",\n  \"created_at\": \"2026-09-18T10:04:23Z\",\n  \"data\": {\n    \"fiat_account_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"holder_type\": \"retail\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"transaction_id\": \"5f1b2c9a-1d44-4f0e-9c1a-2b5f0d7e9a31\",\n    \"amount\": \"500.00\",\n    \"currency\": \"EUR\",\n    \"order_id\": null\n  }\n}\n```\n\n`order_id` is the on-ramp this deposit funded, or `null` when it matched no order.\nThe event is not sent for a credit matched to exactly one off-ramp paid through the customer's\nown fiat account (`payout_via_own_account: true`); `order.own_account_payout.updated` reports\nthat money instead. Any other credit still sends it, including one held for review because it\ncannot be tied to a single order.\n`fiat_account.updated` carries `fiat_account_id`, `user_uuid`, `status` and `currency`.\nA business customer's account sends `fiat_account.deposit.received` (with `holder_type: business`)\nand `fiat_account.payment.sent` / `fiat_account.payment.updated` with a different `data`; see\nBusiness customers, Webhooks.\n\n**Payload shape — `order.own_account_payout.updated`**\n\nSent only on an off-ramp paid through the customer's own fiat account\n(`payout_via_own_account: true`), when the onward payment to the bank you named reaches\n`sent_to_bank`, `held`, `under_review` or `left_on_account`, once per change of state. It does\nnot change the order's `status`. The provider's payment into the customer's account, once\nmatched to the order, does not send `fiat_account.deposit.received`.\n\n```json\n{\n  \"event_id\": \"evt_own_account_payout_1234_sent_to_bank_3f9a1c0b7d2e4a55\",\n  \"event_type\": \"order.own_account_payout.updated\",\n  \"created_at\": \"2026-10-16T12:00:00Z\",\n  \"data\": {\n    \"order_id\": \"9f1c6b7e-0000-4000-8000-000000000042\",\n    \"user_uuid\": \"c0ffee00-0000-4000-8000-000000000001\",\n    \"own_account_payout_status\": \"sent_to_bank\",\n    \"fiat_account_id\": \"6b1d2c3e-0000-4000-8000-000000000007\",\n    \"amount\": \"250.00\",\n    \"currency\": \"EUR\"\n  }\n}\n```\n\n`fiat_account_id` is omitted when the account is not one you can address by id. `amount` is a\ndecimal string with at least two decimals.\n\nAll events share the same envelope (`event_id`, `event_type`, `created_at`, `data`)\nand the same signature scheme. The structure of the `data` object differs per event type.\n\n**Payload shape — `order.status.changed`**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"order.status.changed\",\n  \"created_at\": \"2026-02-01T12:00:05Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"crypto_received\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"101.5\",\n    \"crypto_currency\": \"USDT\",\n    \"partner_fee\": \"1\",\n    \"partner_fee_pct\": 1,\n    \"fiat_amount\": \"152880.00\",\n    \"fiat_currency\": \"NGN\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\"\n  }\n}\n```\n\n`user_id` is the customer's `user_uuid`.\n\n**Payload shape — `order.refund.required`**\n\nFired when an off-ramp order has stopped without a payout and its crypto is still in escrow.\nThis has its own event type because there is no status change to carry it: the order reads\n`cancelled` from the moment it stopped, exactly like an order whose refund was already paid out,\nso a listener filtering on status transitions would never learn that anything is owed. It is\nsent **at most once per order**, and the same information is on `GET /orders/{order_id}` for as\nlong as it stays true.\n\nThe `data` object is the order.status.changed payload plus `action_required`.\n\n```json\n{\n  \"event_id\": \"evt_refund_required_b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n  \"event_type\": \"order.refund.required\",\n  \"created_at\": \"2026-09-09T09:14:00Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"cancelled\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"1000.25\",\n    \"crypto_currency\": \"USDT\",\n    \"fiat_amount\": \"3070.50\",\n    \"fiat_currency\": \"KWD\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\",\n    \"action_required\": {\n      \"type\": \"authorize_refund\",\n      \"message\": \"This order ended without a payout and the crypto is still in escrow. ...\",\n      \"endpoint\": \"POST /api/v1/partner/orders/{order_id}/authorize-refund\"\n    }\n  }\n}\n```\n\nAct on it with the refund pair: `GET /orders/{order_id}/refund-authorization-parameters` for the\ntransaction to sign, then `POST /orders/{order_id}/authorize-refund` with the signature. Nobody\nelse can produce that signature — the escrow needs two of its three owners, we hold one key and\nyou hold the other.\n\n**Payload shape — `user.kyc.updated`**\n\nFired when a user's KYC status changes — to `VERIFIED`, `REJECTED`, or to a manual compliance\nreview hold (`UNDER_REVIEW`). Use this event to unlock order creation for the user on your side\n(only on `VERIFIED`; `UNDER_REVIEW` is not cleared).\n\n```json\n{\n  \"event_id\": \"evt_2d8418dd-e3a8-4463-a11e-6b54f354ca90\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T11:37:42Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"VERIFIED\"\n  }\n}\n```\n\nWhen KYC is declined, `rejection_reasons` is included:\n\n```json\n{\n  \"event_id\": \"evt_fc75484d-b374-4d05-b54e-820f3dd80e6d\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:00:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"REJECTED\",\n    \"rejection_reasons\": [\"Document expired\", \"Photo quality low\"]\n  }\n}\n```\n\nWhen a customer is placed on a manual compliance review hold, `kyc_status` is `UNDER_REVIEW`:\n\n```json\n{\n  \"event_id\": \"evt_9a1c7f20-4d3b-4e88-9f2a-1b6d0c5e7a3f\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:05:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"UNDER_REVIEW\"\n  }\n}\n```\n\n`kyc_status` values: `VERIFIED` | `REJECTED` | `UNDER_REVIEW`\n\n`UNDER_REVIEW` is a manual compliance review: the customer is NOT cleared and can take up to\n24 hours (unlike an automated check of a couple of minutes). Do not unlock order creation until\n`VERIFIED`.\n\n**Signature verification**\n\nEvery delivery includes two headers for HMAC-SHA256 verification:\n- `X-Unigox-Signature: sha256=<hex>` — HMAC of `\"<timestamp>.<raw_body>\"`\n- `X-Unigox-Timestamp: <unix_seconds>`\n\nVerification pseudocode:\n```\nexpected = HMAC-SHA256(webhook_secret, \"<timestamp>.<raw_body>\")\nvalid    = constant_time_compare(expected, signature_from_header)\n```\n\n**Delivery guarantees**\n\n- At-least-once delivery. Your endpoint may receive the same event more than once.\n- De-duplicate by `event_id`.\n- Respond with any 2xx status within 10 seconds to acknowledge receipt.\n\n**Retry policy**\n\nFailed deliveries (non-2xx or timeout) are retried with exponential backoff:\n1 min → 5 min → 15 min → 1 h → 6 h → 12 h → 24 h (max 10 attempts over ~3.5 days).\n\n**Partner-facing statuses** (`order.status.changed`)\n\n| Status | Description |\n|---|---|\n| `created` | Order created |\n| `awaiting_liquidity_provider` | Waiting for vendor match |\n| `awaiting_crypto_transfer_authorization` | Partner must authorize crypto transfer |\n| `crypto_transfer_authorization_pending` | Authorization submitted, awaiting on-chain confirmation |\n| `price_changed_requote_needed` | Slippage exceeded at initiation; create a new quote |\n| `crypto_received` | Crypto received in escrow |\n| `fiat_payment_started` | Buyer submitted fiat payment proof |\n| `fiat_payment_review_started` | Payment proof under review |\n| `awaiting_fiat_received_confirmation` | Proof approved, awaiting seller confirmation |\n| `completed` | Order completed, crypto released |\n| `cancelled` | Order cancelled or payment declined |\n| `failed` | Escrow error, or fiat-anchored safety bound exceeded (see below) |\n| `dispute_started` | Dispute opened |\n| `settlement_in_progress` | Delayed settlement (T+1): the release of the crypto has started or is confirmed, and the fiat has not arrived |\n| `returned` | Delayed settlement (T+1): the bank sent the payout back and no new attempt has been approved yet |\n| `awaiting_vendor_escrow_funding` | On-ramp: vendor accepted, funding escrow with crypto |\n| `awaiting_fiat_transfer` | On-ramp: crypto locked in escrow, waiting for the fiat payment |\n| `fiat_transfer_pending` | On-ramp: fiat payment confirmed, awaiting vendor confirmation of receipt |\n| `send_out_pending` | On-ramp send-out: cross-chain transfer in progress |\n| `send_out_completed` | On-ramp send-out: delivered on the destination chain |\n| `send_out_failed` | On-ramp send-out: cross-chain transfer failed; the on-ramp itself stays completed |\n\n**Fiat-anchored safety bound failure**\n\nFor fiat-anchored off-ramp orders (`anchor_type: \"fiat\"`), if the crypto cost we quote exceeds\n1.20× the expected amount at the time of settlement, the order moves to `failed` status asynchronously\n(not during `/initiate`). The deposit is automatically refunded from escrow back to the partner wallet.\nCreate a new quote to retry the trade flow.\n\n**Settlement notifications (recipient received the fiat)**\n\nSome liquidity providers automatically confirm when the fiat payout reaches the\nrecipient's bank account or mobile wallet. When the provider matched to an order\nsupports this, the order moves to `completed` on its own and you receive an\n`order.status.changed` webhook with `status=completed` — that webhook is your signal\nthat the recipient has actually received the money.\n\nWhether the matched provider sends this is reported per order by the\n`has_fiat_settlement_notification` field on the **quote** and **order** responses:\n\n- `true` — the matched provider sends an automatic settlement confirmation. You will\n  receive the `completed` webhook once fiat is delivered; no manual action is needed.\n- `false` — no automatic confirmation for this order. Confirm delivery yourself by\n  calling `confirm-fiat-received` (or rely on your own banking/payment systems).\n\nA delayed settlement (T+1) quote, and a T+1 order once a liquidity provider has accepted\nit, always read `true`: the fiat leg ends in the `completed` webhook, and\n`confirm-fiat-received` refuses it. Every order a liquidity provider has not accepted yet,\nT+1 included, reads `false`; read the flag again after acceptance.\n\nTo match **only** providers that send settlement notifications, pass\n`has_fiat_settlement_notification: true` in the quote request — providers that can't\noffer it are then excluded from matching.\n\nAvailability is provider- and corridor-dependent: not every currency has a provider\nthat sends settlement notifications, so always read the flag on each quote rather than\nassuming it. Manual `confirm-fiat-received` and the automatic confirmation are mutually\nidempotent — whichever happens first wins and the other is a safe no-op.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"WebhookConfigResponse":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"Currently configured webhook URL (null if not set)"},"enabled":{"type":"boolean","description":"Whether webhook delivery is active"}}}}},"paths":{"/api/v1/partner/webhooks":{"get":{"tags":["Webhooks"],"summary":"Get webhook config","description":"Returns the current webhook configuration for your partner account,\nincluding the URL and whether the webhook is enabled.\n","operationId":"getWebhook","responses":{"200":{"description":"Webhook configuration retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookConfigResponse"}}}]}}}},"401":{"description":"Unauthorized — invalid or missing API key"}}}}}}
````

## Register webhook URL

> Register or update the webhook URL for your partner account. The URL must use HTTPS.\
> Once registered, the webhook is automatically enabled and will start receiving order status events.<br>

````json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Signed notifications for orders, KYC/KYB, fiat accounts, business customers and wallet deposits.\nThe system sends a signed HTTP POST to your configured webhook URL on every relevant event.\n\n**Event model**\n\nThese event types are delivered:\n\n| Event type | Fired when |\n|---|---|\n| `order.status.changed` | An order transitions to a new status |\n| `order.refund.required` | An order's crypto is stuck in escrow and only your signature can return it |\n| `user.kyc.updated` | A user's KYC verification is approved, declined or put on manual review |\n| `fiat_account.updated` | An issued fiat account changes status. No money moved. |\n| `fiat_account.deposit.received` | Money arrived on an issued fiat account. Not sent for a credit matched to exactly one off-ramp paid through that account, which `order.own_account_payout.updated` covers. A business customer's account sends it with `holder_type: business` |\n| `fiat_account.payment.sent` | Money left a business customer's account |\n| `fiat_account.payment.updated` | A transfer on a business customer's account reached a new status (`pending`, `confirmed`, `sent`, `blocked`, `refused`, `refunded`…) |\n| `business_customer.kyb.updated` | A business customer's KYB status changed |\n| `order.own_account_payout.updated` | An off-ramp paid through the customer's own fiat account was sent on to the bank, or stopped on the account |\n| `wallet.linked` | An external-wallet customer linked their address |\n| `wallet.deposit.received` | A bridge payment was credited to a linked customer wallet on XAI |\n| `wallet.withdrawal.status.changed` | A customer withdrawal from an external wallet changed status |\n\n**Customer wallet events**\n\n`wallet.linked` carries `user_uuid`, `address` and `linked_at`. The link response and\n`GET /api/v1/partner/users/{user_uuid}/wallet` confirm the link even if that notification\nis not delivered. This event has no automatic delivery retry.\n\n`wallet.deposit.received` reports the credited XAI token and amount, with the source\ntransaction and XAI settlement transaction. It reports supported bridge credits to linked\nwallets, not every transfer into that wallet. It does not include a memo or memo-lock ID.\n\n```json\n{\n  \"event_id\": \"evt_dep_42_12345\",\n  \"event_type\": \"wallet.deposit.received\",\n  \"created_at\": \"2026-10-18T10:01:00Z\",\n  \"data\": {\n    \"deposit_id\": \"intent:12345\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"address\": \"0x1111111111111111111111111111111111111111\",\n    \"chain_id\": \"660279\",\n    \"crypto_currency\": \"USDC\",\n    \"token_address\": \"0x37bf70ee0dc89a408de31b79cccc3152f0c8af43\",\n    \"amount\": \"1\",\n    \"amount_atomic\": \"1000000\",\n    \"source_chain_id\": \"8453\",\n    \"source_tx_hash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n    \"tx_hash\": \"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n    \"credited_at\": \"2026-10-18T10:00:00Z\"\n  }\n}\n```\n\nRegister and enable your webhook before accepting deposits. Deposit notifications retry\nfailed delivery with the same `event_id` (first retry after 30 s, the wait doubling up to 6 h, at most\n10 attempts); `data.deposit_id` identifies the credited payment.\nProcess each deposit once within your partner account and environment. Return a 2xx after\naccepting the event. Delivery is bounded; disabling a webhook does not queue a later replay.\nBoth wallet events use the partner signature scheme described below. `created_at` and the\ndelivery signature can change on retry; `credited_at` is the settlement time.\n\n**Payload shape — the fiat account events**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"fiat_account.deposit.received\",\n  \"created_at\": \"2026-09-18T10:04:23Z\",\n  \"data\": {\n    \"fiat_account_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"holder_type\": \"retail\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"transaction_id\": \"5f1b2c9a-1d44-4f0e-9c1a-2b5f0d7e9a31\",\n    \"amount\": \"500.00\",\n    \"currency\": \"EUR\",\n    \"order_id\": null\n  }\n}\n```\n\n`order_id` is the on-ramp this deposit funded, or `null` when it matched no order.\nThe event is not sent for a credit matched to exactly one off-ramp paid through the customer's\nown fiat account (`payout_via_own_account: true`); `order.own_account_payout.updated` reports\nthat money instead. Any other credit still sends it, including one held for review because it\ncannot be tied to a single order.\n`fiat_account.updated` carries `fiat_account_id`, `user_uuid`, `status` and `currency`.\nA business customer's account sends `fiat_account.deposit.received` (with `holder_type: business`)\nand `fiat_account.payment.sent` / `fiat_account.payment.updated` with a different `data`; see\nBusiness customers, Webhooks.\n\n**Payload shape — `order.own_account_payout.updated`**\n\nSent only on an off-ramp paid through the customer's own fiat account\n(`payout_via_own_account: true`), when the onward payment to the bank you named reaches\n`sent_to_bank`, `held`, `under_review` or `left_on_account`, once per change of state. It does\nnot change the order's `status`. The provider's payment into the customer's account, once\nmatched to the order, does not send `fiat_account.deposit.received`.\n\n```json\n{\n  \"event_id\": \"evt_own_account_payout_1234_sent_to_bank_3f9a1c0b7d2e4a55\",\n  \"event_type\": \"order.own_account_payout.updated\",\n  \"created_at\": \"2026-10-16T12:00:00Z\",\n  \"data\": {\n    \"order_id\": \"9f1c6b7e-0000-4000-8000-000000000042\",\n    \"user_uuid\": \"c0ffee00-0000-4000-8000-000000000001\",\n    \"own_account_payout_status\": \"sent_to_bank\",\n    \"fiat_account_id\": \"6b1d2c3e-0000-4000-8000-000000000007\",\n    \"amount\": \"250.00\",\n    \"currency\": \"EUR\"\n  }\n}\n```\n\n`fiat_account_id` is omitted when the account is not one you can address by id. `amount` is a\ndecimal string with at least two decimals.\n\nAll events share the same envelope (`event_id`, `event_type`, `created_at`, `data`)\nand the same signature scheme. The structure of the `data` object differs per event type.\n\n**Payload shape — `order.status.changed`**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"order.status.changed\",\n  \"created_at\": \"2026-02-01T12:00:05Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"crypto_received\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"101.5\",\n    \"crypto_currency\": \"USDT\",\n    \"partner_fee\": \"1\",\n    \"partner_fee_pct\": 1,\n    \"fiat_amount\": \"152880.00\",\n    \"fiat_currency\": \"NGN\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\"\n  }\n}\n```\n\n`user_id` is the customer's `user_uuid`.\n\n**Payload shape — `order.refund.required`**\n\nFired when an off-ramp order has stopped without a payout and its crypto is still in escrow.\nThis has its own event type because there is no status change to carry it: the order reads\n`cancelled` from the moment it stopped, exactly like an order whose refund was already paid out,\nso a listener filtering on status transitions would never learn that anything is owed. It is\nsent **at most once per order**, and the same information is on `GET /orders/{order_id}` for as\nlong as it stays true.\n\nThe `data` object is the order.status.changed payload plus `action_required`.\n\n```json\n{\n  \"event_id\": \"evt_refund_required_b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n  \"event_type\": \"order.refund.required\",\n  \"created_at\": \"2026-09-09T09:14:00Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"cancelled\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"1000.25\",\n    \"crypto_currency\": \"USDT\",\n    \"fiat_amount\": \"3070.50\",\n    \"fiat_currency\": \"KWD\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\",\n    \"action_required\": {\n      \"type\": \"authorize_refund\",\n      \"message\": \"This order ended without a payout and the crypto is still in escrow. ...\",\n      \"endpoint\": \"POST /api/v1/partner/orders/{order_id}/authorize-refund\"\n    }\n  }\n}\n```\n\nAct on it with the refund pair: `GET /orders/{order_id}/refund-authorization-parameters` for the\ntransaction to sign, then `POST /orders/{order_id}/authorize-refund` with the signature. Nobody\nelse can produce that signature — the escrow needs two of its three owners, we hold one key and\nyou hold the other.\n\n**Payload shape — `user.kyc.updated`**\n\nFired when a user's KYC status changes — to `VERIFIED`, `REJECTED`, or to a manual compliance\nreview hold (`UNDER_REVIEW`). Use this event to unlock order creation for the user on your side\n(only on `VERIFIED`; `UNDER_REVIEW` is not cleared).\n\n```json\n{\n  \"event_id\": \"evt_2d8418dd-e3a8-4463-a11e-6b54f354ca90\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T11:37:42Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"VERIFIED\"\n  }\n}\n```\n\nWhen KYC is declined, `rejection_reasons` is included:\n\n```json\n{\n  \"event_id\": \"evt_fc75484d-b374-4d05-b54e-820f3dd80e6d\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:00:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"REJECTED\",\n    \"rejection_reasons\": [\"Document expired\", \"Photo quality low\"]\n  }\n}\n```\n\nWhen a customer is placed on a manual compliance review hold, `kyc_status` is `UNDER_REVIEW`:\n\n```json\n{\n  \"event_id\": \"evt_9a1c7f20-4d3b-4e88-9f2a-1b6d0c5e7a3f\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:05:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"UNDER_REVIEW\"\n  }\n}\n```\n\n`kyc_status` values: `VERIFIED` | `REJECTED` | `UNDER_REVIEW`\n\n`UNDER_REVIEW` is a manual compliance review: the customer is NOT cleared and can take up to\n24 hours (unlike an automated check of a couple of minutes). Do not unlock order creation until\n`VERIFIED`.\n\n**Signature verification**\n\nEvery delivery includes two headers for HMAC-SHA256 verification:\n- `X-Unigox-Signature: sha256=<hex>` — HMAC of `\"<timestamp>.<raw_body>\"`\n- `X-Unigox-Timestamp: <unix_seconds>`\n\nVerification pseudocode:\n```\nexpected = HMAC-SHA256(webhook_secret, \"<timestamp>.<raw_body>\")\nvalid    = constant_time_compare(expected, signature_from_header)\n```\n\n**Delivery guarantees**\n\n- At-least-once delivery. Your endpoint may receive the same event more than once.\n- De-duplicate by `event_id`.\n- Respond with any 2xx status within 10 seconds to acknowledge receipt.\n\n**Retry policy**\n\nFailed deliveries (non-2xx or timeout) are retried with exponential backoff:\n1 min → 5 min → 15 min → 1 h → 6 h → 12 h → 24 h (max 10 attempts over ~3.5 days).\n\n**Partner-facing statuses** (`order.status.changed`)\n\n| Status | Description |\n|---|---|\n| `created` | Order created |\n| `awaiting_liquidity_provider` | Waiting for vendor match |\n| `awaiting_crypto_transfer_authorization` | Partner must authorize crypto transfer |\n| `crypto_transfer_authorization_pending` | Authorization submitted, awaiting on-chain confirmation |\n| `price_changed_requote_needed` | Slippage exceeded at initiation; create a new quote |\n| `crypto_received` | Crypto received in escrow |\n| `fiat_payment_started` | Buyer submitted fiat payment proof |\n| `fiat_payment_review_started` | Payment proof under review |\n| `awaiting_fiat_received_confirmation` | Proof approved, awaiting seller confirmation |\n| `completed` | Order completed, crypto released |\n| `cancelled` | Order cancelled or payment declined |\n| `failed` | Escrow error, or fiat-anchored safety bound exceeded (see below) |\n| `dispute_started` | Dispute opened |\n| `settlement_in_progress` | Delayed settlement (T+1): the release of the crypto has started or is confirmed, and the fiat has not arrived |\n| `returned` | Delayed settlement (T+1): the bank sent the payout back and no new attempt has been approved yet |\n| `awaiting_vendor_escrow_funding` | On-ramp: vendor accepted, funding escrow with crypto |\n| `awaiting_fiat_transfer` | On-ramp: crypto locked in escrow, waiting for the fiat payment |\n| `fiat_transfer_pending` | On-ramp: fiat payment confirmed, awaiting vendor confirmation of receipt |\n| `send_out_pending` | On-ramp send-out: cross-chain transfer in progress |\n| `send_out_completed` | On-ramp send-out: delivered on the destination chain |\n| `send_out_failed` | On-ramp send-out: cross-chain transfer failed; the on-ramp itself stays completed |\n\n**Fiat-anchored safety bound failure**\n\nFor fiat-anchored off-ramp orders (`anchor_type: \"fiat\"`), if the crypto cost we quote exceeds\n1.20× the expected amount at the time of settlement, the order moves to `failed` status asynchronously\n(not during `/initiate`). The deposit is automatically refunded from escrow back to the partner wallet.\nCreate a new quote to retry the trade flow.\n\n**Settlement notifications (recipient received the fiat)**\n\nSome liquidity providers automatically confirm when the fiat payout reaches the\nrecipient's bank account or mobile wallet. When the provider matched to an order\nsupports this, the order moves to `completed` on its own and you receive an\n`order.status.changed` webhook with `status=completed` — that webhook is your signal\nthat the recipient has actually received the money.\n\nWhether the matched provider sends this is reported per order by the\n`has_fiat_settlement_notification` field on the **quote** and **order** responses:\n\n- `true` — the matched provider sends an automatic settlement confirmation. You will\n  receive the `completed` webhook once fiat is delivered; no manual action is needed.\n- `false` — no automatic confirmation for this order. Confirm delivery yourself by\n  calling `confirm-fiat-received` (or rely on your own banking/payment systems).\n\nA delayed settlement (T+1) quote, and a T+1 order once a liquidity provider has accepted\nit, always read `true`: the fiat leg ends in the `completed` webhook, and\n`confirm-fiat-received` refuses it. Every order a liquidity provider has not accepted yet,\nT+1 included, reads `false`; read the flag again after acceptance.\n\nTo match **only** providers that send settlement notifications, pass\n`has_fiat_settlement_notification: true` in the quote request — providers that can't\noffer it are then excluded from matching.\n\nAvailability is provider- and corridor-dependent: not every currency has a provider\nthat sends settlement notifications, so always read the flag on each quote rather than\nassuming it. Manual `confirm-fiat-received` and the automatic confirmation are mutually\nidempotent — whichever happens first wins and the other is a safe no-op.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"RegisterWebhookRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS URL that will receive webhook events"}}},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"WebhookConfigResponse":{"type":"object","properties":{"url":{"type":"string","nullable":true,"description":"Currently configured webhook URL (null if not set)"},"enabled":{"type":"boolean","description":"Whether webhook delivery is active"}}}}},"paths":{"/api/v1/partner/webhooks":{"post":{"tags":["Webhooks"],"summary":"Register webhook URL","description":"Register or update the webhook URL for your partner account. The URL must use HTTPS.\nOnce registered, the webhook is automatically enabled and will start receiving order status events.\n","operationId":"registerWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterWebhookRequest"}}}},"responses":{"200":{"description":"Webhook registered successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookConfigResponse"}}}]}}}},"400":{"description":"Bad request — missing or invalid URL.\n\nThis endpoint answers with a bare message string under `error`, not the\n`{\"success\": false, \"error\": {\"code\", \"message\"}}` object the off-ramp and order\nendpoints use, and not the `data.error_key` shape. Read `error` as text; there is no code\nto branch on.\n","content":{"application/json":{"schema":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"string","description":"Human-readable message. Not an object, and not a stable key."}}}}}},"401":{"description":"Unauthorized — invalid or missing API key"}}}}}}
````

## Delete webhook

> Remove the webhook URL and disable webhook delivery for your partner account.\
> No further events will be sent until a new URL is registered.<br>

````json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Signed notifications for orders, KYC/KYB, fiat accounts, business customers and wallet deposits.\nThe system sends a signed HTTP POST to your configured webhook URL on every relevant event.\n\n**Event model**\n\nThese event types are delivered:\n\n| Event type | Fired when |\n|---|---|\n| `order.status.changed` | An order transitions to a new status |\n| `order.refund.required` | An order's crypto is stuck in escrow and only your signature can return it |\n| `user.kyc.updated` | A user's KYC verification is approved, declined or put on manual review |\n| `fiat_account.updated` | An issued fiat account changes status. No money moved. |\n| `fiat_account.deposit.received` | Money arrived on an issued fiat account. Not sent for a credit matched to exactly one off-ramp paid through that account, which `order.own_account_payout.updated` covers. A business customer's account sends it with `holder_type: business` |\n| `fiat_account.payment.sent` | Money left a business customer's account |\n| `fiat_account.payment.updated` | A transfer on a business customer's account reached a new status (`pending`, `confirmed`, `sent`, `blocked`, `refused`, `refunded`…) |\n| `business_customer.kyb.updated` | A business customer's KYB status changed |\n| `order.own_account_payout.updated` | An off-ramp paid through the customer's own fiat account was sent on to the bank, or stopped on the account |\n| `wallet.linked` | An external-wallet customer linked their address |\n| `wallet.deposit.received` | A bridge payment was credited to a linked customer wallet on XAI |\n| `wallet.withdrawal.status.changed` | A customer withdrawal from an external wallet changed status |\n\n**Customer wallet events**\n\n`wallet.linked` carries `user_uuid`, `address` and `linked_at`. The link response and\n`GET /api/v1/partner/users/{user_uuid}/wallet` confirm the link even if that notification\nis not delivered. This event has no automatic delivery retry.\n\n`wallet.deposit.received` reports the credited XAI token and amount, with the source\ntransaction and XAI settlement transaction. It reports supported bridge credits to linked\nwallets, not every transfer into that wallet. It does not include a memo or memo-lock ID.\n\n```json\n{\n  \"event_id\": \"evt_dep_42_12345\",\n  \"event_type\": \"wallet.deposit.received\",\n  \"created_at\": \"2026-10-18T10:01:00Z\",\n  \"data\": {\n    \"deposit_id\": \"intent:12345\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"address\": \"0x1111111111111111111111111111111111111111\",\n    \"chain_id\": \"660279\",\n    \"crypto_currency\": \"USDC\",\n    \"token_address\": \"0x37bf70ee0dc89a408de31b79cccc3152f0c8af43\",\n    \"amount\": \"1\",\n    \"amount_atomic\": \"1000000\",\n    \"source_chain_id\": \"8453\",\n    \"source_tx_hash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n    \"tx_hash\": \"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n    \"credited_at\": \"2026-10-18T10:00:00Z\"\n  }\n}\n```\n\nRegister and enable your webhook before accepting deposits. Deposit notifications retry\nfailed delivery with the same `event_id` (first retry after 30 s, the wait doubling up to 6 h, at most\n10 attempts); `data.deposit_id` identifies the credited payment.\nProcess each deposit once within your partner account and environment. Return a 2xx after\naccepting the event. Delivery is bounded; disabling a webhook does not queue a later replay.\nBoth wallet events use the partner signature scheme described below. `created_at` and the\ndelivery signature can change on retry; `credited_at` is the settlement time.\n\n**Payload shape — the fiat account events**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"fiat_account.deposit.received\",\n  \"created_at\": \"2026-09-18T10:04:23Z\",\n  \"data\": {\n    \"fiat_account_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"holder_type\": \"retail\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"transaction_id\": \"5f1b2c9a-1d44-4f0e-9c1a-2b5f0d7e9a31\",\n    \"amount\": \"500.00\",\n    \"currency\": \"EUR\",\n    \"order_id\": null\n  }\n}\n```\n\n`order_id` is the on-ramp this deposit funded, or `null` when it matched no order.\nThe event is not sent for a credit matched to exactly one off-ramp paid through the customer's\nown fiat account (`payout_via_own_account: true`); `order.own_account_payout.updated` reports\nthat money instead. Any other credit still sends it, including one held for review because it\ncannot be tied to a single order.\n`fiat_account.updated` carries `fiat_account_id`, `user_uuid`, `status` and `currency`.\nA business customer's account sends `fiat_account.deposit.received` (with `holder_type: business`)\nand `fiat_account.payment.sent` / `fiat_account.payment.updated` with a different `data`; see\nBusiness customers, Webhooks.\n\n**Payload shape — `order.own_account_payout.updated`**\n\nSent only on an off-ramp paid through the customer's own fiat account\n(`payout_via_own_account: true`), when the onward payment to the bank you named reaches\n`sent_to_bank`, `held`, `under_review` or `left_on_account`, once per change of state. It does\nnot change the order's `status`. The provider's payment into the customer's account, once\nmatched to the order, does not send `fiat_account.deposit.received`.\n\n```json\n{\n  \"event_id\": \"evt_own_account_payout_1234_sent_to_bank_3f9a1c0b7d2e4a55\",\n  \"event_type\": \"order.own_account_payout.updated\",\n  \"created_at\": \"2026-10-16T12:00:00Z\",\n  \"data\": {\n    \"order_id\": \"9f1c6b7e-0000-4000-8000-000000000042\",\n    \"user_uuid\": \"c0ffee00-0000-4000-8000-000000000001\",\n    \"own_account_payout_status\": \"sent_to_bank\",\n    \"fiat_account_id\": \"6b1d2c3e-0000-4000-8000-000000000007\",\n    \"amount\": \"250.00\",\n    \"currency\": \"EUR\"\n  }\n}\n```\n\n`fiat_account_id` is omitted when the account is not one you can address by id. `amount` is a\ndecimal string with at least two decimals.\n\nAll events share the same envelope (`event_id`, `event_type`, `created_at`, `data`)\nand the same signature scheme. The structure of the `data` object differs per event type.\n\n**Payload shape — `order.status.changed`**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"order.status.changed\",\n  \"created_at\": \"2026-02-01T12:00:05Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"crypto_received\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"101.5\",\n    \"crypto_currency\": \"USDT\",\n    \"partner_fee\": \"1\",\n    \"partner_fee_pct\": 1,\n    \"fiat_amount\": \"152880.00\",\n    \"fiat_currency\": \"NGN\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\"\n  }\n}\n```\n\n`user_id` is the customer's `user_uuid`.\n\n**Payload shape — `order.refund.required`**\n\nFired when an off-ramp order has stopped without a payout and its crypto is still in escrow.\nThis has its own event type because there is no status change to carry it: the order reads\n`cancelled` from the moment it stopped, exactly like an order whose refund was already paid out,\nso a listener filtering on status transitions would never learn that anything is owed. It is\nsent **at most once per order**, and the same information is on `GET /orders/{order_id}` for as\nlong as it stays true.\n\nThe `data` object is the order.status.changed payload plus `action_required`.\n\n```json\n{\n  \"event_id\": \"evt_refund_required_b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n  \"event_type\": \"order.refund.required\",\n  \"created_at\": \"2026-09-09T09:14:00Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"cancelled\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"1000.25\",\n    \"crypto_currency\": \"USDT\",\n    \"fiat_amount\": \"3070.50\",\n    \"fiat_currency\": \"KWD\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\",\n    \"action_required\": {\n      \"type\": \"authorize_refund\",\n      \"message\": \"This order ended without a payout and the crypto is still in escrow. ...\",\n      \"endpoint\": \"POST /api/v1/partner/orders/{order_id}/authorize-refund\"\n    }\n  }\n}\n```\n\nAct on it with the refund pair: `GET /orders/{order_id}/refund-authorization-parameters` for the\ntransaction to sign, then `POST /orders/{order_id}/authorize-refund` with the signature. Nobody\nelse can produce that signature — the escrow needs two of its three owners, we hold one key and\nyou hold the other.\n\n**Payload shape — `user.kyc.updated`**\n\nFired when a user's KYC status changes — to `VERIFIED`, `REJECTED`, or to a manual compliance\nreview hold (`UNDER_REVIEW`). Use this event to unlock order creation for the user on your side\n(only on `VERIFIED`; `UNDER_REVIEW` is not cleared).\n\n```json\n{\n  \"event_id\": \"evt_2d8418dd-e3a8-4463-a11e-6b54f354ca90\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T11:37:42Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"VERIFIED\"\n  }\n}\n```\n\nWhen KYC is declined, `rejection_reasons` is included:\n\n```json\n{\n  \"event_id\": \"evt_fc75484d-b374-4d05-b54e-820f3dd80e6d\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:00:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"REJECTED\",\n    \"rejection_reasons\": [\"Document expired\", \"Photo quality low\"]\n  }\n}\n```\n\nWhen a customer is placed on a manual compliance review hold, `kyc_status` is `UNDER_REVIEW`:\n\n```json\n{\n  \"event_id\": \"evt_9a1c7f20-4d3b-4e88-9f2a-1b6d0c5e7a3f\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:05:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"UNDER_REVIEW\"\n  }\n}\n```\n\n`kyc_status` values: `VERIFIED` | `REJECTED` | `UNDER_REVIEW`\n\n`UNDER_REVIEW` is a manual compliance review: the customer is NOT cleared and can take up to\n24 hours (unlike an automated check of a couple of minutes). Do not unlock order creation until\n`VERIFIED`.\n\n**Signature verification**\n\nEvery delivery includes two headers for HMAC-SHA256 verification:\n- `X-Unigox-Signature: sha256=<hex>` — HMAC of `\"<timestamp>.<raw_body>\"`\n- `X-Unigox-Timestamp: <unix_seconds>`\n\nVerification pseudocode:\n```\nexpected = HMAC-SHA256(webhook_secret, \"<timestamp>.<raw_body>\")\nvalid    = constant_time_compare(expected, signature_from_header)\n```\n\n**Delivery guarantees**\n\n- At-least-once delivery. Your endpoint may receive the same event more than once.\n- De-duplicate by `event_id`.\n- Respond with any 2xx status within 10 seconds to acknowledge receipt.\n\n**Retry policy**\n\nFailed deliveries (non-2xx or timeout) are retried with exponential backoff:\n1 min → 5 min → 15 min → 1 h → 6 h → 12 h → 24 h (max 10 attempts over ~3.5 days).\n\n**Partner-facing statuses** (`order.status.changed`)\n\n| Status | Description |\n|---|---|\n| `created` | Order created |\n| `awaiting_liquidity_provider` | Waiting for vendor match |\n| `awaiting_crypto_transfer_authorization` | Partner must authorize crypto transfer |\n| `crypto_transfer_authorization_pending` | Authorization submitted, awaiting on-chain confirmation |\n| `price_changed_requote_needed` | Slippage exceeded at initiation; create a new quote |\n| `crypto_received` | Crypto received in escrow |\n| `fiat_payment_started` | Buyer submitted fiat payment proof |\n| `fiat_payment_review_started` | Payment proof under review |\n| `awaiting_fiat_received_confirmation` | Proof approved, awaiting seller confirmation |\n| `completed` | Order completed, crypto released |\n| `cancelled` | Order cancelled or payment declined |\n| `failed` | Escrow error, or fiat-anchored safety bound exceeded (see below) |\n| `dispute_started` | Dispute opened |\n| `settlement_in_progress` | Delayed settlement (T+1): the release of the crypto has started or is confirmed, and the fiat has not arrived |\n| `returned` | Delayed settlement (T+1): the bank sent the payout back and no new attempt has been approved yet |\n| `awaiting_vendor_escrow_funding` | On-ramp: vendor accepted, funding escrow with crypto |\n| `awaiting_fiat_transfer` | On-ramp: crypto locked in escrow, waiting for the fiat payment |\n| `fiat_transfer_pending` | On-ramp: fiat payment confirmed, awaiting vendor confirmation of receipt |\n| `send_out_pending` | On-ramp send-out: cross-chain transfer in progress |\n| `send_out_completed` | On-ramp send-out: delivered on the destination chain |\n| `send_out_failed` | On-ramp send-out: cross-chain transfer failed; the on-ramp itself stays completed |\n\n**Fiat-anchored safety bound failure**\n\nFor fiat-anchored off-ramp orders (`anchor_type: \"fiat\"`), if the crypto cost we quote exceeds\n1.20× the expected amount at the time of settlement, the order moves to `failed` status asynchronously\n(not during `/initiate`). The deposit is automatically refunded from escrow back to the partner wallet.\nCreate a new quote to retry the trade flow.\n\n**Settlement notifications (recipient received the fiat)**\n\nSome liquidity providers automatically confirm when the fiat payout reaches the\nrecipient's bank account or mobile wallet. When the provider matched to an order\nsupports this, the order moves to `completed` on its own and you receive an\n`order.status.changed` webhook with `status=completed` — that webhook is your signal\nthat the recipient has actually received the money.\n\nWhether the matched provider sends this is reported per order by the\n`has_fiat_settlement_notification` field on the **quote** and **order** responses:\n\n- `true` — the matched provider sends an automatic settlement confirmation. You will\n  receive the `completed` webhook once fiat is delivered; no manual action is needed.\n- `false` — no automatic confirmation for this order. Confirm delivery yourself by\n  calling `confirm-fiat-received` (or rely on your own banking/payment systems).\n\nA delayed settlement (T+1) quote, and a T+1 order once a liquidity provider has accepted\nit, always read `true`: the fiat leg ends in the `completed` webhook, and\n`confirm-fiat-received` refuses it. Every order a liquidity provider has not accepted yet,\nT+1 included, reads `false`; read the flag again after acceptance.\n\nTo match **only** providers that send settlement notifications, pass\n`has_fiat_settlement_notification: true` in the quote request — providers that can't\noffer it are then excluded from matching.\n\nAvailability is provider- and corridor-dependent: not every currency has a provider\nthat sends settlement notifications, so always read the flag on each quote rather than\nassuming it. Manual `confirm-fiat-received` and the automatic confirmation are mutually\nidempotent — whichever happens first wins and the other is a safe no-op.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}}}},"paths":{"/api/v1/partner/webhooks/{id}":{"delete":{"tags":["Webhooks"],"summary":"Delete webhook","description":"Remove the webhook URL and disable webhook delivery for your partner account.\nNo further events will be sent until a new URL is registered.\n","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"description":"Webhook ID (any value accepted — the system uses the authenticated partner context)","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deleted successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string"}}}}}]}}}},"401":{"description":"Unauthorized — invalid or missing API key"}}}}}}
````

## Test webhook

> Send a signed test event to your configured webhook URL. Uses the same HMAC-SHA256\
> signature scheme as production events. Use this to verify your endpoint is reachable\
> and correctly validating signatures.\
> \
> \*\*No body\*\* (or an empty one) sends a \`ping\` event with empty \`data\`, as it always has.\
> \
> \*\*With a body\*\* \`{"event\_type": "..."}\` it sends a sample of that real event instead, in\
> the exact shape your endpoint will receive in production, so you can test your handler\
> before real money moves. Supported \`event\_type\` values:\
> \
> \| \`event\_type\` | Sample |\
> \| --- | --- |\
> \| \`ping\` | Same as no body. |\
> \| \`order.status.changed\` | A completed off-ramp order. |\
> \| \`fiat\_account.deposit.received\` | A credit on an issued account. \`holder\_type\`: \`retail\` (default) or \`business\`. |\
> \| \`fiat\_account.payment.sent\` | Money leaving a business customer's account. |\
> \| \`fiat\_account.payment.updated\` | A status step of a business account payment (\`status: pending\`). |\
> \| \`business\_customer.kyb.updated\` | A business customer's KYB reaching \`approved\`. |\
> \
> Any other value returns \`400\` with the supported list.\
> \
> Every sample is clearly marked: \`event\_id\` starts with \`evt\_test\_\` and the envelope carries\
> \`"test": true\` at the top level (inside the signed body, so signature verification is\
> unchanged). Ids inside \`data\` are placeholders (\`00000000-0000-4000-8000-00000000000N\`,\
> \`business\_0\`) that match nothing in your account. A test event is sent once, is not\
> retried, and does not appear in \`GET /api/v1/partner/webhooks/events\`.<br>

````json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Signed notifications for orders, KYC/KYB, fiat accounts, business customers and wallet deposits.\nThe system sends a signed HTTP POST to your configured webhook URL on every relevant event.\n\n**Event model**\n\nThese event types are delivered:\n\n| Event type | Fired when |\n|---|---|\n| `order.status.changed` | An order transitions to a new status |\n| `order.refund.required` | An order's crypto is stuck in escrow and only your signature can return it |\n| `user.kyc.updated` | A user's KYC verification is approved, declined or put on manual review |\n| `fiat_account.updated` | An issued fiat account changes status. No money moved. |\n| `fiat_account.deposit.received` | Money arrived on an issued fiat account. Not sent for a credit matched to exactly one off-ramp paid through that account, which `order.own_account_payout.updated` covers. A business customer's account sends it with `holder_type: business` |\n| `fiat_account.payment.sent` | Money left a business customer's account |\n| `fiat_account.payment.updated` | A transfer on a business customer's account reached a new status (`pending`, `confirmed`, `sent`, `blocked`, `refused`, `refunded`…) |\n| `business_customer.kyb.updated` | A business customer's KYB status changed |\n| `order.own_account_payout.updated` | An off-ramp paid through the customer's own fiat account was sent on to the bank, or stopped on the account |\n| `wallet.linked` | An external-wallet customer linked their address |\n| `wallet.deposit.received` | A bridge payment was credited to a linked customer wallet on XAI |\n| `wallet.withdrawal.status.changed` | A customer withdrawal from an external wallet changed status |\n\n**Customer wallet events**\n\n`wallet.linked` carries `user_uuid`, `address` and `linked_at`. The link response and\n`GET /api/v1/partner/users/{user_uuid}/wallet` confirm the link even if that notification\nis not delivered. This event has no automatic delivery retry.\n\n`wallet.deposit.received` reports the credited XAI token and amount, with the source\ntransaction and XAI settlement transaction. It reports supported bridge credits to linked\nwallets, not every transfer into that wallet. It does not include a memo or memo-lock ID.\n\n```json\n{\n  \"event_id\": \"evt_dep_42_12345\",\n  \"event_type\": \"wallet.deposit.received\",\n  \"created_at\": \"2026-10-18T10:01:00Z\",\n  \"data\": {\n    \"deposit_id\": \"intent:12345\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"address\": \"0x1111111111111111111111111111111111111111\",\n    \"chain_id\": \"660279\",\n    \"crypto_currency\": \"USDC\",\n    \"token_address\": \"0x37bf70ee0dc89a408de31b79cccc3152f0c8af43\",\n    \"amount\": \"1\",\n    \"amount_atomic\": \"1000000\",\n    \"source_chain_id\": \"8453\",\n    \"source_tx_hash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n    \"tx_hash\": \"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n    \"credited_at\": \"2026-10-18T10:00:00Z\"\n  }\n}\n```\n\nRegister and enable your webhook before accepting deposits. Deposit notifications retry\nfailed delivery with the same `event_id` (first retry after 30 s, the wait doubling up to 6 h, at most\n10 attempts); `data.deposit_id` identifies the credited payment.\nProcess each deposit once within your partner account and environment. Return a 2xx after\naccepting the event. Delivery is bounded; disabling a webhook does not queue a later replay.\nBoth wallet events use the partner signature scheme described below. `created_at` and the\ndelivery signature can change on retry; `credited_at` is the settlement time.\n\n**Payload shape — the fiat account events**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"fiat_account.deposit.received\",\n  \"created_at\": \"2026-09-18T10:04:23Z\",\n  \"data\": {\n    \"fiat_account_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"holder_type\": \"retail\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"transaction_id\": \"5f1b2c9a-1d44-4f0e-9c1a-2b5f0d7e9a31\",\n    \"amount\": \"500.00\",\n    \"currency\": \"EUR\",\n    \"order_id\": null\n  }\n}\n```\n\n`order_id` is the on-ramp this deposit funded, or `null` when it matched no order.\nThe event is not sent for a credit matched to exactly one off-ramp paid through the customer's\nown fiat account (`payout_via_own_account: true`); `order.own_account_payout.updated` reports\nthat money instead. Any other credit still sends it, including one held for review because it\ncannot be tied to a single order.\n`fiat_account.updated` carries `fiat_account_id`, `user_uuid`, `status` and `currency`.\nA business customer's account sends `fiat_account.deposit.received` (with `holder_type: business`)\nand `fiat_account.payment.sent` / `fiat_account.payment.updated` with a different `data`; see\nBusiness customers, Webhooks.\n\n**Payload shape — `order.own_account_payout.updated`**\n\nSent only on an off-ramp paid through the customer's own fiat account\n(`payout_via_own_account: true`), when the onward payment to the bank you named reaches\n`sent_to_bank`, `held`, `under_review` or `left_on_account`, once per change of state. It does\nnot change the order's `status`. The provider's payment into the customer's account, once\nmatched to the order, does not send `fiat_account.deposit.received`.\n\n```json\n{\n  \"event_id\": \"evt_own_account_payout_1234_sent_to_bank_3f9a1c0b7d2e4a55\",\n  \"event_type\": \"order.own_account_payout.updated\",\n  \"created_at\": \"2026-10-16T12:00:00Z\",\n  \"data\": {\n    \"order_id\": \"9f1c6b7e-0000-4000-8000-000000000042\",\n    \"user_uuid\": \"c0ffee00-0000-4000-8000-000000000001\",\n    \"own_account_payout_status\": \"sent_to_bank\",\n    \"fiat_account_id\": \"6b1d2c3e-0000-4000-8000-000000000007\",\n    \"amount\": \"250.00\",\n    \"currency\": \"EUR\"\n  }\n}\n```\n\n`fiat_account_id` is omitted when the account is not one you can address by id. `amount` is a\ndecimal string with at least two decimals.\n\nAll events share the same envelope (`event_id`, `event_type`, `created_at`, `data`)\nand the same signature scheme. The structure of the `data` object differs per event type.\n\n**Payload shape — `order.status.changed`**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"order.status.changed\",\n  \"created_at\": \"2026-02-01T12:00:05Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"crypto_received\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"101.5\",\n    \"crypto_currency\": \"USDT\",\n    \"partner_fee\": \"1\",\n    \"partner_fee_pct\": 1,\n    \"fiat_amount\": \"152880.00\",\n    \"fiat_currency\": \"NGN\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\"\n  }\n}\n```\n\n`user_id` is the customer's `user_uuid`.\n\n**Payload shape — `order.refund.required`**\n\nFired when an off-ramp order has stopped without a payout and its crypto is still in escrow.\nThis has its own event type because there is no status change to carry it: the order reads\n`cancelled` from the moment it stopped, exactly like an order whose refund was already paid out,\nso a listener filtering on status transitions would never learn that anything is owed. It is\nsent **at most once per order**, and the same information is on `GET /orders/{order_id}` for as\nlong as it stays true.\n\nThe `data` object is the order.status.changed payload plus `action_required`.\n\n```json\n{\n  \"event_id\": \"evt_refund_required_b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n  \"event_type\": \"order.refund.required\",\n  \"created_at\": \"2026-09-09T09:14:00Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"cancelled\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"1000.25\",\n    \"crypto_currency\": \"USDT\",\n    \"fiat_amount\": \"3070.50\",\n    \"fiat_currency\": \"KWD\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\",\n    \"action_required\": {\n      \"type\": \"authorize_refund\",\n      \"message\": \"This order ended without a payout and the crypto is still in escrow. ...\",\n      \"endpoint\": \"POST /api/v1/partner/orders/{order_id}/authorize-refund\"\n    }\n  }\n}\n```\n\nAct on it with the refund pair: `GET /orders/{order_id}/refund-authorization-parameters` for the\ntransaction to sign, then `POST /orders/{order_id}/authorize-refund` with the signature. Nobody\nelse can produce that signature — the escrow needs two of its three owners, we hold one key and\nyou hold the other.\n\n**Payload shape — `user.kyc.updated`**\n\nFired when a user's KYC status changes — to `VERIFIED`, `REJECTED`, or to a manual compliance\nreview hold (`UNDER_REVIEW`). Use this event to unlock order creation for the user on your side\n(only on `VERIFIED`; `UNDER_REVIEW` is not cleared).\n\n```json\n{\n  \"event_id\": \"evt_2d8418dd-e3a8-4463-a11e-6b54f354ca90\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T11:37:42Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"VERIFIED\"\n  }\n}\n```\n\nWhen KYC is declined, `rejection_reasons` is included:\n\n```json\n{\n  \"event_id\": \"evt_fc75484d-b374-4d05-b54e-820f3dd80e6d\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:00:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"REJECTED\",\n    \"rejection_reasons\": [\"Document expired\", \"Photo quality low\"]\n  }\n}\n```\n\nWhen a customer is placed on a manual compliance review hold, `kyc_status` is `UNDER_REVIEW`:\n\n```json\n{\n  \"event_id\": \"evt_9a1c7f20-4d3b-4e88-9f2a-1b6d0c5e7a3f\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:05:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"UNDER_REVIEW\"\n  }\n}\n```\n\n`kyc_status` values: `VERIFIED` | `REJECTED` | `UNDER_REVIEW`\n\n`UNDER_REVIEW` is a manual compliance review: the customer is NOT cleared and can take up to\n24 hours (unlike an automated check of a couple of minutes). Do not unlock order creation until\n`VERIFIED`.\n\n**Signature verification**\n\nEvery delivery includes two headers for HMAC-SHA256 verification:\n- `X-Unigox-Signature: sha256=<hex>` — HMAC of `\"<timestamp>.<raw_body>\"`\n- `X-Unigox-Timestamp: <unix_seconds>`\n\nVerification pseudocode:\n```\nexpected = HMAC-SHA256(webhook_secret, \"<timestamp>.<raw_body>\")\nvalid    = constant_time_compare(expected, signature_from_header)\n```\n\n**Delivery guarantees**\n\n- At-least-once delivery. Your endpoint may receive the same event more than once.\n- De-duplicate by `event_id`.\n- Respond with any 2xx status within 10 seconds to acknowledge receipt.\n\n**Retry policy**\n\nFailed deliveries (non-2xx or timeout) are retried with exponential backoff:\n1 min → 5 min → 15 min → 1 h → 6 h → 12 h → 24 h (max 10 attempts over ~3.5 days).\n\n**Partner-facing statuses** (`order.status.changed`)\n\n| Status | Description |\n|---|---|\n| `created` | Order created |\n| `awaiting_liquidity_provider` | Waiting for vendor match |\n| `awaiting_crypto_transfer_authorization` | Partner must authorize crypto transfer |\n| `crypto_transfer_authorization_pending` | Authorization submitted, awaiting on-chain confirmation |\n| `price_changed_requote_needed` | Slippage exceeded at initiation; create a new quote |\n| `crypto_received` | Crypto received in escrow |\n| `fiat_payment_started` | Buyer submitted fiat payment proof |\n| `fiat_payment_review_started` | Payment proof under review |\n| `awaiting_fiat_received_confirmation` | Proof approved, awaiting seller confirmation |\n| `completed` | Order completed, crypto released |\n| `cancelled` | Order cancelled or payment declined |\n| `failed` | Escrow error, or fiat-anchored safety bound exceeded (see below) |\n| `dispute_started` | Dispute opened |\n| `settlement_in_progress` | Delayed settlement (T+1): the release of the crypto has started or is confirmed, and the fiat has not arrived |\n| `returned` | Delayed settlement (T+1): the bank sent the payout back and no new attempt has been approved yet |\n| `awaiting_vendor_escrow_funding` | On-ramp: vendor accepted, funding escrow with crypto |\n| `awaiting_fiat_transfer` | On-ramp: crypto locked in escrow, waiting for the fiat payment |\n| `fiat_transfer_pending` | On-ramp: fiat payment confirmed, awaiting vendor confirmation of receipt |\n| `send_out_pending` | On-ramp send-out: cross-chain transfer in progress |\n| `send_out_completed` | On-ramp send-out: delivered on the destination chain |\n| `send_out_failed` | On-ramp send-out: cross-chain transfer failed; the on-ramp itself stays completed |\n\n**Fiat-anchored safety bound failure**\n\nFor fiat-anchored off-ramp orders (`anchor_type: \"fiat\"`), if the crypto cost we quote exceeds\n1.20× the expected amount at the time of settlement, the order moves to `failed` status asynchronously\n(not during `/initiate`). The deposit is automatically refunded from escrow back to the partner wallet.\nCreate a new quote to retry the trade flow.\n\n**Settlement notifications (recipient received the fiat)**\n\nSome liquidity providers automatically confirm when the fiat payout reaches the\nrecipient's bank account or mobile wallet. When the provider matched to an order\nsupports this, the order moves to `completed` on its own and you receive an\n`order.status.changed` webhook with `status=completed` — that webhook is your signal\nthat the recipient has actually received the money.\n\nWhether the matched provider sends this is reported per order by the\n`has_fiat_settlement_notification` field on the **quote** and **order** responses:\n\n- `true` — the matched provider sends an automatic settlement confirmation. You will\n  receive the `completed` webhook once fiat is delivered; no manual action is needed.\n- `false` — no automatic confirmation for this order. Confirm delivery yourself by\n  calling `confirm-fiat-received` (or rely on your own banking/payment systems).\n\nA delayed settlement (T+1) quote, and a T+1 order once a liquidity provider has accepted\nit, always read `true`: the fiat leg ends in the `completed` webhook, and\n`confirm-fiat-received` refuses it. Every order a liquidity provider has not accepted yet,\nT+1 included, reads `false`; read the flag again after acceptance.\n\nTo match **only** providers that send settlement notifications, pass\n`has_fiat_settlement_notification: true` in the quote request — providers that can't\noffer it are then excluded from matching.\n\nAvailability is provider- and corridor-dependent: not every currency has a provider\nthat sends settlement notifications, so always read the flag on each quote rather than\nassuming it. Manual `confirm-fiat-received` and the automatic confirmation are mutually\nidempotent — whichever happens first wins and the other is a safe no-op.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"WebhookTestRequest":{"type":"object","description":"Optional body of `POST /api/v1/partner/webhooks/test`. Omit it to send `ping`.","properties":{"event_type":{"type":"string","enum":["ping","order.status.changed","fiat_account.deposit.received","fiat_account.payment.sent","fiat_account.payment.updated","business_customer.kyb.updated"],"description":"The event to send a sample of. Empty or omitted is `ping`."},"holder_type":{"type":"string","enum":["retail","business"],"description":"For `fiat_account.deposit.received` only: the retail (default) or business account\nsample. `business` is also accepted for the `fiat_account.payment.*` events, which\nexist only on business accounts.\n"}}},"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"WebhookTestPingResponse":{"type":"object","properties":{"delivered":{"type":"boolean","description":"Whether the test event was delivered successfully"},"http_status":{"type":"integer","nullable":true,"description":"HTTP status code returned by the webhook endpoint; `null` when it did not answer"},"error":{"type":"string","description":"Present when `delivered` is `false`","enum":["webhook endpoint answered non-2xx","webhook endpoint unreachable"]}}},"ErrorResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean"},"data":{"type":"object","required":["error_key"],"properties":{"error_key":{"type":"string","description":"Standardized error key for client error handling"}}}}}}},"paths":{"/api/v1/partner/webhooks/test":{"post":{"tags":["Webhooks"],"summary":"Test webhook","description":"Send a signed test event to your configured webhook URL. Uses the same HMAC-SHA256\nsignature scheme as production events. Use this to verify your endpoint is reachable\nand correctly validating signatures.\n\n**No body** (or an empty one) sends a `ping` event with empty `data`, as it always has.\n\n**With a body** `{\"event_type\": \"...\"}` it sends a sample of that real event instead, in\nthe exact shape your endpoint will receive in production, so you can test your handler\nbefore real money moves. Supported `event_type` values:\n\n| `event_type` | Sample |\n| --- | --- |\n| `ping` | Same as no body. |\n| `order.status.changed` | A completed off-ramp order. |\n| `fiat_account.deposit.received` | A credit on an issued account. `holder_type`: `retail` (default) or `business`. |\n| `fiat_account.payment.sent` | Money leaving a business customer's account. |\n| `fiat_account.payment.updated` | A status step of a business account payment (`status: pending`). |\n| `business_customer.kyb.updated` | A business customer's KYB reaching `approved`. |\n\nAny other value returns `400` with the supported list.\n\nEvery sample is clearly marked: `event_id` starts with `evt_test_` and the envelope carries\n`\"test\": true` at the top level (inside the signed body, so signature verification is\nunchanged). Ids inside `data` are placeholders (`00000000-0000-4000-8000-00000000000N`,\n`business_0`) that match nothing in your account. A test event is sent once, is not\nretried, and does not appear in `GET /api/v1/partner/webhooks/events`.\n","operationId":"testPingWebhook","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestRequest"}}}},"responses":{"200":{"description":"The test event was sent. `delivered` says whether your endpoint accepted it: `true`\nfor a 2xx answer, `false` for any other answer (its code in `http_status`) or none at\nall (`http_status: null`). A `false` here is your endpoint's result, not an error of\nthe call, so it is a `200` too.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookTestPingResponse"}}}]}}}},"400":{"description":"Webhook URL not configured, malformed body, or an unsupported `event_type` / `holder_type`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key"}}}}}}
````

## List webhook events (replay)

> Read back the webhook events sent to you, oldest first, with how each delivery went.\
> Use it to catch up after your endpoint was down or your webhook was switched off, or to\
> reconcile what you processed against what was sent.\
> \
> Each item is the event \*\*exactly as it was signed and sent\*\* (\`event\_id\`, \`event\_type\`,\
> \`created\_at\`, \`data\`) with a \`delivery\` object added, so the same code that handles the\
> live webhook can process it. Deduplicate on \`event\_id\`, as you do for live deliveries.\
> \
> \*\*Which events appear.\*\* Events delivered through Unigox's retrying event queue:\
> \`order.status.changed\`, \`order.refund.required\`, \`order.own\_account\_payout.updated\`,\
> \`user.kyc.updated\`, \`business\_customer.kyb.updated\`, \`fiat\_account.updated\` when an account\
> is closed, and the business account events \`fiat\_account.deposit.received\`,\
> \`fiat\_account.payment.sent\` and \`fiat\_account.payment.updated\`. The retail\
> \`fiat\_account.deposit.received\`, other \`fiat\_account.updated\` notices and test events are\
> sent once and are not retried. \`wallet.deposit.received\` is retried on its own schedule\
> (see Webhooks). None of these appear here.\
> \
> \*\*Events from while your webhook was off are listed too.\*\* They were never sent: their\
> \`delivery.status\` is \`failed\` with \`failure\_reason: webhook\_disabled\`. Read them here, or\
> ask for one to be sent with the redeliver endpoint once your webhook is on.\
> \
> \*\*Paging.\*\* Pass \`next\_cursor\` back as \`cursor\` for the next page. \`next\_cursor\` is set\
> on every non-empty page, including the last one, so you can keep polling with it; an\
> empty page returns the cursor you sent. When \`cursor\` is sent without \`since\`, the cursor\
> alone is the starting point. An event is stamped when the change that raised it began, so\
> one can become visible slightly after a later-stamped one: when polling, re-read with a\
> small overlap (\`since\` a few minutes back) and deduplicate on \`event\_id\`.<br>

````json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Signed notifications for orders, KYC/KYB, fiat accounts, business customers and wallet deposits.\nThe system sends a signed HTTP POST to your configured webhook URL on every relevant event.\n\n**Event model**\n\nThese event types are delivered:\n\n| Event type | Fired when |\n|---|---|\n| `order.status.changed` | An order transitions to a new status |\n| `order.refund.required` | An order's crypto is stuck in escrow and only your signature can return it |\n| `user.kyc.updated` | A user's KYC verification is approved, declined or put on manual review |\n| `fiat_account.updated` | An issued fiat account changes status. No money moved. |\n| `fiat_account.deposit.received` | Money arrived on an issued fiat account. Not sent for a credit matched to exactly one off-ramp paid through that account, which `order.own_account_payout.updated` covers. A business customer's account sends it with `holder_type: business` |\n| `fiat_account.payment.sent` | Money left a business customer's account |\n| `fiat_account.payment.updated` | A transfer on a business customer's account reached a new status (`pending`, `confirmed`, `sent`, `blocked`, `refused`, `refunded`…) |\n| `business_customer.kyb.updated` | A business customer's KYB status changed |\n| `order.own_account_payout.updated` | An off-ramp paid through the customer's own fiat account was sent on to the bank, or stopped on the account |\n| `wallet.linked` | An external-wallet customer linked their address |\n| `wallet.deposit.received` | A bridge payment was credited to a linked customer wallet on XAI |\n| `wallet.withdrawal.status.changed` | A customer withdrawal from an external wallet changed status |\n\n**Customer wallet events**\n\n`wallet.linked` carries `user_uuid`, `address` and `linked_at`. The link response and\n`GET /api/v1/partner/users/{user_uuid}/wallet` confirm the link even if that notification\nis not delivered. This event has no automatic delivery retry.\n\n`wallet.deposit.received` reports the credited XAI token and amount, with the source\ntransaction and XAI settlement transaction. It reports supported bridge credits to linked\nwallets, not every transfer into that wallet. It does not include a memo or memo-lock ID.\n\n```json\n{\n  \"event_id\": \"evt_dep_42_12345\",\n  \"event_type\": \"wallet.deposit.received\",\n  \"created_at\": \"2026-10-18T10:01:00Z\",\n  \"data\": {\n    \"deposit_id\": \"intent:12345\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"address\": \"0x1111111111111111111111111111111111111111\",\n    \"chain_id\": \"660279\",\n    \"crypto_currency\": \"USDC\",\n    \"token_address\": \"0x37bf70ee0dc89a408de31b79cccc3152f0c8af43\",\n    \"amount\": \"1\",\n    \"amount_atomic\": \"1000000\",\n    \"source_chain_id\": \"8453\",\n    \"source_tx_hash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n    \"tx_hash\": \"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n    \"credited_at\": \"2026-10-18T10:00:00Z\"\n  }\n}\n```\n\nRegister and enable your webhook before accepting deposits. Deposit notifications retry\nfailed delivery with the same `event_id` (first retry after 30 s, the wait doubling up to 6 h, at most\n10 attempts); `data.deposit_id` identifies the credited payment.\nProcess each deposit once within your partner account and environment. Return a 2xx after\naccepting the event. Delivery is bounded; disabling a webhook does not queue a later replay.\nBoth wallet events use the partner signature scheme described below. `created_at` and the\ndelivery signature can change on retry; `credited_at` is the settlement time.\n\n**Payload shape — the fiat account events**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"fiat_account.deposit.received\",\n  \"created_at\": \"2026-09-18T10:04:23Z\",\n  \"data\": {\n    \"fiat_account_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"holder_type\": \"retail\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"transaction_id\": \"5f1b2c9a-1d44-4f0e-9c1a-2b5f0d7e9a31\",\n    \"amount\": \"500.00\",\n    \"currency\": \"EUR\",\n    \"order_id\": null\n  }\n}\n```\n\n`order_id` is the on-ramp this deposit funded, or `null` when it matched no order.\nThe event is not sent for a credit matched to exactly one off-ramp paid through the customer's\nown fiat account (`payout_via_own_account: true`); `order.own_account_payout.updated` reports\nthat money instead. Any other credit still sends it, including one held for review because it\ncannot be tied to a single order.\n`fiat_account.updated` carries `fiat_account_id`, `user_uuid`, `status` and `currency`.\nA business customer's account sends `fiat_account.deposit.received` (with `holder_type: business`)\nand `fiat_account.payment.sent` / `fiat_account.payment.updated` with a different `data`; see\nBusiness customers, Webhooks.\n\n**Payload shape — `order.own_account_payout.updated`**\n\nSent only on an off-ramp paid through the customer's own fiat account\n(`payout_via_own_account: true`), when the onward payment to the bank you named reaches\n`sent_to_bank`, `held`, `under_review` or `left_on_account`, once per change of state. It does\nnot change the order's `status`. The provider's payment into the customer's account, once\nmatched to the order, does not send `fiat_account.deposit.received`.\n\n```json\n{\n  \"event_id\": \"evt_own_account_payout_1234_sent_to_bank_3f9a1c0b7d2e4a55\",\n  \"event_type\": \"order.own_account_payout.updated\",\n  \"created_at\": \"2026-10-16T12:00:00Z\",\n  \"data\": {\n    \"order_id\": \"9f1c6b7e-0000-4000-8000-000000000042\",\n    \"user_uuid\": \"c0ffee00-0000-4000-8000-000000000001\",\n    \"own_account_payout_status\": \"sent_to_bank\",\n    \"fiat_account_id\": \"6b1d2c3e-0000-4000-8000-000000000007\",\n    \"amount\": \"250.00\",\n    \"currency\": \"EUR\"\n  }\n}\n```\n\n`fiat_account_id` is omitted when the account is not one you can address by id. `amount` is a\ndecimal string with at least two decimals.\n\nAll events share the same envelope (`event_id`, `event_type`, `created_at`, `data`)\nand the same signature scheme. The structure of the `data` object differs per event type.\n\n**Payload shape — `order.status.changed`**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"order.status.changed\",\n  \"created_at\": \"2026-02-01T12:00:05Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"crypto_received\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"101.5\",\n    \"crypto_currency\": \"USDT\",\n    \"partner_fee\": \"1\",\n    \"partner_fee_pct\": 1,\n    \"fiat_amount\": \"152880.00\",\n    \"fiat_currency\": \"NGN\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\"\n  }\n}\n```\n\n`user_id` is the customer's `user_uuid`.\n\n**Payload shape — `order.refund.required`**\n\nFired when an off-ramp order has stopped without a payout and its crypto is still in escrow.\nThis has its own event type because there is no status change to carry it: the order reads\n`cancelled` from the moment it stopped, exactly like an order whose refund was already paid out,\nso a listener filtering on status transitions would never learn that anything is owed. It is\nsent **at most once per order**, and the same information is on `GET /orders/{order_id}` for as\nlong as it stays true.\n\nThe `data` object is the order.status.changed payload plus `action_required`.\n\n```json\n{\n  \"event_id\": \"evt_refund_required_b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n  \"event_type\": \"order.refund.required\",\n  \"created_at\": \"2026-09-09T09:14:00Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"cancelled\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"1000.25\",\n    \"crypto_currency\": \"USDT\",\n    \"fiat_amount\": \"3070.50\",\n    \"fiat_currency\": \"KWD\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\",\n    \"action_required\": {\n      \"type\": \"authorize_refund\",\n      \"message\": \"This order ended without a payout and the crypto is still in escrow. ...\",\n      \"endpoint\": \"POST /api/v1/partner/orders/{order_id}/authorize-refund\"\n    }\n  }\n}\n```\n\nAct on it with the refund pair: `GET /orders/{order_id}/refund-authorization-parameters` for the\ntransaction to sign, then `POST /orders/{order_id}/authorize-refund` with the signature. Nobody\nelse can produce that signature — the escrow needs two of its three owners, we hold one key and\nyou hold the other.\n\n**Payload shape — `user.kyc.updated`**\n\nFired when a user's KYC status changes — to `VERIFIED`, `REJECTED`, or to a manual compliance\nreview hold (`UNDER_REVIEW`). Use this event to unlock order creation for the user on your side\n(only on `VERIFIED`; `UNDER_REVIEW` is not cleared).\n\n```json\n{\n  \"event_id\": \"evt_2d8418dd-e3a8-4463-a11e-6b54f354ca90\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T11:37:42Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"VERIFIED\"\n  }\n}\n```\n\nWhen KYC is declined, `rejection_reasons` is included:\n\n```json\n{\n  \"event_id\": \"evt_fc75484d-b374-4d05-b54e-820f3dd80e6d\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:00:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"REJECTED\",\n    \"rejection_reasons\": [\"Document expired\", \"Photo quality low\"]\n  }\n}\n```\n\nWhen a customer is placed on a manual compliance review hold, `kyc_status` is `UNDER_REVIEW`:\n\n```json\n{\n  \"event_id\": \"evt_9a1c7f20-4d3b-4e88-9f2a-1b6d0c5e7a3f\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:05:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"UNDER_REVIEW\"\n  }\n}\n```\n\n`kyc_status` values: `VERIFIED` | `REJECTED` | `UNDER_REVIEW`\n\n`UNDER_REVIEW` is a manual compliance review: the customer is NOT cleared and can take up to\n24 hours (unlike an automated check of a couple of minutes). Do not unlock order creation until\n`VERIFIED`.\n\n**Signature verification**\n\nEvery delivery includes two headers for HMAC-SHA256 verification:\n- `X-Unigox-Signature: sha256=<hex>` — HMAC of `\"<timestamp>.<raw_body>\"`\n- `X-Unigox-Timestamp: <unix_seconds>`\n\nVerification pseudocode:\n```\nexpected = HMAC-SHA256(webhook_secret, \"<timestamp>.<raw_body>\")\nvalid    = constant_time_compare(expected, signature_from_header)\n```\n\n**Delivery guarantees**\n\n- At-least-once delivery. Your endpoint may receive the same event more than once.\n- De-duplicate by `event_id`.\n- Respond with any 2xx status within 10 seconds to acknowledge receipt.\n\n**Retry policy**\n\nFailed deliveries (non-2xx or timeout) are retried with exponential backoff:\n1 min → 5 min → 15 min → 1 h → 6 h → 12 h → 24 h (max 10 attempts over ~3.5 days).\n\n**Partner-facing statuses** (`order.status.changed`)\n\n| Status | Description |\n|---|---|\n| `created` | Order created |\n| `awaiting_liquidity_provider` | Waiting for vendor match |\n| `awaiting_crypto_transfer_authorization` | Partner must authorize crypto transfer |\n| `crypto_transfer_authorization_pending` | Authorization submitted, awaiting on-chain confirmation |\n| `price_changed_requote_needed` | Slippage exceeded at initiation; create a new quote |\n| `crypto_received` | Crypto received in escrow |\n| `fiat_payment_started` | Buyer submitted fiat payment proof |\n| `fiat_payment_review_started` | Payment proof under review |\n| `awaiting_fiat_received_confirmation` | Proof approved, awaiting seller confirmation |\n| `completed` | Order completed, crypto released |\n| `cancelled` | Order cancelled or payment declined |\n| `failed` | Escrow error, or fiat-anchored safety bound exceeded (see below) |\n| `dispute_started` | Dispute opened |\n| `settlement_in_progress` | Delayed settlement (T+1): the release of the crypto has started or is confirmed, and the fiat has not arrived |\n| `returned` | Delayed settlement (T+1): the bank sent the payout back and no new attempt has been approved yet |\n| `awaiting_vendor_escrow_funding` | On-ramp: vendor accepted, funding escrow with crypto |\n| `awaiting_fiat_transfer` | On-ramp: crypto locked in escrow, waiting for the fiat payment |\n| `fiat_transfer_pending` | On-ramp: fiat payment confirmed, awaiting vendor confirmation of receipt |\n| `send_out_pending` | On-ramp send-out: cross-chain transfer in progress |\n| `send_out_completed` | On-ramp send-out: delivered on the destination chain |\n| `send_out_failed` | On-ramp send-out: cross-chain transfer failed; the on-ramp itself stays completed |\n\n**Fiat-anchored safety bound failure**\n\nFor fiat-anchored off-ramp orders (`anchor_type: \"fiat\"`), if the crypto cost we quote exceeds\n1.20× the expected amount at the time of settlement, the order moves to `failed` status asynchronously\n(not during `/initiate`). The deposit is automatically refunded from escrow back to the partner wallet.\nCreate a new quote to retry the trade flow.\n\n**Settlement notifications (recipient received the fiat)**\n\nSome liquidity providers automatically confirm when the fiat payout reaches the\nrecipient's bank account or mobile wallet. When the provider matched to an order\nsupports this, the order moves to `completed` on its own and you receive an\n`order.status.changed` webhook with `status=completed` — that webhook is your signal\nthat the recipient has actually received the money.\n\nWhether the matched provider sends this is reported per order by the\n`has_fiat_settlement_notification` field on the **quote** and **order** responses:\n\n- `true` — the matched provider sends an automatic settlement confirmation. You will\n  receive the `completed` webhook once fiat is delivered; no manual action is needed.\n- `false` — no automatic confirmation for this order. Confirm delivery yourself by\n  calling `confirm-fiat-received` (or rely on your own banking/payment systems).\n\nA delayed settlement (T+1) quote, and a T+1 order once a liquidity provider has accepted\nit, always read `true`: the fiat leg ends in the `completed` webhook, and\n`confirm-fiat-received` refuses it. Every order a liquidity provider has not accepted yet,\nT+1 included, reads `false`; read the flag again after acceptance.\n\nTo match **only** providers that send settlement notifications, pass\n`has_fiat_settlement_notification: true` in the quote request — providers that can't\noffer it are then excluded from matching.\n\nAvailability is provider- and corridor-dependent: not every currency has a provider\nthat sends settlement notifications, so always read the flag on each quote rather than\nassuming it. Manual `confirm-fiat-received` and the automatic confirmation are mutually\nidempotent — whichever happens first wins and the other is a safe no-op.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"WebhookEventPage":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"since":{"type":"string","format":"date-time","description":"The lower bound this page was read from (the default is shown when you sent none)."},"has_more":{"type":"boolean","description":"More events match beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Pass as `cursor` for the next page. Set on every non-empty page."}}},"WebhookEvent":{"type":"object","description":"One event as it was signed and sent (`event_id`, `event_type`, `created_at`, `data`), with\n`delivery` added. `data` is the event's own payload; see each event type.\n","properties":{"event_id":{"type":"string"},"event_type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true},"delivery":{"$ref":"#/components/schemas/WebhookEventDelivery"}}},"WebhookEventDelivery":{"type":"object","description":"How the delivery of one event stands.","properties":{"status":{"type":"string","enum":["pending","in_progress","delivered","failed"],"description":"`pending`: waiting for its (next) attempt. `in_progress`: being sent now.\n`delivered`: your endpoint answered 2xx. `failed`: no more attempts, or never sent\n(see `failure_reason`).\n"},"attempts":{"type":"integer","description":"Delivery attempts made so far (reset to 0 by redeliver)."},"delivered_at":{"type":"string","format":"date-time","nullable":true,"description":"When your endpoint last accepted it."},"last_http_status":{"type":"integer","nullable":true,"description":"Your endpoint's HTTP status on the last attempt; null when there was no answer."},"failure_reason":{"type":"string","nullable":true,"enum":["webhook_disabled","webhook_url_not_set","http_error","network_error","delivery_failed",null],"description":"Why the last attempt did not succeed. `webhook_disabled` / `webhook_url_not_set`: the\nevent was never sent because of your webhook settings. `http_error`: your endpoint\nanswered non-2xx (see `last_http_status`). `network_error`: no answer (connect, TLS,\ntimeout). Null when delivered, or when requeued and not yet attempted.\n"}}},"WebhookErrorResponse":{"type":"object","description":"The error shape the partner webhook endpoints answer with.","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}},"paths":{"/api/v1/partner/webhooks/events":{"get":{"tags":["Webhooks"],"summary":"List webhook events (replay)","description":"Read back the webhook events sent to you, oldest first, with how each delivery went.\nUse it to catch up after your endpoint was down or your webhook was switched off, or to\nreconcile what you processed against what was sent.\n\nEach item is the event **exactly as it was signed and sent** (`event_id`, `event_type`,\n`created_at`, `data`) with a `delivery` object added, so the same code that handles the\nlive webhook can process it. Deduplicate on `event_id`, as you do for live deliveries.\n\n**Which events appear.** Events delivered through Unigox's retrying event queue:\n`order.status.changed`, `order.refund.required`, `order.own_account_payout.updated`,\n`user.kyc.updated`, `business_customer.kyb.updated`, `fiat_account.updated` when an account\nis closed, and the business account events `fiat_account.deposit.received`,\n`fiat_account.payment.sent` and `fiat_account.payment.updated`. The retail\n`fiat_account.deposit.received`, other `fiat_account.updated` notices and test events are\nsent once and are not retried. `wallet.deposit.received` is retried on its own schedule\n(see Webhooks). None of these appear here.\n\n**Events from while your webhook was off are listed too.** They were never sent: their\n`delivery.status` is `failed` with `failure_reason: webhook_disabled`. Read them here, or\nask for one to be sent with the redeliver endpoint once your webhook is on.\n\n**Paging.** Pass `next_cursor` back as `cursor` for the next page. `next_cursor` is set\non every non-empty page, including the last one, so you can keep polling with it; an\nempty page returns the cursor you sent. When `cursor` is sent without `since`, the cursor\nalone is the starting point. An event is stamped when the change that raised it began, so\none can become visible slightly after a later-stamped one: when polling, re-read with a\nsmall overlap (`since` a few minutes back) and deduplicate on `event_id`.\n","operationId":"listWebhookEvents","parameters":[{"name":"since","in":"query","required":false,"description":"RFC 3339 timestamp; events created at or after it. Default: 24 hours ago, or no lower\nbound when `cursor` is sent.\n","schema":{"type":"string","format":"date-time"}},{"name":"event_type","in":"query","required":false,"description":"Only events of this type (exact match).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50, maximum 200 (larger values are read as 200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` of the previous page. Opaque; do not build it yourself.","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of events","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEventPage"}}}]}}}},"400":{"description":"Malformed `since`, `limit` or `cursor`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key"}}}}}}
````

## Redeliver a webhook event

> Send one of your events again: same \`event\_id\`, same payload, a fresh signature and\
> timestamp, and the full retry schedule (up to 10 attempts with backoff), as for a new\
> event. Delivery happens within seconds; the response confirms it is queued, not that your\
> endpoint accepted it — read the event back with \`GET /api/v1/partner/webhooks/events\` to\
> follow it. The previous \`delivered\_at\` / \`last\_http\_status\` stay until the new attempt\
> replaces them.\
> \
> Your webhook must be registered and enabled; an event that is being delivered at this\
> moment returns \`409\`, retry a few seconds later.<br>

````json
{"openapi":"3.0.3","info":{"title":"Unigox API Gateway","version":"1.0.0"},"tags":[{"name":"Webhooks","description":"Signed notifications for orders, KYC/KYB, fiat accounts, business customers and wallet deposits.\nThe system sends a signed HTTP POST to your configured webhook URL on every relevant event.\n\n**Event model**\n\nThese event types are delivered:\n\n| Event type | Fired when |\n|---|---|\n| `order.status.changed` | An order transitions to a new status |\n| `order.refund.required` | An order's crypto is stuck in escrow and only your signature can return it |\n| `user.kyc.updated` | A user's KYC verification is approved, declined or put on manual review |\n| `fiat_account.updated` | An issued fiat account changes status. No money moved. |\n| `fiat_account.deposit.received` | Money arrived on an issued fiat account. Not sent for a credit matched to exactly one off-ramp paid through that account, which `order.own_account_payout.updated` covers. A business customer's account sends it with `holder_type: business` |\n| `fiat_account.payment.sent` | Money left a business customer's account |\n| `fiat_account.payment.updated` | A transfer on a business customer's account reached a new status (`pending`, `confirmed`, `sent`, `blocked`, `refused`, `refunded`…) |\n| `business_customer.kyb.updated` | A business customer's KYB status changed |\n| `order.own_account_payout.updated` | An off-ramp paid through the customer's own fiat account was sent on to the bank, or stopped on the account |\n| `wallet.linked` | An external-wallet customer linked their address |\n| `wallet.deposit.received` | A bridge payment was credited to a linked customer wallet on XAI |\n| `wallet.withdrawal.status.changed` | A customer withdrawal from an external wallet changed status |\n\n**Customer wallet events**\n\n`wallet.linked` carries `user_uuid`, `address` and `linked_at`. The link response and\n`GET /api/v1/partner/users/{user_uuid}/wallet` confirm the link even if that notification\nis not delivered. This event has no automatic delivery retry.\n\n`wallet.deposit.received` reports the credited XAI token and amount, with the source\ntransaction and XAI settlement transaction. It reports supported bridge credits to linked\nwallets, not every transfer into that wallet. It does not include a memo or memo-lock ID.\n\n```json\n{\n  \"event_id\": \"evt_dep_42_12345\",\n  \"event_type\": \"wallet.deposit.received\",\n  \"created_at\": \"2026-10-18T10:01:00Z\",\n  \"data\": {\n    \"deposit_id\": \"intent:12345\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"address\": \"0x1111111111111111111111111111111111111111\",\n    \"chain_id\": \"660279\",\n    \"crypto_currency\": \"USDC\",\n    \"token_address\": \"0x37bf70ee0dc89a408de31b79cccc3152f0c8af43\",\n    \"amount\": \"1\",\n    \"amount_atomic\": \"1000000\",\n    \"source_chain_id\": \"8453\",\n    \"source_tx_hash\": \"0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n    \"tx_hash\": \"0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n    \"credited_at\": \"2026-10-18T10:00:00Z\"\n  }\n}\n```\n\nRegister and enable your webhook before accepting deposits. Deposit notifications retry\nfailed delivery with the same `event_id` (first retry after 30 s, the wait doubling up to 6 h, at most\n10 attempts); `data.deposit_id` identifies the credited payment.\nProcess each deposit once within your partner account and environment. Return a 2xx after\naccepting the event. Delivery is bounded; disabling a webhook does not queue a later replay.\nBoth wallet events use the partner signature scheme described below. `created_at` and the\ndelivery signature can change on retry; `credited_at` is the settlement time.\n\n**Payload shape — the fiat account events**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"fiat_account.deposit.received\",\n  \"created_at\": \"2026-09-18T10:04:23Z\",\n  \"data\": {\n    \"fiat_account_id\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n    \"holder_type\": \"retail\",\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"transaction_id\": \"5f1b2c9a-1d44-4f0e-9c1a-2b5f0d7e9a31\",\n    \"amount\": \"500.00\",\n    \"currency\": \"EUR\",\n    \"order_id\": null\n  }\n}\n```\n\n`order_id` is the on-ramp this deposit funded, or `null` when it matched no order.\nThe event is not sent for a credit matched to exactly one off-ramp paid through the customer's\nown fiat account (`payout_via_own_account: true`); `order.own_account_payout.updated` reports\nthat money instead. Any other credit still sends it, including one held for review because it\ncannot be tied to a single order.\n`fiat_account.updated` carries `fiat_account_id`, `user_uuid`, `status` and `currency`.\nA business customer's account sends `fiat_account.deposit.received` (with `holder_type: business`)\nand `fiat_account.payment.sent` / `fiat_account.payment.updated` with a different `data`; see\nBusiness customers, Webhooks.\n\n**Payload shape — `order.own_account_payout.updated`**\n\nSent only on an off-ramp paid through the customer's own fiat account\n(`payout_via_own_account: true`), when the onward payment to the bank you named reaches\n`sent_to_bank`, `held`, `under_review` or `left_on_account`, once per change of state. It does\nnot change the order's `status`. The provider's payment into the customer's account, once\nmatched to the order, does not send `fiat_account.deposit.received`.\n\n```json\n{\n  \"event_id\": \"evt_own_account_payout_1234_sent_to_bank_3f9a1c0b7d2e4a55\",\n  \"event_type\": \"order.own_account_payout.updated\",\n  \"created_at\": \"2026-10-16T12:00:00Z\",\n  \"data\": {\n    \"order_id\": \"9f1c6b7e-0000-4000-8000-000000000042\",\n    \"user_uuid\": \"c0ffee00-0000-4000-8000-000000000001\",\n    \"own_account_payout_status\": \"sent_to_bank\",\n    \"fiat_account_id\": \"6b1d2c3e-0000-4000-8000-000000000007\",\n    \"amount\": \"250.00\",\n    \"currency\": \"EUR\"\n  }\n}\n```\n\n`fiat_account_id` is omitted when the account is not one you can address by id. `amount` is a\ndecimal string with at least two decimals.\n\nAll events share the same envelope (`event_id`, `event_type`, `created_at`, `data`)\nand the same signature scheme. The structure of the `data` object differs per event type.\n\n**Payload shape — `order.status.changed`**\n\n```json\n{\n  \"event_id\": \"evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"event_type\": \"order.status.changed\",\n  \"created_at\": \"2026-02-01T12:00:05Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"crypto_received\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"101.5\",\n    \"crypto_currency\": \"USDT\",\n    \"partner_fee\": \"1\",\n    \"partner_fee_pct\": 1,\n    \"fiat_amount\": \"152880.00\",\n    \"fiat_currency\": \"NGN\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\"\n  }\n}\n```\n\n`user_id` is the customer's `user_uuid`.\n\n**Payload shape — `order.refund.required`**\n\nFired when an off-ramp order has stopped without a payout and its crypto is still in escrow.\nThis has its own event type because there is no status change to carry it: the order reads\n`cancelled` from the moment it stopped, exactly like an order whose refund was already paid out,\nso a listener filtering on status transitions would never learn that anything is owed. It is\nsent **at most once per order**, and the same information is on `GET /orders/{order_id}` for as\nlong as it stays true.\n\nThe `data` object is the order.status.changed payload plus `action_required`.\n\n```json\n{\n  \"event_id\": \"evt_refund_required_b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n  \"event_type\": \"order.refund.required\",\n  \"created_at\": \"2026-09-09T09:14:00Z\",\n  \"data\": {\n    \"order_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n    \"status\": \"cancelled\",\n    \"user_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"crypto_amount\": \"1000.25\",\n    \"crypto_currency\": \"USDT\",\n    \"fiat_amount\": \"3070.50\",\n    \"fiat_currency\": \"KWD\",\n    \"provider\": \"p2p\",\n    \"payment_details_id\": \"987\",\n    \"action_required\": {\n      \"type\": \"authorize_refund\",\n      \"message\": \"This order ended without a payout and the crypto is still in escrow. ...\",\n      \"endpoint\": \"POST /api/v1/partner/orders/{order_id}/authorize-refund\"\n    }\n  }\n}\n```\n\nAct on it with the refund pair: `GET /orders/{order_id}/refund-authorization-parameters` for the\ntransaction to sign, then `POST /orders/{order_id}/authorize-refund` with the signature. Nobody\nelse can produce that signature — the escrow needs two of its three owners, we hold one key and\nyou hold the other.\n\n**Payload shape — `user.kyc.updated`**\n\nFired when a user's KYC status changes — to `VERIFIED`, `REJECTED`, or to a manual compliance\nreview hold (`UNDER_REVIEW`). Use this event to unlock order creation for the user on your side\n(only on `VERIFIED`; `UNDER_REVIEW` is not cleared).\n\n```json\n{\n  \"event_id\": \"evt_2d8418dd-e3a8-4463-a11e-6b54f354ca90\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T11:37:42Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"VERIFIED\"\n  }\n}\n```\n\nWhen KYC is declined, `rejection_reasons` is included:\n\n```json\n{\n  \"event_id\": \"evt_fc75484d-b374-4d05-b54e-820f3dd80e6d\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:00:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"REJECTED\",\n    \"rejection_reasons\": [\"Document expired\", \"Photo quality low\"]\n  }\n}\n```\n\nWhen a customer is placed on a manual compliance review hold, `kyc_status` is `UNDER_REVIEW`:\n\n```json\n{\n  \"event_id\": \"evt_9a1c7f20-4d3b-4e88-9f2a-1b6d0c5e7a3f\",\n  \"event_type\": \"user.kyc.updated\",\n  \"created_at\": \"2026-03-10T12:05:00Z\",\n  \"data\": {\n    \"user_uuid\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"kyc_status\": \"UNDER_REVIEW\"\n  }\n}\n```\n\n`kyc_status` values: `VERIFIED` | `REJECTED` | `UNDER_REVIEW`\n\n`UNDER_REVIEW` is a manual compliance review: the customer is NOT cleared and can take up to\n24 hours (unlike an automated check of a couple of minutes). Do not unlock order creation until\n`VERIFIED`.\n\n**Signature verification**\n\nEvery delivery includes two headers for HMAC-SHA256 verification:\n- `X-Unigox-Signature: sha256=<hex>` — HMAC of `\"<timestamp>.<raw_body>\"`\n- `X-Unigox-Timestamp: <unix_seconds>`\n\nVerification pseudocode:\n```\nexpected = HMAC-SHA256(webhook_secret, \"<timestamp>.<raw_body>\")\nvalid    = constant_time_compare(expected, signature_from_header)\n```\n\n**Delivery guarantees**\n\n- At-least-once delivery. Your endpoint may receive the same event more than once.\n- De-duplicate by `event_id`.\n- Respond with any 2xx status within 10 seconds to acknowledge receipt.\n\n**Retry policy**\n\nFailed deliveries (non-2xx or timeout) are retried with exponential backoff:\n1 min → 5 min → 15 min → 1 h → 6 h → 12 h → 24 h (max 10 attempts over ~3.5 days).\n\n**Partner-facing statuses** (`order.status.changed`)\n\n| Status | Description |\n|---|---|\n| `created` | Order created |\n| `awaiting_liquidity_provider` | Waiting for vendor match |\n| `awaiting_crypto_transfer_authorization` | Partner must authorize crypto transfer |\n| `crypto_transfer_authorization_pending` | Authorization submitted, awaiting on-chain confirmation |\n| `price_changed_requote_needed` | Slippage exceeded at initiation; create a new quote |\n| `crypto_received` | Crypto received in escrow |\n| `fiat_payment_started` | Buyer submitted fiat payment proof |\n| `fiat_payment_review_started` | Payment proof under review |\n| `awaiting_fiat_received_confirmation` | Proof approved, awaiting seller confirmation |\n| `completed` | Order completed, crypto released |\n| `cancelled` | Order cancelled or payment declined |\n| `failed` | Escrow error, or fiat-anchored safety bound exceeded (see below) |\n| `dispute_started` | Dispute opened |\n| `settlement_in_progress` | Delayed settlement (T+1): the release of the crypto has started or is confirmed, and the fiat has not arrived |\n| `returned` | Delayed settlement (T+1): the bank sent the payout back and no new attempt has been approved yet |\n| `awaiting_vendor_escrow_funding` | On-ramp: vendor accepted, funding escrow with crypto |\n| `awaiting_fiat_transfer` | On-ramp: crypto locked in escrow, waiting for the fiat payment |\n| `fiat_transfer_pending` | On-ramp: fiat payment confirmed, awaiting vendor confirmation of receipt |\n| `send_out_pending` | On-ramp send-out: cross-chain transfer in progress |\n| `send_out_completed` | On-ramp send-out: delivered on the destination chain |\n| `send_out_failed` | On-ramp send-out: cross-chain transfer failed; the on-ramp itself stays completed |\n\n**Fiat-anchored safety bound failure**\n\nFor fiat-anchored off-ramp orders (`anchor_type: \"fiat\"`), if the crypto cost we quote exceeds\n1.20× the expected amount at the time of settlement, the order moves to `failed` status asynchronously\n(not during `/initiate`). The deposit is automatically refunded from escrow back to the partner wallet.\nCreate a new quote to retry the trade flow.\n\n**Settlement notifications (recipient received the fiat)**\n\nSome liquidity providers automatically confirm when the fiat payout reaches the\nrecipient's bank account or mobile wallet. When the provider matched to an order\nsupports this, the order moves to `completed` on its own and you receive an\n`order.status.changed` webhook with `status=completed` — that webhook is your signal\nthat the recipient has actually received the money.\n\nWhether the matched provider sends this is reported per order by the\n`has_fiat_settlement_notification` field on the **quote** and **order** responses:\n\n- `true` — the matched provider sends an automatic settlement confirmation. You will\n  receive the `completed` webhook once fiat is delivered; no manual action is needed.\n- `false` — no automatic confirmation for this order. Confirm delivery yourself by\n  calling `confirm-fiat-received` (or rely on your own banking/payment systems).\n\nA delayed settlement (T+1) quote, and a T+1 order once a liquidity provider has accepted\nit, always read `true`: the fiat leg ends in the `completed` webhook, and\n`confirm-fiat-received` refuses it. Every order a liquidity provider has not accepted yet,\nT+1 included, reads `false`; read the flag again after acceptance.\n\nTo match **only** providers that send settlement notifications, pass\n`has_fiat_settlement_notification: true` in the quote request — providers that can't\noffer it are then excluded from matching.\n\nAvailability is provider- and corridor-dependent: not every currency has a provider\nthat sends settlement notifications, so always read the flag on each quote rather than\nassuming it. Manual `confirm-fiat-received` and the automatic confirmation are mutually\nidempotent — whichever happens first wins and the other is a safe no-op.\n"}],"servers":[{"url":"https://api-staging.unigox.com","description":"Sandbox server"},{"url":"https://api.unigox.com","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Partner API key for authentication. Required for all partner account endpoints."}},"schemas":{"APIResponse":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Indicates if the request was successful"},"data":{"description":"Response data (structure varies by endpoint) or error information if success is false"}}},"WebhookEvent":{"type":"object","description":"One event as it was signed and sent (`event_id`, `event_type`, `created_at`, `data`), with\n`delivery` added. `data` is the event's own payload; see each event type.\n","properties":{"event_id":{"type":"string"},"event_type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true},"delivery":{"$ref":"#/components/schemas/WebhookEventDelivery"}}},"WebhookEventDelivery":{"type":"object","description":"How the delivery of one event stands.","properties":{"status":{"type":"string","enum":["pending","in_progress","delivered","failed"],"description":"`pending`: waiting for its (next) attempt. `in_progress`: being sent now.\n`delivered`: your endpoint answered 2xx. `failed`: no more attempts, or never sent\n(see `failure_reason`).\n"},"attempts":{"type":"integer","description":"Delivery attempts made so far (reset to 0 by redeliver)."},"delivered_at":{"type":"string","format":"date-time","nullable":true,"description":"When your endpoint last accepted it."},"last_http_status":{"type":"integer","nullable":true,"description":"Your endpoint's HTTP status on the last attempt; null when there was no answer."},"failure_reason":{"type":"string","nullable":true,"enum":["webhook_disabled","webhook_url_not_set","http_error","network_error","delivery_failed",null],"description":"Why the last attempt did not succeed. `webhook_disabled` / `webhook_url_not_set`: the\nevent was never sent because of your webhook settings. `http_error`: your endpoint\nanswered non-2xx (see `last_http_status`). `network_error`: no answer (connect, TLS,\ntimeout). Null when delivered, or when requeued and not yet attempted.\n"}}},"WebhookErrorResponse":{"type":"object","description":"The error shape the partner webhook endpoints answer with.","required":["success","error"],"properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}},"paths":{"/api/v1/partner/webhooks/events/{event_id}/redeliver":{"post":{"tags":["Webhooks"],"summary":"Redeliver a webhook event","description":"Send one of your events again: same `event_id`, same payload, a fresh signature and\ntimestamp, and the full retry schedule (up to 10 attempts with backoff), as for a new\nevent. Delivery happens within seconds; the response confirms it is queued, not that your\nendpoint accepted it — read the event back with `GET /api/v1/partner/webhooks/events` to\nfollow it. The previous `delivered_at` / `last_http_status` stay until the new attempt\nreplaces them.\n\nYour webhook must be registered and enabled; an event that is being delivered at this\nmoment returns `409`, retry a few seconds later.\n","operationId":"redeliverWebhookEvent","parameters":[{"name":"event_id","in":"path","required":true,"description":"The event's `event_id`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Queued for delivery. The event as it now stands.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/APIResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEvent"}}}]}}}},"400":{"description":"No webhook URL registered (`WEBHOOK_URL_NOT_SET`) or webhook switched off (`WEBHOOK_DISABLED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key"},"404":{"description":"No such event for your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorResponse"}}}},"409":{"description":"The event is being delivered right now; retry shortly","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookErrorResponse"}}}}}}}}}
````
