Event Types
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_type | Group | Description |
|---|---|---|
card.request.result New | Operation results | A card request has finished: the card was issued (SUCCESS) or the request was declined / issuance failed (FAILED). |
card.top_up.result New | Operation results | A card top-up (recharge) has finished, funded either externally or from the internal wallet. |
card.withdrawal.result New | Operation results | A card withdrawal has finished. |
card.status.update.result New | Operation results | A requested card status change (block, unblock, cancel) has succeeded or failed at the provider. |
card.update.result New | Operation results | A change to the card's per-transaction limit has succeeded or failed at the provider. |
card.3ds.otp New | OTP and activation | A one-time password for 3D Secure online payment confirmation. |
card.verification.otp New | OTP and activation | A one-time password for card verification. |
card.activation.code New | OTP and activation | The activation code for a physical card request. |
card.activation.status New | OTP and activation | The provider's card activation result. |
card.fee | Fee | A fee is charged to the card. |
card.transaction.authorization | Transactions | A cardholder purchase is approved. |
card.transaction.refund New | Transactions | A merchant refund is credited back to the card. |
card.transaction.reversal New | Transactions | An authorization is reversed (for example, cancelled by the merchant) and the funds go back to the card. |
card.transaction.settlement.credit | Transactions | A transaction settles for less than the authorized amount. |
card.transaction.settlement.debit | Transactions | A transaction settles for more than the authorized amount. |
card.transaction.settlement.reversal | Transactions | A settlement is reversed due to an error. |
card.transaction.fund.collection | Transactions | An 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.transfer | Transactions | A fund transfer is processed. |
card.transaction.chargeback.credit | Transactions | A chargeback credit is applied. |
card.transaction.chargeback.debit | Transactions | A chargeback debit is applied. |
Operation results
card.request.result
NewA 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:SUCCESSorFAILED.card_idcan benullwhen 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
NewA 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:SUCCESSorFAILED.card_wallet_transfer_idis 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
NewA 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:SUCCESSorFAILED.- External withdrawal: includes
card_withdrawal_id. Internal wallet: includescard_wallet_transfer_idinstead. SUCCESSfor an external withdrawal means the withdrawal was approved; it is not a blockchain payout confirmation.- On
FAILED,received_amountis 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
NewA requested card status change (block, unblock, cancel) has succeeded or failed at the provider.
status:SUCCESSorFAILED.card_statusis always the card's actual status after processing. Example: a failed block returnsFAILEDwithACTIVE.
{
"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
NewA change to the card's per-transaction limit has succeeded or failed at the provider.
status:SUCCESSorFAILED.- On
FAILED,limit_per_transactionis 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
NewA one-time password for 3D Secure online payment confirmation. Pass it to the cardholder.
- No
statusfield. It does not confirm a payment outcome. otpis text: keep leading zeros.reference_code,amount,currencyandmerchant_nameare 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
NewA one-time password for card verification. Pass it to the cardholder.
- Only
card_idandotp. Nostatusfield. otpis 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
NewThe activation code for a physical card request.
- Uses
card_request_id, notcard_id. - No
statusfield. 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
NewThe provider's card activation result. Activated = SUCCESS; any other value = FAILED.
status:SUCCESSorFAILED.activation_statuskeeps the provider value.- On success,
card.request.resultis 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.
statusis alwaysAPPROVED.- Only
amountandcurrency; 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:APPROVEDorDECLINED. 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
NewA merchant refund is credited back to the card.
status: alwaysAPPROVED(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
NewAn authorization is reversed (for example, cancelled by the merchant) and the funds go back to the card.
status: alwaysAPPROVED(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:APPROVEDorDECLINED.
{
"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:APPROVEDorDECLINED.
{
"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:APPROVEDorDECLINED.
{
"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:APPROVEDorDECLINED.- 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:APPROVEDorDECLINED.- 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:APPROVEDorDECLINED.
{
"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:APPROVEDorDECLINED.
{
"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"
}