Webhooks

Event Types

Every UC-Card webhook event type with its data fields and an example body.

All events share the same envelope: event_id, event_type, version, event_at, agent_id and data. Compare event_type and data to tell them apart. Signature verification is the same for every event type, see Integration Guide.

UUIDs, amounts and times below are illustrative.

Summary

event_typeGroupDescription
card.request.result NewOperation resultsA card request has finished: the card was issued (SUCCESS) or the request was declined / issuance failed (FAILED).
card.top_up.result NewOperation resultsA card top-up (recharge) has finished, funded either externally or from the internal wallet.
card.withdrawal.result NewOperation resultsA card withdrawal has finished.
card.status.update.result NewOperation resultsA requested card status change (block, unblock, cancel) has succeeded or failed at the provider.
card.update.result NewOperation resultsA change to the card's per-transaction limit has succeeded or failed at the provider.
card.3ds.otp NewOTP and activationA one-time password for 3D Secure online payment confirmation.
card.verification.otp NewOTP and activationA one-time password for card verification.
card.activation.code NewOTP and activationThe activation code for a physical card request.
card.activation.status NewOTP and activationThe provider's card activation result.
card.feeFeeA fee is charged to the card.
card.transaction.authorizationTransactionsA cardholder purchase is approved.
card.transaction.refund NewTransactionsA merchant refund is credited back to the card.
card.transaction.reversal NewTransactionsAn authorization is reversed (for example, cancelled by the merchant) and the funds go back to the card.
card.transaction.settlement.creditTransactionsA transaction settles for less than the authorized amount.
card.transaction.settlement.debitTransactionsA transaction settles for more than the authorized amount.
card.transaction.settlement.reversalTransactionsA settlement is reversed due to an error.
card.transaction.fund.collectionTransactionsAn external source adds funds to the cardholder's card account, as reported by the card network (Visa, Mastercard) and relayed through UC-Pay.
card.transaction.fund.transferTransactionsA fund transfer is processed.
card.transaction.chargeback.creditTransactionsA chargeback credit is applied.
card.transaction.chargeback.debitTransactionsA chargeback debit is applied.

Operation results

card.request.result

New

A card request has finished: the card was issued (SUCCESS) or the request was declined / issuance failed (FAILED). Not sent when the request is only created or approved.

  • status: SUCCESS or FAILED.
  • card_id can be null when issuance failed before a card existed.
  • A physical card is reported only after activation succeeds.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "card_holder_id": "0f8e2c61-7d3b-4b6a-9a51-2b6c4e1d9f07",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "card_request_id": "6df4b096-a437-4b52-9f1d-52ab15ee5193",
    "card_type": "VIRTUAL",
    "currency": "USD",
    "failure_reason": null,
    "status": "SUCCESS"
  },
  "event_at": "2026-10-16T08:00:25.121447Z",
  "event_id": "d06d711a-dced-5c36-8e2c-7ccbb4e48bc9",
  "event_type": "card.request.result",
  "version": "1"
}

card.top_up.result

New

A card top-up (recharge) has finished, funded either externally or from the internal wallet. Payment received alone does not send this event; it waits until the card is credited or the top-up fails.

  • status: SUCCESS or FAILED.
  • card_wallet_transfer_id is present only for internal-wallet funding; it is omitted for external funding.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "100.00",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "card_top_up_id": "a3ead888-cfc5-4ad9-8b68-876e3e8ffb41",
    "card_wallet_transfer_id": "8b597ad4-62c8-4e8a-a626-d5de04c18e81",
    "currency": "USD",
    "failure_reason": null,
    "fee_amount": "2.00",
    "net_amount": "98.00",
    "status": "SUCCESS"
  },
  "event_at": "2026-10-16T08:07:25.121447Z",
  "event_id": "195ee0ef-d2b2-5851-9398-74910a28afb6",
  "event_type": "card.top_up.result",
  "version": "1"
}

card.withdrawal.result

New

