代付订单 · 墨西哥

请求

代付 API 用于向受益人发起代付交易。本页为 墨西哥（国家码 mx）的代付说明。代付走 SPEI 时，bankCode 为参与机构 数字编码，bankCard 常为收款人 CLABE（18 位） 等账户标识；完整机构码与名称见地区支付说明 — 墨西哥。

请求路径

域名：推荐使用统一域名 openapi.toppayment.com（路径不变）；原国别域名（如 global-mx-openapi.toppayment.com）仍可用。

环境	地址
沙箱	`https://openapi.toppayment.com/sandbox/mx/disbursement/cash`
生产	`https://openapi.toppayment.com/mx/disbursement/cash`

代付 bankCode / bankName（SPEI 机构） 见地区支付说明 — 墨西哥。

请求头

字段	必填	类型	描述
Content-Type	M	String	HTTP内容类型规范固定值：application/json 正确解析请求所必需

请求体

字段	必填	类型	描述
mchNo	M	String(32)	商户编号平台分配的唯一商户标识符用于商户认证和交易路由
orderNum	M	String(50)	商户订单号唯一交易标识符格式：字母数字字符串用于交易跟踪和参考
amount	M	Number(32,8)	交易金额格式：数值类型示例：100.50 墨西哥地区：须为正数，整数或最多两位小数，不允许全为 0，不允许三位及以上小数。
bankCode	M	String(32)	SPEI 收款机构数字编码（墨西哥）见地区支付说明 — 墨西哥中「SPEI 参与机构」
bankCard	M	String(50)	收款账户标识常见为 CLABE（18 位数字）等，格式以实际网关与收款行要求为准
accountName	M	String(50)	账户名收款人账户名称格式：UTF-8编码字符串
description	O	String(255)	描述交易目的或描述格式：UTF-8编码字符串
feeType	M	Number(0或1)	手续费类型 0 : 代付金额内扣除(实际到账金额=下单金额-手续费) 1 : 手续费另计(实际到账金额=下单金额)
downNotifyUrl	M	String(164)	异步通知地址交易状态更新的Webhook通知URL 格式：有效的HTTP/HTTPS URL 用于实时交易状态通知
timestamp	M	String(13位数字)	时间戳请求时间戳示例：1749451858772
sign	M	String	签名请求认证的数字签名参见签名生成

请求体示例 – 付款请求（示例为 BBVA MEXICO `40012` + CLABE 占位；以实际网关为准）：

Content-type: application/json

{
    "mchNo": "{{mchNo}}",
    "orderNum": "MXPAYOUT1234561",
    "amount": 100.50,
    "bankCode": "40012",
    "bankCard": "012345678901234567",
    "accountName": "Luis Garcia",
    "description": "test",
    "feeType": 1,
    "downNotifyUrl": "https://example.com/notify",
    "timestamp": "1749451858772",
    "sign": "按签名规则生成后替换"
}

响应

HTTP响应

字段	必填	类型	描述
Content-Type	M	String	HTTP响应内容类型规范固定值：application/json 指示JSON响应格式

响应字段

字段	必填	类型	描述
success	M	Boolean	请求是否成功 true：成功，false：失败
code	M	String	响应状态码 9999：成功其他：请根据订单状态码判断，不能直接处理订单失败,以免造成资金损失
msg	O	String	响应消息可读的响应状态描述包含订单详细信息
timeStamp	M	Number	响应时间戳服务器响应时间（毫秒级）
data	M	Object	响应数据对象包含交易详细信息
orderNum	M	String	商户订单号与请求中提供的orderNum相同用于交易跟踪和参考
platOrderNum	M	String	平台订单号系统生成的内部交易参考号用于内部交易管理和支持
amount	M	Number	交易金额确认的交易金额
fee	M	Number	手续费交易产生的手续费
feeType	M	Number	手续费类型 1：商户承担手续费
status	M	Number	交易状态订单当前处理状态码
statusMsg	M	String	状态消息订单状态的文字描述
bankCode	M	String	SPEI 机构编码（墨西哥）含义见地区支付说明 — 墨西哥
bankCard	M	String	银行卡号/账户号收款人的银行账户号码或钱包账号
accountName	M	String	账户名收款人账户名称
description	O	String	描述交易目的或描述

响应示例

Content-type: application/json

{
    "success": true,
    "code": "9999",
    "msg": "SUCCESS",
    "timeStamp": 1767772957433,
    "data": {
        "orderNum": "MXPAYOUT12345617",
        "platOrderNum": "TRANS2008811496544403456",
        "amount": 100.50,
        "fee": 2,
        "feeType": 1,
        "status": 1,
        "statusMsg": "ORDER_RECEIVED_PROCESSING",
        "bankCode": "40012",
        "bankCard": "012345678901234567",
        "accountName": "Luis Garcia",
        "description": "test"
    }
}

通知

HTTP请求

字段	必填	类型	描述
Content-Type	M	String	HTTP请求内容类型规范固定值：application/json 指示JSON请求格式

通知体

字段	必填	类型	描述
platOrderNum	M	String	平台订单号系统生成的内部交易参考号用于内部交易管理和支持
version	M	String	版本号接口版本标识示例：v1
orderNum	M	String	商户订单号与原始请求中提供的orderNum相同用于交易识别和验证
amount	M	Number	交易金额确认的交易金额
fee	M	Number	手续费交易产生的手续费
feeType	M	Number	手续费类型 1：商户承担手续费
status	M	Number	交易状态取值见交易状态码
statusMsg	M	String	状态消息订单状态的文字描述
bankCode	M	String	SPEI 机构编码（墨西哥）见地区支付说明 — 墨西哥
bankCard	M	String	银行卡号/账户号
accountName	M	String	账户名
description	O	String	描述
sign	M	String	签名回调数据的数字签名

重要响应

通知响应： 请仅返回字符串SUCCESS以确认收到通知

{
    "platOrderNum": "TRANS2008812168572567552",
    "version": "v1",
    "orderNum": "MXPAYOUT12345648",
    "amount": 111.00,
    "fee": 3,
    "feeType": 1,
    "status": 2,
    "statusMsg": "supplement success!",
    "bankCode": "40012",
    "bankCard": "012345678901234567",
    "accountName": "Luis Garcia",
    "description": "test",
    "sign": "KCitZCmhtuoGtVOl/EC4Mn1vwf3QRkoL9Ged0psKiCzATvP0AePNc8P1PEcWrbJYAPctewCRO9jW+vHjtXrh6ozk2OUvVDUlLTiM3PS7ydpeogy+W6w3b4OZDg5vUtaTVwz5mpEKBZv/XEhOes1C16+ec36PLp3Mi0Y0g4ivgwk="
}

SUCCESS

代付订单 · 墨西哥

# 请求

# 请求路径

# 请求头

# 请求体

# 请求体示例 – 付款请求（示例为 BBVA MEXICO 40012 + CLABE 占位；以实际网关为准）：

# 响应

# HTTP响应

# 响应字段

# 响应示例

# 通知

# HTTP请求

# 通知体

# 返回

请求