代付订单 · 秘鲁
大约 5 分钟
请求
代付 API 用于向受益人发起代付交易。本页为 秘鲁（国家码 pe）的代付说明。收款行 bankCode、账户类型与 CCI 等以本国地区说明及下表为准。
请求路径
域名：推荐使用统一域名
openapi.toppayment.com（路径不变）；原国别域名（如global-pe-openapi.toppayment.com）仍可用。
| 环境 | 地址 |
|---|---|
| 沙箱 | https://openapi.toppayment.com/sandbox/pe/disbursement/cash |
| 生产 | https://openapi.toppayment.com/pe/disbursement/cash |
代付 bankCode / bankName（收款行） 见 地区支付说明 — 秘鲁。
请求头
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP内容类型规范 固定值：application/json 正确解析请求所必需 |
请求体
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| mchNo | M | String(32) | 商户编号 平台分配的唯一商户标识符 用于商户认证和交易路由 |
| orderNum | M | String(50) | 商户订单号 唯一交易标识符 格式：字母数字字符串 用于交易跟踪和参考 |
| amount | M | Number(32,8) | 交易金额 格式：数值类型 示例：100 秘鲁地区：须为正数，整数或最多两位小数，不允许全为 0。 |
| bankCode | M | String(32) | 收款银行/钱包编码（秘鲁） 见 地区支付说明 — 秘鲁 中「代付银行及对应编码」 |
| bankCard | C | String(50) | 银行卡号/账号等（若网关仍使用该字段；秘鲁侧 CCI 请优先使用 accountNumber） |
| accountType | M | String(32) | 账户类型：CORRIENTE / AHORROS / WALLET（忽略大小写），见 地区支付说明 — 秘鲁 |
| accountNumber | C | String(100) | CCI 中转账户：非 WALLET 时 必填；去非数字后须为 20 位数字；WALLET 可不填 |
| documentType | M | String(16) | 证件类型：DNI / CE / PAS / RUC（忽略大小写） |
| documentNo | M | String(100) | 证件号码（documento） 不校验号码位数与 documentType 的对应关系。 |
| accountEmail | M | String(255) | 收款人邮箱 须为有效邮箱格式 |
| accountName | M | String(50) | 账户名 收款人姓名，最长 50，仅字母数字空格 |
| 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 | 签名 请求认证的数字签名 参见签名生成 |
请求体示例 – 付款请求（示例为活期 + CCI，字段以实际网关为准）：
Content-type: application/json
{
"mchNo": "{{mchNo}}",
"orderNum": "PEPAYOUT1234561",
"amount": 100.50,
"bankCode": "BCP",
"accountType": "CORRIENTE",
"accountNumber": "00219200212345678901",
"documentType": "DNI",
"documentNo": "12345678",
"accountEmail": "[email protected]",
"accountName": "Juan Perez",
"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 | 银行代码（秘鲁） 含义见 地区支付说明 — 秘鲁 |
| bankCard | M | String | 银行卡号/账户号 收款人的银行账户号码或钱包账号 |
| accountName | M | String | 账户名 收款人账户名称 |
| description | O | String | 描述 交易目的或描述 |
响应示例
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": "SUCCESS",
"timeStamp": 1767772957433,
"data": {
"orderNum": "PEPAYOUT12345617",
"platOrderNum": "TRANS2008811496544403456",
"amount": 100.50,
"fee": 2,
"feeType": 1,
"status": 1,
"statusMsg": "ORDER_RECEIVED_PROCESSING",
"bankCode": "BCP",
"bankCard": "00219200212345678901",
"accountName": "Juan Perez",
"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 | 银行代码（秘鲁） 见 地区支付说明 — 秘鲁 |
| bankCard | M | String | 银行卡号/账户号 |
| accountName | M | String | 账户名 |
| description | O | String | 描述 |
| sign | M | String | 签名 回调数据的数字签名 |
返回
重要响应
通知响应： 请仅返回字符串
SUCCESS以确认收到通知
{
"platOrderNum": "TRANS2008812168572567552",
"version": "v1",
"orderNum": "PEPAYOUT12345648",
"amount": 111.00,
"fee": 3,
"feeType": 1,
"status": 2,
"statusMsg": "supplement success!",
"bankCode": "BCP",
"bankCard": "00219200212345678901",
"accountName": "Juan Perez",
"description": "test",
"sign": "KCitZCmhtuoGtVOl/EC4Mn1vwf3QRkoL9Ged0psKiCzATvP0AePNc8P1PEcWrbJYAPctewCRO9jW+vHjtXrh6ozk2OUvVDUlLTiM3PS7ydpeogy+W6w3b4OZDg5vUtaTVwz5mpEKBZv/XEhOes1C16+ec36PLp3Mi0Y0g4ivgwk="
}
SUCCESS