Card Issuing

Card webhooks

Real-time events for onboarding, wallets, and cards

View as Markdown

The Card API is asynchronous — onboarding, KYB, deposits, card issuing, and transactions all complete in the background. Subscribe to webhooks to be notified the moment state changes, instead of polling.

Manage your webhook endpoints (URL, subscribed events, signing secret) in the Partner Platform → Developer → Webhook endpoints.

Payload structure

Every event is delivered as an HTTP POST with this envelope:

1{
2  "id": "unique_event_id",
3  "type": "card.transaction.created",
4  "payload": {
5    // event-specific fields (see below)
6  },
7  "createdAt": "2026-08-03T12:00:00Z"
8}

Verifying signatures

Each request includes an X-Signature header — an HMAC-SHA256 hex digest of the raw request body, keyed by your endpoint’s signing secret. Recompute it and compare using a constant-time function. See the general Webhook guide for full code samples (Node.js, PHP, Go, Java).

Retries

If your endpoint doesn’t return a 2xx, we retry with exponential backoff, up to 5 attempts (10s, 30s, 1m, 2m, 5m).

Events

EventWhen it fires
company.onboarding_status_changedA company’s onboarding status changes
company.kyb_status_changedA company’s KYB status changes
wallet.createdA wallet is created
wallet_address.createdA deposit address is provisioned
wallet.deposit_receivedFunds are received on a wallet address
card_holder.status_changedA card holder’s status changes
card.status_changedA card is issued / activated / frozen / closed
card.transaction.createdA new card transaction is recorded
card.transaction.updatedA card transaction changes (amount cleared / status)
card.otp.issuedA 3DS OTP is issued for a card payment

company.onboarding_status_changed

1{ "companyId": "01KZ2WJKWVFPCVAB6MY106QRZV", "status": "ACTIVE" }

company.kyb_status_changed

1{ "companyId": "01KZ2WJKWVFPCVAB6MY106QRZV", "status": "APPROVED" }

wallet.created

1{ "companyId": "01KZ2WJK...", "walletId": "01KZ2WXM...", "currency": "USDC" }

wallet_address.created

1{
2  "companyId": "01KZ2WJK...",
3  "walletId": "01KZ2WXM...",
4  "address": "0xa03cb11b9cb10915439f316fe66f2e32d5df806c",
5  "chain": "ETH",
6  "currency": "USDC"
7}

wallet.deposit_received

1{
2  "companyId": "01KZ2WJK...",
3  "walletId": "01KZ2WXM...",
4  "transactionId": "01KZ2TXN...",
5  "amount": "100.00",
6  "currency": "USDC",
7  "status": "Settled"
8}

card_holder.status_changed

1{ "companyId": "01KZ2WJK...", "cardHolderId": "01KZ2CH...", "status": "ACTIVE" }

card.status_changed

1{ "companyId": "01KZ2WJK...", "cardId": "01KZ2CARD...", "status": "Active" }

card.transaction.created / card.transaction.updated

1{
2  "id": "01KZ2TXN...",
3  "cardId": "01KZ2CARD...",
4  "type": "Consumption",
5  "status": "Settled",
6  "amount": "5.00",
7  "currency": "USD",
8  "clearedAmount": "5.00",
9  "merchantName": "FACEBK *XFDFYYMYL2",
10  "createdAt": "2026-08-03T13:28:22Z"
11}

card.otp.issued

The partner is responsible for delivering the OTP to the end user — AlphaX does not email it.

1{
2  "companyId": "01KZ2WJK...",
3  "cardId": "01KZ2CARD...",
4  "last4": "4242",
5  "otp": "123456",
6  "amount": "5",
7  "currency": "USD",
8  "expiresAt": "2026-08-03T13:33:22Z"
9}