> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alphax.asia/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alphax.asia/_mcp/server.

# Card webhooks

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:

```json
{
  "id": "unique_event_id",
  "type": "card.transaction.created",
  "payload": {
    // event-specific fields (see below)
  },
  "createdAt": "2026-08-03T12:00:00Z"
}
```

## 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](/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

| Event                               | When it fires                                        |
| ----------------------------------- | ---------------------------------------------------- |
| `company.onboarding_status_changed` | A company's onboarding status changes                |
| `company.kyb_status_changed`        | A company's KYB status changes                       |
| `wallet.created`                    | A wallet is created                                  |
| `wallet_address.created`            | A deposit address is provisioned                     |
| `wallet.deposit_received`           | Funds are received on a wallet address               |
| `card_holder.status_changed`        | A card holder's status changes                       |
| `card.status_changed`               | A card is issued / activated / frozen / closed       |
| `card.transaction.created`          | A new card transaction is recorded                   |
| `card.transaction.updated`          | A card transaction changes (amount cleared / status) |
| `card.otp.issued`                   | A 3DS OTP is issued for a card payment               |

### company.onboarding\_status\_changed

```json
{ "companyId": "01KZ2WJKWVFPCVAB6MY106QRZV", "status": "ACTIVE" }
```

### company.kyb\_status\_changed

```json
{ "companyId": "01KZ2WJKWVFPCVAB6MY106QRZV", "status": "APPROVED" }
```

### wallet.created

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

### wallet\_address.created

```json
{
  "companyId": "01KZ2WJK...",
  "walletId": "01KZ2WXM...",
  "address": "0xa03cb11b9cb10915439f316fe66f2e32d5df806c",
  "chain": "ETH",
  "currency": "USDC"
}
```

### wallet.deposit\_received

```json
{
  "companyId": "01KZ2WJK...",
  "walletId": "01KZ2WXM...",
  "transactionId": "01KZ2TXN...",
  "amount": "100.00",
  "currency": "USDC",
  "status": "Settled"
}
```

### card\_holder.status\_changed

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

### card.status\_changed

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

### card.transaction.created / card.transaction.updated

```json
{
  "id": "01KZ2TXN...",
  "cardId": "01KZ2CARD...",
  "type": "Consumption",
  "status": "Settled",
  "amount": "5.00",
  "currency": "USD",
  "clearedAmount": "5.00",
  "merchantName": "FACEBK *XFDFYYMYL2",
  "createdAt": "2026-08-03T13:28:22Z"
}
```

### card.otp.issued

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

```json
{
  "companyId": "01KZ2WJK...",
  "cardId": "01KZ2CARD...",
  "last4": "4242",
  "otp": "123456",
  "amount": "5",
  "currency": "USD",
  "expiresAt": "2026-08-03T13:33:22Z"
}
```