Webhooks

IMBA POSTs terminal (and smoke-test) events to the HTTPS URL configured for your tenant.

Delivery semantics

At-least-once delivery
Idempotency key: event_id (UUID). Duplicate delivery → return 200 without applying twice
Signature header: X-IMBA-Signature
Content-Type: application/json

Allowlist IMBA egress IPs (list from onboarding / ops) on your firewall if required.

Signature

X-IMBA-Signature: hex(hmac_sha256(<your_webhook_secret>, raw_body))

Verify against the raw request body bytes before JSON parsing. Use the HMAC secret you registered with IMBA. Constant-time compare recommended. The body is not minified: there is a space after every : and ,, and key order is IMBA’s, not alphabetical. Re-serializing the parsed JSON produces a different signature — sign the bytes exactly as received.

Envelope

{
  "event_id": "019d0130-aaaa-7bbb-8ccc-ddddeeeeffff",
  "event": "card_issue.status_changed",
  "occurred_at": "2026-07-10T09:28:00.000Z",
  "data": {
    "ext_id": "card-issue-20260710-003",
    "order_id": "019d0127-fd3c-78cc-ac8e-e36927c03535",
    "ref_id": "019d0127-fd3c-78cc-ac8e-e36927c03535",
    "status": "completed",
    "document_status": "done",
    "card_id": "00112233445566778899aabb",
    "http_status": "200"
  }
}

Field name is event (not event_type).

Event types (v1)

`event`	When
`test.ping`	Oper smoke test
`card_issue.status_changed`	Card issue terminal
`card_topup.status_changed`	Card topup terminal
`card_freeze.status_changed`	Freeze terminal
`withdrawal.status_changed`	Withdrawal terminal
`gift_purchase.status_changed`	Gift purchase terminal
`esim_purchase.status_changed`	eSIM purchase terminal
`esim_topup.status_changed`	eSIM topup terminal
`card.otp`	3-D Secure code for one of your cards (not a status change)

Not in v1: chargebacks, separate reconciliation settled events, unfreeze events.

`data` fields

Minimum: ext_id, status, document_status. Often also ref_id / order_id, card_id, http_status, error / message, and when present amount / currency / network / to_address / offer_id. card.otp is not a status change and has no status / document_status — see below.

`card.otp` — 3-D Secure code

Sent when an acquirer asks for a confirmation code on a card issued to you. The same code goes to the cardholder e-mail you supplied at issue — the webhook does not replace that mail. It exists so your own support can read the code out to the buyer.

{
  "event_id": "019d0130-bbbb-7ccc-8ddd-eeeeffff0000",
  "event": "card.otp",
  "occurred_at": "2026-08-04T16:41:12.480Z",
  "data": {
    "card_id": "00112233445566778899aabb",
    "otp": "424242",
    "merchant": "ANTHROPIC",
    "purpose": "payment",
    "ext_id": "card-issue-20260710-003",
    "order_id": "019d0127-fd3c-78cc-ac8e-e36927c03535",
    "delivery_id": "pin-otp-8f21"
  }
}

Field	Always	Meaning
`card_id`	yes	Hex card id — same value as in `card_issue.status_changed` and `GET /partner/cards/{card_id}`
`otp`	yes	The 3-D Secure code itself — the only field carrying it (there is no `code` field in this event)
`merchant`	when the provider sends it	Shop / service that asked for the code (`ANTHROPIC`, `STEAM`, …)
`purpose`	when the provider sends it	Why the code was asked: a payment, or binding the card to Apple / Google Pay
`ext_id`	when the card was issued via Partner API	Your `ext_id` of the issue order
`order_id`	when known	IMBA order id of the issue (same as in `card_issue`)
`delivery_id`	when the provider sends it	Provider-side delivery id of the code; useful for your own dedupe

No cardholder contacts (e-mail, phone, name) and no card secrets are in the event: card_id + otp already identify the code, and you supplied the holder data yourself at issue. The code lives about 2 minutes. Handle the event immediately; do not queue it behind slow work. Idempotency. A provider retry of the same code on the same card does not create a second event. A new code on the same card is always a new event. Stay idempotent by event_id, and optionally by delivery_id. Only cards issued to a partner tenant produce this event; retail IMBA Wallet cards do not. If your webhook endpoint is missing or disabled there is no event and the cardholder mail goes out as usual.

Secrets — never trust webhooks for these

Secret	Where to fetch
PAN / CVV / `card_encrypted`	`GET /partner/cards/{card_id}`
Gift `epin` / codes	`GET /partner/gift-cards/{purchase_id}`
eSIM LPA / QR	`GET /partner/esims/{esim_id}`

Webhook payloads must not be treated as a source of card numbers, CVV, JWE, epin, or LPA. The single exception is the 3-D Secure code in card.otp (field otp), where the code is the event; there is no pull endpoint for it. Automated delivery of voucher / card credentials after purchase is the product GET, not the webhook. See FAQ.

Smoke test

IMBA can send test.ping from the admin console. Expect HTTP 2xx. Respond 200 for duplicate event_id.

Get started

Money

Products

Operations

Delivery semantics

Signature

Envelope

Event types (v1)

`data` fields

`card.otp` — 3-D Secure code

Secrets — never trust webhooks for these

Smoke test

​Delivery semantics

​Signature

​Envelope

​Event types (v1)

​data fields

​card.otp — 3-D Secure code

​Secrets — never trust webhooks for these

​Smoke test

Delivery semantics

Signature

Envelope

Event types (v1)

`data` fields

`card.otp` — 3-D Secure code

Secrets — never trust webhooks for these

Smoke test