A card withdrawal has finished. For withdrawal to an external wallet, this is sent after admin/agent review (APPROVED = SUCCESS, DECLINED = FAILED). For withdrawal to the internal wallet, it is sent when the transfer completes.

  • status: SUCCESS or FAILED.
  • External withdrawal: includes card_withdrawal_id. Internal wallet: includes card_wallet_transfer_id instead.
  • SUCCESS for an external withdrawal means the withdrawal was approved; it is not a blockchain payout confirmation.
  • On FAILED, received_amount is the expected amount, not money received.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "100.00",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "card_withdrawal_id": "794dd4a8-2a22-4148-bc5f-e9ad3d1c711f",
    "currency": "USD",
    "exchange_rate": "1.00",
    "failure_reason": null,
    "fee_amount": "2.00",
    "fee_currency": "USD",
    "received_amount": "98.00",
    "received_currency": "USDT",
    "status": "SUCCESS"
  },
  "event_at": "2026-10-16T08:14:25.121447Z",
  "event_id": "cf56eaf8-93a7-5048-ab3b-59416c1f496a",
  "event_type": "card.withdrawal.result",
  "version": "1"
}

card.status.update.result

New

A requested card status change (block, unblock, cancel) has succeeded or failed at the provider.

  • status: SUCCESS or FAILED.
  • card_status is always the card's actual status after processing. Example: a failed block returns FAILED with ACTIVE.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "card_status": "ACTIVE",
    "failure_reason": "Provider rejected status change",
    "status": "FAILED"
  },
  "event_at": "2026-10-16T08:21:25.121447Z",
  "event_id": "23837adf-128b-557a-b902-614d4b7e7a05",
  "event_type": "card.status.update.result",
  "version": "1"
}

card.update.result

New

A change to the card's per-transaction limit has succeeded or failed at the provider.

  • status: SUCCESS or FAILED.
  • On FAILED, limit_per_transaction is the current stored limit, not the rejected value.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "failure_reason": null,
    "limit_per_transaction": "250.00",
    "status": "SUCCESS"
  },
  "event_at": "2026-10-16T08:28:25.121447Z",
  "event_id": "17997b4e-7e83-51e2-b4c8-593f3e0df68e",
  "event_type": "card.update.result",
  "version": "1"
}

OTP and activation

card.3ds.otp

New

A one-time password for 3D Secure online payment confirmation. Pass it to the cardholder.

  • No status field. It does not confirm a payment outcome.
  • otp is text: keep leading zeros.
  • reference_code, amount, currency and merchant_name are omitted when empty.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "25.00",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "merchant_name": "Example Merchant",
    "otp": "001234",
    "reference_code": "payment-reference-123"
  },
  "event_at": "2026-10-16T08:35:25.121447Z",
  "event_id": "773aa0f4-e66d-52d7-b83c-942ddc509ed5",
  "event_type": "card.3ds.otp",
  "version": "1"
}

card.verification.otp

New

A one-time password for card verification. Pass it to the cardholder.

  • Only card_id and otp. No status field.
  • otp is text: keep leading zeros. Receiving it does not mean verification is complete.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "otp": "001234"
  },
  "event_at": "2026-10-16T09:42:25.121447Z",
  "event_id": "61f886d4-f365-5204-a15d-965f8562c008",
  "event_type": "card.verification.otp",
  "version": "1"
}

card.activation.code

New

The activation code for a physical card request.

  • Uses card_request_id, not card_id.
  • No status field. It does not mean the card request is complete.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "activation_code": "001234",
    "card_request_id": "6df4b096-a437-4b52-9f1d-52ab15ee5193"
  },
  "event_at": "2026-10-16T09:49:25.121447Z",
  "event_id": "f111c0ce-84fc-50c6-a562-f58a42498574",
  "event_type": "card.activation.code",
  "version": "1"
}

card.activation.status

New

The provider's card activation result. Activated = SUCCESS; any other value = FAILED.

  • status: SUCCESS or FAILED. activation_status keeps the provider value.
  • On success, card.request.result is also sent for the card request.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "activation_status": "Activated",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "failure_reason": null,
    "status": "SUCCESS"
  },
  "event_at": "2026-10-16T09:56:25.121447Z",
  "event_id": "19aecd5c-3a6b-5141-aa34-81f73560dfe9",
  "event_type": "card.activation.status",
  "version": "1"
}

Fee

card.fee

A fee is charged to the card.

  • status is always APPROVED.
  • Only amount and currency; no billing or fee fields.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "1.00",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T09:03:25.121447Z",
  "event_id": "3d611387-b4bc-5483-8e93-dab8d07f1b29",
  "event_type": "card.fee",
  "version": "1"
}

Transactions

card.transaction.authorization

