代收订单 · 印尼
大约 9 分钟
概述
代收 API 用于向客户发起代收交易。本页为 印度尼西亚（国家码 id）的代收能力说明，支持以下两种下单方式：
| 下单方式 | 路径 | 说明 |
|---|---|---|
| 收银台模式 | /pay/prePay | 默认模式，返回 cashierUrl，用户跳转平台 H5 收银台完成支付 |
| API 模式 | /pay/transOrder | 请求中指定 method，直接返回 payData / payDataType（VA、QRIS 等） |
method（印尼代收方式编码）见 地区支付说明 — 印尼。
接入说明
默认开通收银台模式。如需对接 API 模式，请联系客服申请商户白名单后再集成。
请求头
两种模式共用：
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP内容类型规范 固定值：application/json 正确解析请求所必需 |
回调版本（两种模式共用）
下单请求均可传 notifyVersion，用于指定异步通知报文版本：
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| notifyVersion | O | String(8) | 回调版本 可选 v1 或 v2（大小写不敏感）不传或传 v1：回调仅含基础字段传 v2：在 status 为 SUCCESS 且上游通道支持时，成功回调可能附带实际付款人信息（见下方「通知」）默认 v1 |
收银台模式（prePay）
商户预下单后获取 cashierUrl，引导用户至平台收银台选择支付方式并完成付款。
请求路径
域名：推荐使用统一域名
openapi.toppayment.com（路径不变）；原国别域名（如global-id-openapi.toppayment.com）仍可用。
| 环境 | 地址 |
|---|---|
| 沙箱 | https://openapi.toppayment.com/sandbox/id/pay/prePay |
| 生产 | https://openapi.toppayment.com/id/pay/prePay |
请求体
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| mchNo | M | String(32) | 商户编号 平台分配的唯一商户标识符 用于商户认证和交易路由 |
| orderNum | M | String(64) | 商户订单号 唯一交易标识符 格式：字母数字字符串 用于交易跟踪和参考 |
| amount | M | Number(32,8) | 交易金额 格式：数值类型 印尼地区不允许小数，请传整数 示例：100000 |
| productDetail | M | String (100) | 产品详情 交易目的或描述 格式：UTF-8编码字符串 |
| method | O | String (16) | 支付方式（印尼） 可选；不传则用户在收银台选择。示例：QRIS、DANA、BNI 等，完整列表见 地区支付说明 — 印尼 |
| timestamp | M | String(13) | 时间戳 请求时间戳（毫秒级） 示例：1749451858772 |
| customerName | M | String (64) | 客户姓名 付款人姓名 格式：UTF-8编码字符串 |
| customerEmail | M | String (64) | 客户邮箱 付款人邮箱地址 格式：有效的邮箱格式 |
| customerPhone | M | String (32) | 客户电话 付款人电话号码 格式：有效的电话号码 |
| expiryPeriod | O | Number(1-9999) | 过期时间 交易过期时间（分钟） 示例：1440（24小时） 用于设置交易有效期 |
| downNotifyUrl | M | String(255) | 异步通知地址 交易状态更新的Webhook通知URL 格式：有效的HTTP/HTTPS URL 用于实时交易状态通知 |
| redirectUrl | O | String(512) | 重定向地址 支付成功后浏览器回跳 URL（收银台模式） 格式：有效的 http:// 或 https:// 绝对地址须与商户已报备的回跳白名单 同源（origin）；不传或非法时按白名单规则回退（见下方说明） |
| notifyVersion | O | String(8) | 回调版本 见上文「回调版本」 |
| sign | M | String | 签名 请求认证的数字签名 参见签名生成 |
请求体示例
Content-type: application/json
{
"mchNo": "{{mchNo}}",
"orderNum": "ID1234561",
"amount": 100000,
"productDetail": "测试商品",
"method": "DANA",
"timestamp": "1749451858772",
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/return",
"notifyVersion": "v2",
"sign": "按签名规则生成后替换"
}
响应字段
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| 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 用于跳转支付的收银台地址 |
响应示例
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "ID1234561",
"platOrderNum": "PRE2009093829059153920",
"amount": 100000,
"fee": 2000.0,
"method": "DANA",
"productDetail": "测试商品",
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay"
}
}
收银台成功回跳
支付成功后，可将付款人浏览器回跳至商户指定页面。该能力默认关闭，如需使用请通过 Telegram 联系客服开通，并由客服在后台配置回跳地址白名单（可配置多条）。
下单时可传可选参数 redirectUrl，规则如下：
- 须为
http://或https://绝对地址（不支持相对路径或其它协议） - 仅在支付成功时回跳；支付失败或未完成支付不回跳
- 传了合法
redirectUrl且其 origin 命中商户白名单：支付成功后原样回跳至该地址（不自动追加orderNum） - 未传或为空/非法：回跳至白名单第一条地址，并自动附加 query 参数
orderNum（与下单orderNum一致）
示例：https://merchant.example.com/pay/result?orderNum=ID1234561 - 传了
redirectUrl但 origin 不在白名单内：支付成功后不回跳（不回退至白名单第一条）
API 模式（transOrder）
商户在请求中指定支付方式后，直接向支付通道发起交易，并在响应中返回 payData / payDataType（如 VA 账号、QRIS 码、跳转链接等），无需跳转平台 H5 收银台。
请求路径
| 环境 | 地址 |
|---|---|
| 沙箱 | https://openapi.toppayment.com/sandbox/id/pay/transOrder |
| 生产 | https://openapi.toppayment.com/id/pay/transOrder |
请求体
与收银台模式相比，差异如下：
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| method | M | String(16) | 支付方式（印尼） API 模式必传。示例：QRIS、DANA、BNI 等，完整列表见 地区支付说明 — 印尼 |
其余字段（含 notifyVersion）与收银台模式相同。
请求体示例
Content-type: application/json
{
"mchNo": "{{mchNo}}",
"orderNum": "IDAPI1234561",
"amount": 100000,
"productDetail": "测试商品",
"method": "QRIS",
"timestamp": "1749451858772",
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"sign": "按签名规则生成后替换"
}
{
"mchNo": "{{mchNo}}",
"orderNum": "IDAPI7890121",
"amount": 100000,
"productDetail": "测试商品",
"method": "BNI",
"timestamp": "1749451858772",
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"sign": "按签名规则生成后替换"
}
响应字段
公共响应字段（success、code、msg、timeStamp 及 data 中的 orderNum、platOrderNum、amount、fee、method、productDetail、customerName、customerEmail、customerPhone、validTime）与收银台模式相同。API 模式重点关注：
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| payData | M | String | 支付数据 VA 账号、QRIS 字符串、跳转链接等，具体含义由 payDataType 决定 |
| payDataType | M | String | 支付数据类型 取值： VA、QR_CODE、QR_URL、CASHIER_URL |
| cashierUrl | O | String | 收银台 URL 部分通道可能同时返回，API 模式请以 payData 为准 |
payDataType 说明
| payDataType | 说明 | 典型 method |
|---|---|---|
VA | 虚拟账号，商户引导用户向该账号转账 | BNI、BCA、MANDIRI、BRI 等银行 VA |
QR_CODE | QRIS 二维码内容字符串，需自行渲染为二维码 | QRIS |
QR_URL | 二维码图片或扫码页链接 | 部分 QRIS / 钱包场景 |
CASHIER_URL | 上游支付页跳转链接 | DANA、OVO 等钱包 |
响应示例
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "IDAPI1234561",
"platOrderNum": "PRE2009093829059153920",
"amount": 100000,
"fee": 2000.0,
"method": "QRIS",
"productDetail": "测试商品",
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"validTime": 1767926672819,
"payData": "00020101021226650016COM.DANA.WWW0118936009140812345678900303UMM5144005405100000050205035406100000005802ID5913Test Merchant6007Jakarta61051234062070703A0304140212345678901234567890123456789012345678901234567890123456789012345678906304ABCD",
"payDataType": "QR_CODE"
}
}
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "IDAPI7890121",
"platOrderNum": "PRE2009093829059153921",
"amount": 100000,
"fee": 2000.0,
"method": "BNI",
"productDetail": "测试商品",
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"validTime": 1767926672819,
"payData": "8812345678901234",
"payDataType": "VA"
}
}
通知
两种下单方式的异步通知一致。回调报文版本由下单时的 notifyVersion 决定（未传则为 v1），响应体中的 version 字段与之一致。
HTTP请求
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| Content-Type | M | String | HTTP请求内容类型规范 固定值：application/json 指示JSON请求格式 |
通知体（v1 / 基础字段）
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| platOrderNum | M | String | 平台订单号 系统生成的内部交易参考号 用于内部交易管理和支持 |
| version | M | String | 回调版本 与下单时 notifyVersion 对应示例： v1、v2 |
| 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 | 签名 回调数据的数字签名 用于验证回调数据的真实性 |
通知体（v2 扩展字段）
当 notifyVersion 为 v2 且 status 为 SUCCESS 时，若上游通道回传了付款人信息，回调可能额外包含下列字段（部分渠道支持，无数据时不返回或为空）：
| 字段 | 必填 | 类型 | 描述 |
|---|---|---|---|
| payerName | O | String | 付款人姓名 实际付款账户户名（与下单 customerName 可能不同） |
| payerAccountNo | O | String | 付款人账号 实际付款账号 |
| payerAccountBank | O | String | 付款账号开户行 实际付款银行或渠道名称 |
v2 说明
v2仅影响成功状态回调是否尝试附带付款人信息；失败等非成功状态回调结构与v1相同，不含上述扩展字段。- 是否返回
payerName/payerAccountNo/payerAccountBank取决于支付通道是否在上游回调中提供，商户侧应做兼容处理。
返回
重要响应
通知响应： 请仅返回字符串
SUCCESS以确认收到通知
{
"platOrderNum": "PRE2009165141186183168",
"version": "v1",
"orderNum": "ID12345621",
"amount": 100000,
"fee": 2000,
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"status": "SUCCESS",
"sign": "m5++HHEOfaVL3opFSuihVE4kkdLaCyhpFVSSLJld8WeEhlH93Ido5MQQ6peWrf+8eCkQd127jesL9esQDdFAiGKkem5BwvqTAvZGQm9v7M33Sy+W58OkGkb3/8BxQwCLTIUouhwpj1TwIeqP3JWo3AFMm5qezH3JbVfOd1IZ9Gw="
}
{
"platOrderNum": "PRE2009165141186183168",
"version": "v2",
"orderNum": "ID12345621",
"amount": 100000,
"fee": 2000,
"customerName": "Budi",
"customerEmail": "[email protected]",
"customerPhone": "081234567890",
"status": "SUCCESS",
"payerName": "BUDI SANTOSO",
"payerAccountNo": "081234567890",
"payerAccountBank": "BNI",
"sign": "m5++HHEOfaVL3opFSuihVE4kkdLaCyhpFVSSLJld8WeEhlH93Ido5MQQ6peWrf+8eCkQd127jesL9esQDdFAiGKkem5BwvqTAvZGQm9v7M33Sy+W58OkGkb3/8BxQwCLTIUouhwpj1TwIeqP3JWo3AFMm5qezH3JbVfOd1IZ9Gw="
}
SUCCESS