代付订单 · 巴西

请求

代付 API 用于向受益人发起代付交易。本页为巴西（国家码 br）的代付说明。巴西代付走 PIX，开放字段与 bankCode / bankCard / accountName / taxNumber 的映射及取值见地区支付说明 — 巴西；除通用校验外，代付还须满足本地区 PIX、金额与税号 等规则，详见下表及地区说明。

请求路径

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

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

代付 PIX 类型（bankCode）、bankCard（PIX 密钥）、taxNumber 等见地区支付说明 — 巴西。

请求头

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

请求体

字段	必填	类型	描述
mchNo	M	String(32)	商户编号平台分配的唯一商户标识符用于商户认证和交易路由
orderNum	M	String(50)	商户订单号唯一交易标识符格式：字母数字字符串用于交易跟踪和参考
amount	M	Number(32,8)	交易金额格式：数值类型示例：100.50 巴西地区：须为正数，整数或最多两位小数，不允许全为 0，不允许三位及以上小数。
accountName	M	String(50)	收款人姓名（业务字段 `name`）最长 50；仅 Unicode 字母、数字、空格
bankCode	M	String(32)	PIX 类型（业务字段 `pixType`）须为 CPF / CNPJ / PHONE / EMAIL / EVP 之一，忽略大小写；与展示名对照见地区支付说明 — 巴西
bankCard	M	String(50)	PIX 账号/密钥（业务字段 `pixAccount`）按 `bankCode` 校验：CPF/CNPJ 去非数字后须为 11/14 位；PHONE 去空格后须 `+55` 开头 + 10～11 位数字；EMAIL 须合法邮箱；EVP 须 32 位字母数字。详见地区说明
taxNumber	O	String(64)	可选税号有值时去非数字后须为 11 位（CPF）或 14 位（CNPJ）
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	签名请求认证的数字签名参见签名生成

请求体示例 – 付款请求（示例为 CPF PIX；`bankCode` / `bankCard` 以实际类型为准）：

Content-type: application/json

{
    "mchNo": "{{mchNo}}",
    "orderNum": "BRPAYOUT1234561",
    "amount": 100.50,
    "accountName": "Maria Silva",
    "bankCode": "CPF",
    "bankCard": "52998224725",
    "taxNumber": "52998224725",
    "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	PIX 类型（`bankCode`）含义见地区支付说明 — 巴西
bankCard	M	String	PIX 账号/密钥回显或脱敏
accountName	M	String	账户名收款人账户名称
description	O	String	描述交易目的或描述

响应示例

Content-type: application/json

{
    "success": true,
    "code": "9999",
    "msg": "SUCCESS",
    "timeStamp": 1767772957433,
    "data": {
        "orderNum": "BRPAYOUT12345617",
        "platOrderNum": "TRANS2008811496544403456",
        "amount": 100.50,
        "fee": 2,
        "feeType": 1,
        "status": 1,
        "statusMsg": "ORDER_RECEIVED_PROCESSING",
        "bankCode": "CPF",
        "bankCard": "52998224725",
        "accountName": "Maria Silva",
        "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	PIX 类型见地区支付说明 — 巴西
bankCard	M	String	PIX 账号/密钥
accountName	M	String	账户名
description	O	String	描述
sign	M	String	签名回调数据的数字签名

重要响应

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

{
    "platOrderNum": "TRANS2008812168572567552",
    "version": "v1",
    "orderNum": "BRPAYOUT12345648",
    "amount": 111.00,
    "fee": 3,
    "feeType": 1,
    "status": 2,
    "statusMsg": "supplement success!",
    "bankCode": "CPF",
    "bankCard": "52998224725",
    "accountName": "Maria Silva",
    "description": "test",
    "sign": "…"
}

SUCCESS

代付订单 · 巴西

# 请求

# 请求路径

# 请求头

# 请求体

# 请求体示例 – 付款请求（示例为 CPF PIX；bankCode / bankCard 以实际类型为准）：

# 响应

# HTTP响应

# 响应字段

# 响应示例

# 通知

# HTTP请求

# 通知体

# 返回

请求