A cardholder purchase is approved. This is the standard event for everyday card spending.

  • status: APPROVED or DECLINED. Approval does not mean settlement is complete.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "1258.00",
    "billing_amount": "38.17",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "THB",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T09:10:25.121447Z",
  "event_id": "fc8110f1-e91d-5854-8a75-ba0ea4e83d79",
  "event_type": "card.transaction.authorization",
  "version": "1"
}

card.transaction.refund

New

A merchant refund is credited back to the card.

  • status: always APPROVED (declined refunds are not sent).
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "25.00",
    "billing_amount": "25.00",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T09:17:25.121447Z",
  "event_id": "fe4ca725-8d96-5116-a957-8479da42e991",
  "event_type": "card.transaction.refund",
  "version": "1"
}

card.transaction.reversal

New

An authorization is reversed (for example, cancelled by the merchant) and the funds go back to the card.

  • status: always APPROVED (declined reversals are not sent).
  • Different from card.transaction.settlement.reversal.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "25.00",
    "billing_amount": "25.00",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T10:24:25.121447Z",
  "event_id": "eb649dee-2ee3-5b41-94bf-a109a49370aa",
  "event_type": "card.transaction.reversal",
  "version": "1"
}

card.transaction.settlement.credit

A transaction settles for less than the authorized amount. The difference is credited back to the cardholder.

  • status: APPROVED or DECLINED.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "1258.00",
    "billing_amount": "38.17",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "THB",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T10:31:25.121447Z",
  "event_id": "309db7ed-ecb3-5d99-9caa-2527c45f73fc",
  "event_type": "card.transaction.settlement.credit",
  "version": "1"
}

card.transaction.settlement.debit

A transaction settles for more than the authorized amount. The difference is debited from the cardholder.

  • status: APPROVED or DECLINED.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "3.00",
    "billing_amount": "3.00",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T10:38:25.121447Z",
  "event_id": "e92bc594-529f-5de6-807d-1389695cc1e9",
  "event_type": "card.transaction.settlement.debit",
  "version": "1"
}

card.transaction.settlement.reversal

A settlement is reversed due to an error. The funds go back to the cardholder.

  • status: APPROVED or DECLINED.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "25.00",
    "billing_amount": "25.00",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T10:45:25.121447Z",
  "event_id": "b698517f-04e3-58b0-bcc3-bd172823930d",
  "event_type": "card.transaction.settlement.reversal",
  "version": "1"
}

card.transaction.fund.collection

An external source adds funds to the cardholder's card account, as reported by the card network (Visa, Mastercard) and relayed through UC-Pay. Not triggered by a cardholder card recharge or a top-up of your issuing balance.

  • status: APPROVED or DECLINED.
  • Card top-ups are reported by card.top_up.result.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "100.00",
    "billing_amount": "100.00",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T10:52:25.121447Z",
  "event_id": "508961b8-21b4-55e0-bb81-461dcbd82e59",
  "event_type": "card.transaction.fund.collection",
  "version": "1"
}

card.transaction.fund.transfer

A fund transfer is processed.

  • status: APPROVED or DECLINED.
  • Wallet ↔ card operations are reported by card.top_up.result / card.withdrawal.result.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "50.00",
    "billing_amount": "50.00",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T10:59:25.121447Z",
  "event_id": "c5cae37a-3b1d-564a-b4e9-83a35fc5ebab",
  "event_type": "card.transaction.fund.transfer",
  "version": "1"
}

card.transaction.chargeback.credit

A chargeback credit is applied.

  • status: APPROVED or DECLINED.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "25.00",
    "billing_amount": "25.00",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T11:13:25.121447Z",
  "event_id": "673f7cef-c4c5-5d0d-ac48-c7e75b28f050",
  "event_type": "card.transaction.chargeback.credit",
  "version": "1"
}

card.transaction.chargeback.debit

A chargeback debit is applied.

  • status: APPROVED or DECLINED.
{
  "agent_id": "3a5ea71a-db96-4efd-8223-4713bc9d6ba3",
  "data": {
    "amount": "25.00",
    "billing_amount": "25.00",
    "billing_currency": "USD",
    "card_id": "d5cfc9f4-ee27-4250-8a34-f5e8ea43daea",
    "currency": "USD",
    "fee_amount": "0.00",
    "fee_currency": "",
    "status": "APPROVED"
  },
  "event_at": "2026-10-16T11:20:25.121447Z",
  "event_id": "cd078817-2611-5b41-9611-e02cdb50d6f6",
  "event_type": "card.transaction.chargeback.debit",
  "version": "1"
}
Copyright © 2026