1. 前置必读
ORIXA-API文档
  • 默认模块
    • 前置必读
      • 请求签名算法说明
      • Webhook 签名校验文档
      • 端点响应状态码
      • WebHook通知事件
      • 卡片安全展示(Secure Iframe)
    • 持卡人
      • 修改持卡人
      • 持卡人列表-分页查询
      • 创建持卡人
    • 卡片操作
      • 卡片敏感信息-Iframe版
      • 卡片列表(分页查询)
      • 获取卡产品列表
      • 实体卡绑定
      • 激活实体卡
      • 卡片激活码(回调异常情况下主动获取)
      • 卡片详情
      • 卡片充值
      • 卡片敏感信息(卡片三要素)
      • 设置卡片状态
      • 卡片刷新
      • 设置PIN
      • 卡卡转账
      • 虚拟卡创建
      • 卡Iframe-签发 PAN Token
      • 卡Iframe-获取真实卡片 ID
    • WebHook
      • 获取WebHook信息
      • 设置WebHook
      • 通知记录
    • 模拟测试
      • API请求头模拟
      • 卡片授权交易--仅沙箱环境可用
    • 商户信息
      • 商户可用余额
      • 商户账单
    • 供应链
      • 供应商目录
      • 供应商资质披露
      • 产品类目
      • 产品列表
      • 获取指定产品规格
      • 查询某产品规格库存信息
      • 计算运费
      • 订单记录
      • 取消订单-仅待发货可申请
      • 确认收货
      • 创建订单
      • 获取支持快递列表
    • 全球付
      • 扫码支付
        • 二维码识别
        • 预创建订单
        • 发起支付
        • 订单状态查询
      • 支持国家列表
      • 汇款通道
      • 获取汇款/创建受益人参数说明
      • 创建受益人
      • 受益人列表
      • 获取货币汇率
      • 更新受益人
      • 汇款
      • 汇款订单
    • 钱包服务
      • 支持公链
      • 已创建地址列表
      • 创建地址
  1. 前置必读

WebHook通知事件

代理商 Webhook 通知事件#

本文档说明 ORIXA 向代理商推送的全部 Webhook 事件。所有事件都以 HTTP POST
投递到代理商在「Webhook 设置」中配置的回调地址,报文结构统一。

投递方式#

项目说明
请求方法POST
Content-Typeapplication/json
请求体UTF-8 JSON,不转义中文与斜杠
成功判定必须返回 HTTP 200,其他状态码(含 201、204、302)均视为失败并重试
重试次数最多 7 次
重试间隔指数退避:30s、60s、120s、240s、480s、960s
响应体内容不做校验,建议先落库再返回 200,业务处理放到异步流程,避免超时被重复投递。
连接超时 5 秒,读写超时 10 秒。

请求头#

Header说明
X-Webhook-Signature签名,HMAC-SHA256(请求体原文, webhook_secret) 的十六进制小写
X-Payload-Sha256请求体原文的 SHA-256 摘要,可用于快速比对报文是否完整
webhook_secret 在代理通过API设置webhook地址后在响应体下发。验签务必使用请求体原始字节,
不要先反序列化再重新序列化,否则字段顺序变化会导致签名不一致。
验签示例(PHP):

公共字段#

FieldTypeDescription
event_idstring事件唯一 ID(UUID),幂等键
event_namestring业务域,见下表
event_typestring具体事件类型
source_idstring业务主体 ID(订单号 / 交易号 / 卡片 ID)
versionstring报文版本
dataobject事件明细

业务域与事件索引#

event_name业务域事件类型
ISSUING卡片与卡交易card.*、issuing.*
BANKING国际汇款transfer.payout.*
ORDER商城订单order.*
WALLET链上充值wallet.deposit.*

幂等要求#

同一业务状态可能被多次推送(重试、上游重复通知),请按 event_id 去重:
先用唯一索引落库 event_id,写入成功再处理业务,重复写入直接返回 200。
部分事件还会在一笔业务的不同阶段推送多条(例如链上充值的待确认、已到账),
这些是不同的 event_id,需要按 event_type 与业务状态字段分别处理。

Card Created Event(卡片创建)#

Event Info#

Event Name: ISSUING
Event Types:
card.create.succeeded
card.create.failed
Trigger: Fired when card creation succeeds or fails

