代收订单 · 秘鲁
大约 5 分钟
请求
代收 API 用于向客户发起代收交易。本页为 秘鲁（国家码 pe）的代收能力说明。请求与响应体字段与其他国家一致，method 等枚举以本国地区说明为准。
请求路径
域名：推荐使用统一域名
openapi.toppayment.com（路径不变）；原国别域名（如global-pe-openapi.toppayment.com）仍可用。
| 环境 | 地址 |
|---|---|
| 沙箱 | https://openapi.toppayment.com/sandbox/pe/pay/prePay |
| 生产 | https://openapi.toppayment.com/pe/pay/prePay |
method（秘鲁代收方式编码）见 地区支付说明 — 秘鲁。
请求头
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP内容类型规范 固定值：application/json 正确解析请求所必需 |
请求体
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| mchNo | M | String(32) | 商户编号 平台分配的唯一商户标识符 用于商户认证和交易路由 |
| orderNum | M | String(64) | 商户订单号 唯一交易标识符 格式：字母数字字符串 用于交易跟踪和参考 |
| amount | M | Number(32,8) | 交易金额 格式：数值类型 示例：100 秘鲁地区：须为正数，整数或最多两位小数，不允许全为 0。 |
| productDetail | M | String (100) | 产品详情 交易目的或描述 格式：UTF-8编码字符串 |
| method | O | String (16) | 支付方式（秘鲁） 当前为 DOCUMENTS，详见 地区支付说明 — 秘鲁 |
| timestamp | M | String(13) | 时间戳 请求时间戳（毫秒级） 示例：1749451858772 |
| customerName | M | String (64) | 客户姓名 付款人姓名 格式：UTF-8编码字符串 秘鲁路由：最长 50，仅 Unicode 字母、数字、空格。 |
| customerEmail | M | String (64) | 客户邮箱 付款人邮箱地址 格式：有效的邮箱格式 秘鲁路由：若有值须为合法邮箱。 |
| customerPhone | M | String (32) | 客户电话 付款人电话号码 格式：有效的电话号码 |
| documentType | C | String (16) | 证件类型 与 documentNo 成对使用；填写了 documentNo 时 必填。取值见 地区支付说明 — 秘鲁（DNI / CE / PAS / RUC，忽略大小写） |
| documentNo | C | String (100) | 证件号码 可选；有值时必须同时传 documentType；不校验位数与证件类型对应关系 |
| expiryPeriod | O | Number(1-9999) | 过期时间 交易过期时间（分钟） 示例：1440（24小时） 用于设置交易有效期 |
| downNotifyUrl | M | String(255) | 异步通知地址 交易状态更新的Webhook通知URL 格式：有效的HTTP/HTTPS URL 用于实时交易状态通知 |
| redirectUrl | O | String(512) | 重定向地址 支付完成后客户重定向URL 格式：有效的HTTP/HTTPS URL 用于支付处理后重定向客户(收银台模式可用) |
| sign | M | String | 签名 请求认证的数字签名 参见签名生成 |
请求体示例 – 交易请求：
Content-type: application/json
{
"mchNo": "{{mchNo}}",
"orderNum": "PE1234561",
"amount": 100.50,
"productDetail": "测试商品",
"method": "DOCUMENTS",
"timestamp": "1749451858772",
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/return",
"sign": "按签名规则生成后替换"
}
响应
HTTP响应
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP响应内容类型规范 固定值：application/json 指示JSON响应格式 |
响应字段
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| success | M | Boolean | 请求是否成功 true：成功，false：失败 |
| code | M | String | 响应状态码 9999：成功 其他：失败 |
| msg | O | String | 响应消息 可读的响应状态描述 成功时为null |
| timeStamp | M | Number | 响应时间戳 服务器响应时间（毫秒级） |
| data | M | Object | 响应数据对象 包含交易详细信息 |
| orderNum | M | String | 商户订单号 与请求中提供的orderNum相同 用于交易跟踪和参考 |
| platOrderNum | M | String | 平台订单号 系统生成的内部交易参考号 用于内部交易管理和支持 |
| amount | M | Number | 交易金额 确认的交易金额 |
| fee | M | Number | 手续费 交易产生的手续费 |
| method | M | String | 支付方式（秘鲁） 以实际返回为准。编码含义见 地区支付说明 — 秘鲁 |
| productDetail | M | String | 产品详情 交易目的或描述 |
| customerName | M | String | 客户姓名 付款人姓名 |
| customerEmail | M | String | 客户邮箱 付款人邮箱地址 |
| customerPhone | M | String | 客户电话 付款人电话号码 |
| validTime | M | Number | 有效期时间戳 交易过期时间（毫秒级时间戳） |
| cashierUrl | M | String | 收银台URL 用于跳转支付的收银台地址 (收银台模式特有) |
| payData | M | String | 支付数据 支付跳转链接或支付数据(API模式特有) |
| payDataType | M | String | 支付数据类型 示例：CASHIER_URL（收银台链接） (API模式特有) |
响应示例
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "PE1234561",
"platOrderNum": "PRE2009093829059153920",
"amount": 100000,
"fee": 2000.0,
"method": "DOCUMENTS",
"productDetail": "测试商品",
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay",
"payData": "https://example.cashier/pay",
"payDataType": "CASHIER_URL"
}
}
通知
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 | 手续费 交易产生的手续费 |
| customerName | M | String | 客户姓名 付款人姓名 |
| customerEmail | M | String | 客户邮箱 付款人邮箱地址 |
| customerPhone | M | String | 客户电话 付款人电话号码 |
| status | M | String | 交易状态 取值见 交易状态码 指示交易的最终状态 |
| sign | M | String | 签名 回调数据的数字签名 用于验证回调数据的真实性 |
返回
重要响应
通知响应： 请仅返回字符串
SUCCESS以确认收到通知
{
"platOrderNum": "PRE2009165141186183168",
"version": "v1",
"orderNum": "PE12345621",
"amount": 100000,
"fee": 2000,
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"status": "SUCCESS",
"sign": "m5++HHEOfaVL3opFSuihVE4kkdLaCyhpFVSSLJld8WeEhlH93Ido5MQQ6peWrf+8eCkQd127jesL9esQDdFAiGKkem5BwvqTAvZGQm9v7M33Sy+W58OkGkb3/8BxQwCLTIUouhwpj1TwIeqP3JWo3AFMm5qezH3JbVfOd1IZ9Gw="
}
SUCCESS