Webhooks

ZayPay can notify your app in real time when an order status changes.

This is useful for dApps like wallets or launchpads to:

• Update user balances immediately

• Trigger notifications (e.g. when a swap completes or fails)

• Start follow-up workflows

Setup

👉 To enable webhooks, contact your Zay Pay account manager and provide them with the HTTPS URL of your webhook endpoint.

Requirements:

• The URL must be HTTPS (in production)

• Must accept POST requests

• Must return a 2xx response on success

Webhook Body Format

Each webhook request is sent as a JSON object in the request body.

Field	Type	Description
event_type	string	Type of the event. Possible values: order_status_changed.
subject_type	string	Type of the object that triggered the event. Possible values: Order.
subject_id	string	Unique identifier (UUID) of the object that triggered the event.
payload	object	The object data. For orders, this is a full Order object. See the API reference for full schema.

Events

order_status_changed

Sent whenever an order’s status changes.

Order Status Values

The payload.order.status field can take the following values:

• creating – Order is being created

• transfer_pending – Waiting for deposit

• deposit_received – Deposit confirmed

• completed – Order completed successfully

• cancelled – Order was cancelled or expired

• kyc_required – KYC verification needed

• refund_initiated – Refund process started

• refund_completed – Refund completed

• refund_failed – Refund failed

• creation_blocked – Order creation blocked

• creation_rate_limited – Too many requests, creation rate limited

• deposit_only – Deposit-only mode (e.g. SOL to SOL)

Payload Example

{
  "event_type": "order_status_changed",
  "subject_type": "Order",
  "subject_id": "c9d5e882-5ea9-47de-8e49-08b4fe35056e",
  "payload": {
    "order": {
      "id": "c9d5e882-5ea9-47de-8e49-08b4fe35056e",
      "status": "transfer_pending",
      "created_at": 1758698269,
      "user_confirmed_payment": false,
      "withdraw_address": {
        "address": "8q9h2h9676VcMU6YjxTC5kCp2jT1fMgCa1HbJNX4VxFf"
      },
      "pair": {
        "id": "SOLUSDTSOL",
        "from_token": {
          "id": "usdt",
          "name": "USDT",
          "full_name": "Tether",
          "icon": "https://sfo2.digitaloceanspaces.com/exchange-widget/uploads/token/icon/usdt/usdt.png",
          "decimals_before": 18,
          "decimals_after": 3
        },
        "from_chain": {
          "id": "sol",
          "name": "Solana",
          "icon": "https://sfo2.digitaloceanspaces.com/exchange-widget/uploads/chain/icon/sol/sol.png",
          "token_icon": "https://sfo2.digitaloceanspaces.com/exchange-widget/uploads/pair/from_token_icon/SOLUSDTSOL/usdt.png"
        },
        "to_token": {
          "id": "sol",
          "name": "SOL",
          "full_name": "Solana",
          "icon": "https://sfo2.digitaloceanspaces.com/exchange-widget/uploads/token/icon/sol/sol.png",
          "decimals_before": 18,
          "decimals_after": 5
        },
        "to_chain": {
          "id": "sol",
          "name": "Solana",
          "icon": "https://sfo2.digitaloceanspaces.com/exchange-widget/uploads/chain/icon/sol/sol.png"
        }
      },
      "min_deposit_amount": "11.934",
      "max_deposit_amount": "134309484.591624",
      "rate": "0.004645552",
      "unique_reference": "OAFQJP",
      "withdrawal_fee": "0.00204937",
      "deposit_address": {
        "address": "4J7KthvURfcMBhZzYH6wXWnfPCXd2mjgJTGrUziP4hcU"
      },
      "expires_at": 1758698870
    }
  },
  "created_at": "2025-09-24T07:17:52Z"
}