Payload Structure#

Top Level#

FieldTypeDescription
event_idstringEvent ID
event_typestringCreation result
source_idstringCard order ID
dataobjectCard object

data Object (Card)#

FieldTypeDescription
card_idstringCard ID
card_binstringBIN
card_schemestringVISA / Mastercard
card_numberstringMasked card number
form_factorstringPHYSICAL / VIRTUAL
mode_typestringMode type
card_product_idstringCard product ID
card_available_balancestringAvailable balance
cardholderobjectCardholder info
spending_limitsarraySpending rules
risk_controlsobjectRisk controls
metadataobjectCustom metadata
card_statusstringCard status(卡片状态,取值为以下之一:ACTIVE, PRE_CANCEL, CANCELLED, FROZEN, BLOCKED)

cardholder Object#

FieldTypeDescription
cardholder_idstringCardholder ID
emailstringEmail
first_namestringFirst name
last_namestringLast name
create_timestringCreated time
cardholder_statusstringStatus
plete_timestring事件完成时间,ISO8601 格式

示例#

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.create.succeeded",
  "event_id": "c6dca5c7-b64f-4c49-97dd-074fc66a5fba",
  "source_id": "ed977d6b-d86a-4cda-9e54-92cf0ce6228a",
  "data": {
    "card_available_balance": "1000",
    "card_bin": "40963608",
    "card_id": "f5d1e60a-6852-4fea-bb09-1d5bdab657a0",
    "card_number": "40963608****8664",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_scheme": "VISA",
    "card_status": "ACTIVE",
    "cardholder": {
      "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
      "cardholder_status": "SUCCESS",
      "create_time": "2026-04-10T18:03:47+08:00",
      "email": "quickstart-1775815424@example.com",
      "first_name": "Alex",
      "last_name": "Chen"
    },
    "form_factor": "VIRTUAL",
    "metadata": {},
    "mode_type": "SHARE",
    "risk_control": {
      "enable_3ds": "Y",
      "allow_3ds_transactions": "Y"
    },
    "spending_limits": [
      {
        "amount": "20000",
        "interval": "PER_TRANSACTION"
      }
    ]
  }
}

Card Activation Updated Event(实体卡绑定)#

Event Info#

Event Name: ISSUING
Event Types:
card.activation.status
Trigger: Triggered when the binding of the physical card is completed

data Object#

FieldTypeDescription
card_idstringCard ID
card_numberstringCard Number
activation_statusstringNew card status

示例#

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.activation.status",
  "event_id": "2ad09af2-f6dd-4fbf-bc47-83712aa2670d",
  "source_id": "ba4bdf3e-c2b7-4197-9487-dc269e77b2c0",
  "data": {
    "activation_status": "Activated",
    "card_id": "ba4bdf3e-c2b7-4197-9487-dc269e77b2c0",
    "card_number": "40963608****5859"
  }
}

Card Activation Updated Event(实体卡激活)#

Event Info#

Event Name: ISSUING
Event Types:
card.activation.code
Trigger: Triggered when the binding of the physical card is completed

data Object#

FieldTypeDescription
card_idstringCard ID
card_numberstringCard Number
activation_codestringActivation Code

示例#

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.activation.code",
  "event_id": "78ca1f8a-cf8a-42a4-ae0b-9b2acebe600b",
  "source_id": "ba4bdf3e-c2b7-4197-9487-dc269e77b2c0",
  "data": {
    "activation_code": "57609685",
    "card_id": "ba4bdf3e-c2b7-4197-9487-dc269e77b2c0",
    "card_number": "40963608****5859"
  }
}

Card Status Updated Event(卡状态更新事件)#

Event Info#

Event Name: ISSUING
Event Types:
card.status.update.succeeded
card.status.update.failed
Trigger: Fired when card status update completes or fails

data Object#

FieldTypeDescription
card_idstringCard ID
card_numberstringMasked card number
update_timestringUpdate time
card_statusstringNew card status
update_reasonstringUpdate reason

Card Status Enum#

StatusDescription
ACTIVECard active
PRE_CANCELPre-cancelled
CANCELLEDPermanently cancelled
FROZENTemporarily frozen
BLOCKEDBlocked due to risk

