生产环境开放「全球付-扫码支付」功能模块，目前仅支持生产调用
WebHook通知事件
Issuing Webhook Events
Common Fields
| Field | Type | Description |
|---|---|---|
| event_id | string | Unique event identifier |
| event_name | string | Event category: ISSUING / BANKING / CONSUMPTION_PAY |
| event_type | string | Specific event type |
| source_id | string | Source ID (order ID / transaction ID) |
| version | string | API version |
| data | object | Event payload |
Event List
Card Created Event(卡片创建)
Event Info
card.create.succeededcard.create.failedPayload Structure
Top Level
| Field | Type | Description |
|---|---|---|
| event_id | string | Event ID |
| event_type | string | Creation result |
| source_id | string | Card order ID |
| data | object | Card object |
data Object (Card)
| Field | Type | Description |
|---|---|---|
| card_id | string | Card ID |
| card_bin | string | BIN |
| card_scheme | string | VISA / Mastercard |
| card_number | string | Masked card number |
| form_factor | string | PHYSICAL / VIRTUAL |
| mode_type | string | Mode type |
| card_product_id | string | Card product ID |
| card_available_balance | string | Available balance |
| cardholder | object | Cardholder info |
| spending_limits | array | Spending rules |
| risk_controls | object | Risk controls |
| metadata | object | Custom metadata |
| card_status | string | Card status(卡片状态，取值为以下之一：ACTIVE, PRE_CANCEL, CANCELLED, FROZEN, BLOCKED) |
cardholder Object
| Field | Type | Description |
|---|---|---|
| cardholder_id | string | Cardholder ID |
| string | ||
| first_name | string | First name |
| last_name | string | Last name |
| create_time | string | Created time |
| cardholder_status | string | Status |
Card Activation Updated Event(实 体卡绑定)
Event Info
card.activation.statusdata Object
| Field | Type | Description |
|---|---|---|
| card_id | string | Card ID |
| card_number | string | Card Number |
| activation_status | string | New card status |
Card Activation Updated Event(实体卡激活)
Event Info
card.activation.codedata Object
| Field | Type | Description |
|---|---|---|
| card_id | string | Card ID |
| card_number | string | Card Number |
| activation_code | string | Activation Code |
Card Status Updated Event(卡状态更新事件)
Event Info
card.status.update.succeededcard.status.update.faileddata Object
| Field | Type | Description |
|---|---|---|
| card_id | string | Card ID |
| card_number | string | Masked card number |
| update_time | string | Update time |
| card_status | string | New card status |
| update_reason | string | Update reason |
Card Status Enum
| Status | Description |
|---|---|
| ACTIVE | Card active |
| PRE_CANCEL | Pre-cancelled |
| CANCELLED | Permanently cancelled |
| FROZEN | Temporarily frozen |
| BLOCKED | Blocked due to risk |
Card Recharged Event(卡充值事件)
Event Info
card.recharge.succeededcard.recharge.faileddata Object
| Field | Type | Description |
|---|---|---|
| card_id | string | Card ID |
| amount | string | Recharge amount |
| card_available_balance | string | Balance after recharge |
| card_currency | string | Currency |
| update_time | string | Update time |
| complete_time | string | Completion time |
| card_status | string | Card status |
| order_status | string | Order status |
Order Status Enum
| Status | Description |
|---|---|
| SUCCESS | Recharge succeeded |
| FAILED | Recharge failed |
| PENDING | Pending |
| PROCESSING | Processing |
3DS OTP Event(3D验证事件)
Event Info
card.3ds.otpdata Object
| Field | Type | Description |
|---|---|---|
| reference_code | string | OTP reference code |
| otp | string | One-time password |
| customer_id | string | Customer ID |
| card_id | string | Card ID |
| card_number | string | Masked card number |
| transaction_currency | string | Currency |
| transaction_amount | string | Amount |
| merchant_name | string | Merchant name |
Card OTP Event(卡片验证事件)
Event Info
card.verification.otpdata Object
| Field | Type | Description |
|---|---|---|
| otp | string | One-time password |
| card_id | string | Card ID |
| card_number | string | Masked card number |
Transaction Event(交易事件)
Event Types
data Object
| Field | Type | Description |
|---|---|---|
| card_id | string | Card ID |
| card_number | string | Masked card number |
| cardholder_id | string | Cardholder ID |
| transaction_id | string | Transaction ID |
| short_transaction_id | string | Short ID |
| original_transaction_id | string | Original transaction |
| card_available_balance | string | Balance after |
| transaction_type | string | Transaction type |
| transaction_fee | string | Fee |
| transaction_fee_currency | string | Fee currency |
| fee_pass_through | string | Y / N |
| authorization_code | string | Auth code |
| billing_amount | string | Billing amount |
| billing_currency | string | Billing currency |
| transaction_amount | string | Amount |
| transaction_currency | string | Currency |
| transaction_time | string | Transaction time |
| posted_time | string | Posted time |
| merchant_data | array | Merchant info |
| wallet_type | string | Wallet type |
| description | string | Remark or decline reason |
| transaction_status | string | APPROVED / DECLINED |
merchant_data
| Field | Type | Description |
|---|---|---|
| category_code | string | MCC/6011 [FINANCIAL INSTITUTIONS - AUTOMATED CASH DISBURSEMENTS] |
| city | string | City |
| country | string | Country |
| name | string | Merchant name |
Transfer Payout(全球付交易)
Event Types
transfer.payout.succeeded - 打款成功transfer.payout.failed - 打款失败Body Object
| Field | Type | Description |
|---|---|---|
| event_id | string | A unique ID for the event. |
| event_name | string | Event name，如 BANKING. |
| event_type | string | Event type. |
| source_id | string | 第三方转账订单号（Transfer order ID）. |
| data | object | 转账明细，见下表. |
data 对象字段
| Field | Type | Description |
|---|---|---|
| transfer_order_no | string | 第三方转账订单号 |
| transfer_status | string | SUCCESS / FAIL |
| transfer_amount | string | 转账金额（目标币种） |
| transfer_currency | string | 目标币种，如 SGD、THB |
| channel_fee_usd | string | 通道费（USD） |
| service_fee_usd | string | 手续费（USD） |
| fail_reason | string | 失败原因，成功时为空字符串 |
| create_time | int | 创建时间戳 |
| complete_time | int | 完成时间戳 |
成功回调响应示例
{
"event_id": "8741046a-6eba-4471-bfeb-acb2844d4f0a",
"event_name": "BANKING",
"event_type": "transfer.payout.succeeded",
"source_id": "ARM-69aa3d1ff135b",
"data": {
"channel_fee_usd": "46.5",
"complete_time": 1772692731,
"create_time": 1772692098,
"fail_reason": "",
"service_fee_usd": "58.94",
"transfer_amount": "150",
"transfer_currency": "SGD",
"transfer_order_no": "ARM-69aa3d1ff135b",
"transfer_status": "SUCCESS"
}
}失败回调响应示例
{
"event_id": "fc9bd1b6-4a00-4112-9340-c356e1b4f314",
"event_name": "BANKING",
"event_type": "transfer.payout.failed",
"source_id": "ARM-69aa3d1ff135b",
"data": {
"channel_fee_usd": 0,
"complete_time": 1772546982,
"create_time": 1772462475,
"fail_reason": "Abnormal payment information",
"service_fee_usd": 0,
"transfer_amount": "3500",
"transfer_currency": "THB",
"transfer_order_no": "ARM-69aa3d1ff135b",
"transfer_status": "FAIL"
}
}说明： fail_reason中若包含error:或内部路径前缀，对接方可只解析并展示error:后的可读文案。
Consumption Pay(扫码支付)
Event Types
consumption.pay.success - 支付成功，资金已付出consumption.pay.failed - 支付失败，已扣款项全额退回余额如需感知可调用
agent/v1/qrcode/status（同一订单号限 1 次/秒）。Body Object
| Field | Type | Description |
|---|---|---|
| event_id | string | 事件唯一 ID，可用于幂等去重. |
| event_name | string | 固定为 CONSUMPTION_PAY. |
| event_type | string | Event type. |
| source_id | string | 代理商侧订单号（ACP 开头），与 data.order_sn 相同. |
| data | object | 支付明细，见下表. |
data 对象字段
| Field | Type | Description |
|---|---|---|
| order_sn | string | 代理商侧订单号（ACP 开头） |
| status | string | SUCCESS / FAIL |
| currency | string | 收款币种，如 VND |
| currency_amount | string | 付款金额（原币种） |
| amount_usd | string | 实扣 USD 金额（含汇率滑点） |
| service_fee_usd | string | 服务费（USD） |
| channel_fee_usd | string | 通道费（USD） |
| total_usd | string | 应扣总额（USD），即余额实际扣除金额 |
| exchange_rate | string | 结算汇率 |
| fail_reason | string | 失败原因，成功时为空字符串 |
| order_time | int | 订单时间戳 |
成功回调响应示例
{
"event_id": "0e9bd706-220d-49f7-a150-225fd1667326",
"event_name": "CONSUMPTION_PAY",
"event_type": "consumption.pay.success",
"source_id": "ACP2026082616304212345",
"data": {
"order_sn": "ACP2026082616304212345",
"status": "SUCCESS",
"currency": "VND",
"currency_amount": "100000.0000",
"amount_usd": "4.0400",
"service_fee_usd": "0.0606",
"channel_fee_usd": "0.1000",
"total_usd": "4.2006",
"exchange_rate": "0.00004040",
"fail_reason": "",
"order_time": 1787556758
}
}失败回调响应示例
{
"event_id": "fc9bd1b6-4a00-4112-9340-c356e1b4f314",
"event_name": "CONSUMPTION_PAY",
"event_type": "consumption.pay.failed",
"source_id": "ACP2026082616304212345",
"data": {
"order_sn": "ACP2026082616304212345",
"status": "FAIL",
"currency": "VND",
"currency_amount": "100000.0000",
"amount_usd": "4.0400",
"service_fee_usd": "0.0606",
"channel_fee_usd": "0.1000",
"total_usd": "4.2006",
"exchange_rate": "0.00004040",
"fail_reason": "Abnormal payment information",
"order_time": 1787556758
}
}收到失败事件即代表 total_usd已全额退回代理商余额，无需另行申请退款。