Webhooks

Quick summary

Workflow steps

1. Create a subscription

   POST your callback URL to /api/v1/wh/subscribe.

2. Receive encrypted deliveries

   We POST an encrypted payload to your endpoint with the API-KEY header.

3. Decrypt and acknowledge

   Decrypt the payload and reply with HTTP 200 and { "success": true }. This response is not encrypted.

   Success response

   Return plain JSON (not encrypted).

   SchemaWebhookDeliveryAck

   Field	Type	Required	Description
   success	boolean	Required	Must be true to stop retries.

   JSON

   {
     "success": true
   }

4. Handle retries and duplicates

   Deliveries are at-least-once. Deduplicate by type and timestamp.

Subscription endpoints

All subscription endpoints are encrypted like other /api/v1/* requests. See Encrypted Payload.

• POST/api/v1/wh/subscribeCreate a webhook subscription for your URL.
• POST/api/v1/wh/unsubscribeDeactivate a subscription by id.
• POST/api/v1/wh/subscriptionsList active subscriptions.

• Subscriptions only receive events created after the subscription is created.
• We do not backfill older events.
• You can register multiple subscriptions per API key (the same event is delivered to each).

Delivery request

Delivery envelope schema

{
  "encrypted": "<base64 string>"
}

Retry behavior

Event types

All event payloads include a type field and are provider-agnostic.

Only for purchase authorizations. We send webhooks for these status/type pairs:

The tx_type value is derived from provider status/type mappings.

{
  "type": "card_transaction",
  "tx_type": "transaction_created_auth_pending",
  "card_id": "697c9b7559fad5ba001068ce",
  "tx_at": "2026-02-03T22:37:11.597606+00:00",
  "card_tx_data": {
    "auth_type": "purchase",
    "status": "pending",
    "type": "auth",
    "card_label": "3691",
    "merchant": {
      "name": "GOOGLE *TEMPORARY HOLD",
      "mcc": "5734"
    },
    "fee_amount": 0.25,
    "fee_currency": "usd",
    "card_currency": "usd",
    "card_amount": 99.0,
    "merchant_currency": "hkd",
    "merchant_amount": 771.2,
    "failure_reason": "Card Blocked"
  }
}

Sent for every card topup result.

{
  "type": "card_topup",
  "card_id": "697c9b7559fad5ba001068ce",
  "tx_at": "2026-02-03T22:37:11.597606+00:00",
  "currency": "usd",
  "received_amount": "30.00",
  "order_id": "69827898db842395ebd4821d"
}

We normalize provider status as in the freeze/unfreeze endpoints. Only the end state is delivered.

{
  "type": "card_status_change",
  "card_id": "697c9b7559fad5ba001068ce",
  "changed_at": "2026-02-03T22:37:11.597606+00:00",
  "new_status": "frozen"
}

OTP payloads include the code and the time it was sent.

{
  "type": "card_otp",
  "card_id": "697c9b7559fad5ba001068ce",
  "code": "687524",
  "sent_at": "2026-02-03T22:37:11.597606+00:00"
}

Sent when an incoming master wallet deposit is detected and credited.

• No card_id (this is a master account balance event).
• Idempotency is based on the deposit transaction hash.

{
  "type": "master_account_topup",
  "status": "completed",
  "currency": "usdt",
  "master_account_balance": {
    "before": "100.00000000000000",
    "after": "150.00000000000000"
  },
  "tx_info": {
    "network": "tron",
    "token": "usdt",
    "address": "T...",
    "txid": "0x...",
    "amount_crypto": "50.00000000000000"
  },
  "credited_at": "2026-02-03T22:37:11.597606+00:00"
}

Idempotency and duplicates

• We avoid duplicate inserts using internal idempotency keys, but delivery is at-least-once.
• Use a deterministic key such as type + timestamp for deduplication.
• Always respond quickly with {"success": true} once your handler has accepted the event.