示例#

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.status.update.succeeded",
  "event_id": "87ea563b-659c-469d-9ed9-34131eac2632",
  "source_id": "027fd0b1-5334-4cb3-82c0-d40688142a51",
  "data": {
    "card_id": "6f33bffb-63b3-412e-9fc8-3e4c33f265bf",
    "card_number": "46651711****3173",
    "available_balance": "500",
    "currency": "USD",
    "card_status": "CANCELLED",
    "update_reason": " card test",
    "update_time": "2026-04-08T11:46:09+08:00"
  }
}

Card Recharged Event(卡充值事件)#

Event Info#

Event Name: ISSUING
Event Types:
card.recharge.succeeded
card.recharge.failed
Trigger: Fired when card recharge completes or fails

data Object#

FieldTypeDescription
card_idstringCard ID
amountstringRecharge amount
card_available_balancestringBalance after recharge
card_currencystringCurrency
update_timestringUpdate time
complete_timestringCompletion time
card_statusstringCard status
order_statusstringOrder status

Order Status Enum#

StatusDescription
SUCCESSRecharge succeeded
FAILEDRecharge failed
PENDINGPending
PROCESSINGProcessing

示例#

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.recharge.succeeded",
  "event_id": "dcbdbcb7-71e7-471e-94d6-91b6da45e332",
  "source_id": "c62a3cd2-4e69-43bc-837d-a7a1f09c54f7",
  "data": {
    "amount": "100.02",
    "card_available_balance": "128.52",
    "card_currency": "USD",
    "card_id": "88e8c3a8-1cd1-400e-a58c-d3e8bc9d3e00",
    "card_status": "ACTIVE",
    "complete_time": "2026-04-09T13:34:58.838+08:00",
    "order_status": "SUCCESS",
    "update_time": "2026-04-09T13:34:58.838+08:00"
  }
}

Card Transfer Event(卡卡转账事件)#

Event Info#

Event Name: ISSUING
Event Types:
card.transfer.succeeded
Trigger: Triggered when card transfer is completed

data Object#

FieldTypeDescription
from_card_idstringCard ID
to_card_idstringCard ID
out_amountstringOut amount
in_amountstringIN amount
card_currencystringCurrency
create_timestringCreate time
update_timestringUpdate time
transfer_statusstringOrder status

Order Status Enum#

StatusDescription
SUCCESSRecharge succeeded
FAILEDRecharge failed
PENDINGPending
PROCESSINGProcessing

示例#

{
    "version": "V1.6.0",
    "event_name": "ISSUING",
    "event_type": "card.transfer.succeeded",
    "event_id": "c65008e8-c01a-4612-ba1f-4ebc157b41de",
    "source_id": "81d50602-c480-4dc3-9e3e-c16b6f86a27c",
    "data": {
       "from_card_id":    "09b0fc84-b6e6-4f1a-ac5d-6c306a36728b",
        "to_card_id":      "09b0fc84-b6e6-4f1a-ac5d-6c306a36728b",
        "out_amount":          "200",//转出金额
        "in_amount":          "200",//转入金额
        "card_currency":   "USD",
        "create_time":     "2025-07-17T14:55:39+08:00",
        "complete_time":   "2025-07-17T14:55:39+08:00",
        "transfer_status": "SUCCESS",
    }
}

3DS OTP Event(3D验证事件)#

Event Info#

Event Name: ISSUING
Event Type: card.3ds.otp
Trigger: Fired when a transaction requires 3D Secure verification

data Object#

FieldTypeDescription
reference_codestringOTP reference code
otpstringOne-time password
customer_idstringCustomer ID
card_idstringCard ID
card_numberstringMasked card number
transaction_currencystringCurrency
transaction_amountstringAmount
merchant_namestringMerchant name

示例#

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.3ds.otp",
  "event_id": "26de83a5-cea5-4f84-ab11-48813025e40a",
  "source_id": "12ea604d-5899-43d6-8c2d-618c9ce8eae3",
  "data": {
    "reference_code": "4868798",
    "otp": "12344444",
    "customer_id": "67f006f4-d593-49f4-be0e-f1f894e8933b",
    "card_id": "1d749d10-511e-469f-9a83-0560a602ac37",
    "card_number": "1234********3381",
    "transaction_currency": "USD",
    "transaction_amount": "100",
    "merchant_name": "Example Merchant"
  }
}

Card OTP Event(卡片验证事件)#

Event Info#

Event Name: ISSUING
Event Type: card.verification.otp
Trigger: Fired when a transaction requires email Secure verification

data Object#

FieldTypeDescription
otpstringOne-time password
card_idstringCard ID
card_numberstringMasked card number

示例#

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.verification.otp",
  "event_id": "0f3891bc-5bec-4aea-bd33-ba67997065f0",
  "source_id": "cc56949f-ef3f-4b11-ae88-3af6093fde0f",
  "data": {
    "card_id": "cc56949f-ef3f-4b11-ae88-3af6093fde0f",
    "card_number": "40963609****7723",
    "otp": "111111",
    "wallet_type": "GOOGLE_PAY"
  }
}

Transaction Event(交易事件)#

Event Types#

issuing.transaction.authorization- 交易授权(发卡机构批准了持卡人发起的交易。通常用于普通购物或交易)
issuing.transaction.reversal- 交易冲正(之前的交易被取消或撤销——例如由于欺诈、操作错误或交易取消等原因。资金将退回持卡人账户)
issuing.transaction.refund- 交易退款(持卡人退回了购买的商品或服务,商家将款项退还到了持卡人的账户)
issuing.transaction.settlement.credit- 结算贷记(结算金额低于原交易金额,因此差额将记入持卡人账户)
issuing.transaction.settlement.debit - 结算借记(结算金额高于原始交易金额,因此差额将从持卡人账户中扣除)
issuing.transaction.settlement.reversal- 结算冲正(之前一笔结算交易因出错而被撤销,资金已退还给持卡人)
issuing.transaction.fund.collection - 资金收集(持卡人卡账户收到来自外部来源的款项通知,该款项由卡组织(例如 Visa/Mastercard)报告给 ORIXA 并转发给您。此通知不同于持卡人发起的转账CARD RECHARGE以及为您的发卡行余额充值)
issuing.transaction.validation- 交易验证(验证卡片的有效性,确认持卡人信息正确且卡片已激活。通常与授权流程同时执行)
issuing.transaction.atm.deposit- ATM存款
issuing.transaction.authorization- ATM取款(merchant_data.category_code区分)
issuing.transaction.chargeback.credit- 拒付贷记(已处理退款)
issuing.transaction.chargeback.debit- 拒付借记(已处理一笔拒付借记)

data Object#

FieldTypeDescription
card_idstringCard ID
card_numberstringMasked card number
cardholder_idstringCardholder ID
transaction_idstringTransaction ID
short_transaction_idstringShort ID
original_transaction_idstringOriginal transaction
card_available_balancestringBalance after
transaction_typestringTransaction type
transaction_feestringFee
transaction_fee_currencystringFee currency
fee_pass_throughstringY / N
authorization_codestringAuth code
billing_amountstringBilling amount
billing_currencystringBilling currency
transaction_amountstringAmount
transaction_currencystringCurrency
transaction_timestringTransaction time
posted_timestringPosted time
merchant_dataarrayMerchant info
wallet_typestringWallet type
descriptionstringRemark or decline reason
transaction_statusstringAPPROVED / DECLINED

merchant_data#

FieldTypeDescription
category_codestringMCC/6011 [FINANCIAL INSTITUTIONS - AUTOMATED CASH DISBURSEMENTS]
citystringCity
countrystringCountry
namestringMerchant name

示例#

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "issuing.transaction.authorization",
  "event_id": "234fca01-1ace-4d34-baf5-29b10e9d11c0",
  "source_id": "1a53aebf-900c-4e25-9852-b98f4338d94c",
  "data": {
    "authorization_code": "W6MJU9",
    "billing_amount": "11.5",
    "billing_currency": "USD",
    "card_available_balance": "988.5",
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "card_number": "40963608****1764",
    "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
    "description": "",
    "fee_pass_through": "Y",
    "merchant_data": [
      {
        "category_code": "5734",
        "city": "",
        "country": "",
        "name": "Test Merchant"
      }
    ],
    "original_transaction_id": "",
    "posted_time": "2026-04-12T15:27:39.563+08:00",
    "short_transaction_id": "T260412-2AHV51KO5U68",
    "transaction_amount": "10",
    "transaction_currency": "USD",
    "transaction_fee": "1.5",
    "transaction_fee_currency": "USD",
    "transaction_id": "1a53aebf-900c-4e25-9852-b98f4338d94c",
    "transaction_status": "APPROVED",
    "transaction_time": "2026-04-12T15:27:39.48+08:00",
    "transaction_type": "AUTHORIZATION",
    "wallet_type": ""
  }
}

Transfer Payout(全球付交易)#

Event Types#

transfer.payout.succeeded - 打款成功
transfer.payout.failed - 打款失败

Body Object#

FieldTypeDescription
event_idstringA unique ID for the event.
event_namestringEvent name,如 BANKING.
event_typestringEvent type.
source_idstring第三方转账订单号(Transfer order ID).
dataobject转账明细,见下表.

data 对象字段#

FieldTypeDescription
transfer_order_nostring第三方转账订单号
transfer_statusstringSUCCESS / FAIL
transfer_amountstring转账金额(目标币种)
transfer_currencystring目标币种,如 SGD、THB
channel_fee_usdstring通道费(USD)
service_fee_usdstring手续费(USD)
fail_reasonstring失败原因,成功时为空字符串
create_timeint创建时间戳
complete_timeint完成时间戳

成功回调响应示例#

{
  "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"
  }
}

Consumption Pay(扫码支付)#

Event Types#

consumption.pay.success - 支付成功,资金已付出
consumption.pay.failed - 支付失败,已扣款项全额退回余额
只有终态会推送。中间态(已受理、处理中)不发送回调,
如需感知可调用 agent/v1/qrcode/status(同一订单号限 1 次/秒)。

Body Object#

FieldTypeDescription
event_idstring事件唯一 ID,可用于幂等去重.
event_namestring固定为 CONSUMPTION_PAY.
event_typestringEvent type.
source_idstring代理商侧订单号(ACP 开头),与 data.order_sn 相同.
dataobject支付明细,见下表.

data 对象字段#

FieldTypeDescription
order_snstring代理商侧订单号(ACP 开头)
statusstringSUCCESS / FAIL
currencystring收款币种,如 VND
currency_amountstring付款金额(原币种)
amount_usdstring实扣 USD 金额(含汇率滑点)
service_fee_usdstring服务费(USD)
channel_fee_usdstring通道费(USD)
total_usdstring应扣总额(USD),即余额实际扣除金额
exchange_ratestring结算汇率
fail_reasonstring失败原因,成功时为空字符串
order_timeint订单时间戳

成功回调响应示例#

{
  "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
  }
}
说明:fail_reason 中若包含 error: 或内部路径前缀,对接方可只解析并展示 error: 后的可读文案。

Order Webhook(订单事件)#

用于供应商侧订单状态变更后,向下单代理商推送订单事件。当前已支持以下 3 类场景:
order.delivery.succeeded - 供应商已发货
order.cancel.agreed - 供应商已同意取消
order.cancel.refused - 供应商已拒绝取消

Body Object#

FieldTypeDescription
event_idstring事件唯一 ID(UUID)
event_namestring固定为 ORDER
event_typestring事件类型
source_idstring订单 ID
dataobject订单事件明细,见下表

data 对象字段#

FieldTypeDescription
order_nostring订单号
express_namestring快递公司编码,未发货时为空
express_nostring快递单号,未发货时为空
pay_amountstring订单支付金额
currencystring结算币种,当前固定为 USD
remarkstring订单备注,拒绝取消时会附带拒绝备注
statusstring业务处理结果,如 SUCCESS、REFUSED
refund_amountstring退款金额,仅 order.cancel.agreed 时返回
refuse_reasonstring拒绝原因,仅 order.cancel.refused 时返回
create_timestring订单创建时间,ISO8601 格式
complete_timestring事件完成时间,ISO8601 格式

发货成功示例#

{
  "event_id": "a19a985b-90d3-44f7-827c-bd4301d62192",
  "event_name": "ORDER",
  "event_type": "order.delivery.succeeded",
  "source_id": "202603071234567890",
  "data": {
    "order_no": "202603071234567890",
    "express_name": "DHL",
    "express_no": "DHL9988776655",
    "pay_amount": "15.80",
    "currency": "USD",
    "remark": "",
    "status": "SUCCESS",
    "create_time": "2026-03-07T05:21:28+00:00",
    "complete_time": "2026-03-07T05:21:40+00:00"
  }
}

同意取消示例#

{
  "event_id": "c6b43cb7-3f7a-4d89-8fb3-8fa1e1a4d00a",
  "event_name": "ORDER",
  "event_type": "order.cancel.agreed",
  "source_id": "202603071234567890",
  "data": {
    "order_no": "202603071234567890",
    "express_name": "",
    "express_no": "",
    "pay_amount": "15.80",
    "currency": "USD",
    "remark": "",
    "status": "SUCCESS",
    "refund_amount": "15.80",
    "create_time": "2026-03-07T05:21:28+00:00",
    "complete_time": "2026-03-07T05:30:10+00:00",
  }
}

拒绝取消示例#

{
  "event_id": "e8e4fd7c-6f64-46a5-a2c4-c848f8f6f0c2",
  "event_name": "ORDER",
  "event_type": "order.cancel.refused",
  "source_id": "202603071234567890",
  "data": {
    "order_no": "202603071234567890",
    "express_name": "",
    "express_no": "",
    "pay_amount": "15.80",
    "currency": "USD",
    "remark": "【取消拒绝】该商品已进入配货流程,暂不支持取消",
    "status": "REFUSED",
    "refuse_reason": "该商品已进入配货流程,暂不支持取消",
    "create_time": "2026-03-07T05:21:28+00:00",
    "complete_time": "2026-03-07T05:28:02+00:00"
  }
}

说明#

event_name 固定为 ORDER,便于代理商侧按业务域分类处理。
拒绝取消时,remark 会包含订单备注中的拒绝内容,refuse_reason 为单独拆出的拒绝原因,建议优先展示该字段。

Wallet Deposit(链上充值)#

代理商通过 POST /agent/v1/wallet/address/create 创建充值地址后,该地址上的链上入账
会以本组事件推送。ORIXA 侧只做链上状态的通知转发,不为代理商记账,到账后的
用户入账、风控与对账由代理商自行完成。

Event Types#

wallet.deposit.pending - 充值待确认(已发现链上交易,确认数未达标)
wallet.deposit.succeeded - 充值已到账
wallet.deposit.failed - 充值失败(风控拒绝或链上失败)
一笔充值通常推送 2~3 次:待筛查 → 确认中(两者都是 wallet.deposit.pending)→ 已到账。
请只把 wallet.deposit.succeeded 作为入账依据,pending 事件仅用于展示进度。

Body Object#

FieldTypeDescription
event_idstring事件唯一 ID(UUID)
event_namestring固定为 WALLET
event_typestring事件类型
source_idstring充值流水号,同 data.deposit_id
dataobject充值明细,见下表

data 对象字段#

FieldTypeDescription
deposit_idstring充值流水号;同一笔充值的多次推送该值一致,用于合并进度
ref_idstring创建地址时传入的业务标识,未传则为空字符串
chain_namestring公链名称,如 BEP20
chain_symbolstring公链标识,与创建地址接口的 chain_symbol 一致,如 BSC_BNB
coin_symbolstring币种,如 USDT
amountstring充值数量,字符串传递以免精度丢失
to_addressstring收款地址(代理商创建的地址)
from_addressstring付款地址,取链上第一个输入地址;无法解析时为空字符串
memostring地址 memo/tag,无则为空字符串
tx_hashstring链上交易哈希
block_numberstring区块高度,未上链时为空字符串
block_timestring区块时间,ISO8601;未上链时为空字符串
confirmed_numint当前确认数
confirming_thresholdint到账所需确认数
deposit_statusstring充值状态,见下表
fail_reasonstring失败原因,仅失败事件返回,其余为空字符串
create_timestring交易发现时间,ISO8601
complete_timestring完成时间,ISO8601;未到终态时为空字符串

Deposit Status Enum#

Status对应 event_typeDescription
PENDINGwallet.deposit.pending已发现交易,等待链上确认
CONFIRMINGwallet.deposit.pending链上确认中,可用 confirmed_num / confirming_threshold 展示进度
SUCCESSwallet.deposit.succeeded已到账
FAILEDwallet.deposit.failed充值失败

待确认回调示例#

{
  "version": "V1.6.0",
  "event_name": "WALLET",
  "event_type": "wallet.deposit.pending",
  "event_id": "ca21feaf-390e-4da6-a46b-440ebd955ddc",
  "source_id": "947cc7c3-6cac-4d85-8898-40347193f54b",
  "data": {
    "deposit_id": "947cc7c3-6cac-4d85-8898-40347193f54b",
    "ref_id": "agency-user-10086",
    "chain_name": "BEP20",
    "chain_symbol": "BSC_BNB",
    "coin_symbol": "USDT",
    "amount": "0.05",
    "to_address": "0x4a6c0eaf83970b9e14fa9d16d8b6966f5f52ad85",
    "from_address": "0xf117ba7f334cd7aafff1f89150d7ee999d852031",
    "memo": "",
    "tx_hash": "0x06928b774cc8fcaaaa974b3a389e6efa536a3e4a2afb2371f18216f526ba2572",
    "block_number": "119462185",
    "block_time": "2026-09-02T11:19:47+08:00",
    "confirmed_num": 1,
    "confirming_threshold": 15,
    "deposit_status": "CONFIRMING",
    "fail_reason": "",
    "create_time": "2026-09-02T11:19:50+08:00",
    "complete_time": ""
  }
}

到账回调示例#

{
  "version": "V1.6.0",
  "event_name": "WALLET",
  "event_type": "wallet.deposit.succeeded",
  "event_id": "7b4c1c2e-2f61-4f0a-9d2c-7f55c0f3a911",
  "source_id": "947cc7c3-6cac-4d85-8898-40347193f54b",
  "data": {
    "deposit_id": "947cc7c3-6cac-4d85-8898-40347193f54b",
    "ref_id": "agency-user-10086",
    "chain_name": "BEP20",
    "chain_symbol": "BSC_BNB",
    "coin_symbol": "USDT",
    "amount": "0.05",
    "to_address": "0x4a6c0eaf83970b9e14fa9d16d8b6966f5f52ad85",
    "from_address": "0xf117ba7f334cd7aafff1f89150d7ee999d852031",
    "memo": "",
    "tx_hash": "0x06928b774cc8fcaaaa974b3a389e6efa536a3e4a2afb2371f18216f526ba2572",
    "block_number": "119462185",
    "block_time": "2026-09-02T11:19:47+08:00",
    "confirmed_num": 15,
    "confirming_threshold": 15,
    "deposit_status": "SUCCESS",
    "fail_reason": "",
    "create_time": "2026-09-02T11:19:50+08:00",
    "complete_time": "2026-09-02T11:24:08+08:00"
  }
}

失败回调示例#

{
  "version": "V1.6.0",
  "event_name": "WALLET",
  "event_type": "wallet.deposit.failed",
  "event_id": "2c9f5a70-8d33-4a1d-9b7e-6a0d41f8e552",
  "source_id": "5f2b8d41-9c07-4b6e-bb31-2e9a7c4d1a88",
  "data": {
    "deposit_id": "5f2b8d41-9c07-4b6e-bb31-2e9a7c4d1a88",
    "ref_id": "",
    "chain_name": "TRC20",
    "chain_symbol": "TRON",
    "coin_symbol": "USDT",
    "amount": "120",
    "to_address": "TSUtDgGWhXyLNWfdirJHrhnf74KXon95yc",
    "from_address": "TKrHtF8VQZ4pDyN3nY9m1LgWqB6sXcE2Ja",
    "memo": "",
    "tx_hash": "",
    "block_number": "",
    "block_time": "",
    "confirmed_num": 0,
    "confirming_threshold": 19,
    "deposit_status": "FAILED",
    "fail_reason": "Deposit failed",
    "create_time": "2026-09-02T14:02:11+08:00",
    "complete_time": "2026-09-02T14:03:40+08:00"
  }
}

说明#

amount 一律用字符串传递,请用高精度类型解析,不要转成浮点数。
同一 deposit_id 会推送多条事件,请以 deposit_id 聚合、以 event_id 幂等。
只有 to_address 能匹配到代理商名下的充值地址时才会推送;地址被停用后仍会推送,
因为资金已经到链,需要代理商知悉并处理。
上一页
端点响应状态码
下一页
卡片安全展示(Secure Iframe)
Built with