跳至主要內容

代收订单 · 印尼

TOPPAY Team大约 12 分钟

概述

代收 API 用于向客户发起代收交易。本页为 印度尼西亚(国家码 id)的代收能力说明,支持以下两种下单方式:

下单方式路径说明
收银台模式/pay/prePay默认模式,返回 cashierUrl,用户跳转平台 H5 收银台完成支付
API 模式/pay/transOrder请求中指定 method,直接返回 payData / payDataType(VA、QRIS 等)

method(印尼代收方式编码)见 地区支付说明 — 印尼。

接入说明

默认开通收银台模式。如需对接 API 模式,请联系客服申请商户白名单后再集成。

请求头

两种模式共用:

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

回调版本(两种模式共用)

下单请求均可传 notifyVersion,用于指定异步通知报文版本。大小写不敏感,平台按小写保存到订单;之后的自动通知与补发都使用订单上保存的版本。

字段必填类型描述
notifyVersionOString(8)回调版本
可选 v1、v2、v3(大小写不敏感)
不传或传 v1:回调仅含基础字段
传 v2:在 status 为 SUCCESS 且上游提供有效值时,成功回调可能附带实际付款人信息
传 v3:包含 v2 的全部字段;支付成功且上游提供有效值时,再增加检索参考号 rrn。后续还可能继续增加与 rrn 同级的一级字段
默认 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

请求体

字段必填类型描述
mchNoMString(32)商户编号
平台分配的唯一商户标识符
用于商户认证和交易路由
orderNumMString(64)商户订单号
唯一交易标识符
格式:字母数字字符串
用于交易跟踪和参考
amountMNumber(32,8)交易金额
格式:数值类型
印尼地区不允许小数,请传整数
示例:100000
productDetailMString (100)产品详情
交易目的或描述
格式:UTF-8编码字符串
methodOString (16)支付方式(印尼)
可选;不传则用户在收银台选择。示例:QRIS、DANA、BNI 等,完整列表见 地区支付说明 — 印尼
timestampMString(13)时间戳
请求时间戳(毫秒级)
示例:1749451858772
customerNameMString (64)客户姓名
付款人姓名
格式:UTF-8编码字符串
customerEmailMString (64)客户邮箱
付款人邮箱地址
格式:有效的邮箱格式
customerPhoneMString (32)客户电话
付款人电话号码
格式:有效的电话号码
expiryPeriodONumber(1-9999)过期时间
交易过期时间(分钟)
示例:1440(24小时)
用于设置交易有效期
downNotifyUrlMString(255)异步通知地址
交易状态更新的Webhook通知URL
格式:有效的HTTP/HTTPS URL
用于实时交易状态通知
redirectUrlOString(512)重定向地址
支付成功后浏览器回跳 URL(收银台模式)
格式:有效的 http:// 或 https:// 绝对地址
须与商户已报备的回跳白名单 同源(origin);不传或非法时按白名单规则回退(见下方说明)
notifyVersionOString(8)回调版本
见上文「回调版本」
signMString签名
请求认证的数字签名
参见签名生成

请求体示例

Content-type: application/json

响应字段

字段必填类型描述
successMBoolean请求是否成功
true:成功,false:失败
codeMString响应状态码
9999:成功
其他:失败
msgOString响应消息
可读的响应状态描述
成功时为null
timeStampMNumber响应时间戳
服务器响应时间(毫秒级)
dataMObject响应数据对象
包含交易详细信息
orderNumMString商户订单号
与请求中提供的orderNum相同
用于交易跟踪和参考
platOrderNumMString平台订单号
系统生成的内部交易参考号
用于内部交易管理和支持
amountMNumber交易金额
确认的交易金额
feeMNumber手续费
交易产生的手续费
methodMString支付方式(印尼)
以实际返回为准。编码含义见 地区支付说明 — 印尼
productDetailMString产品详情
交易目的或描述
customerNameMString客户姓名
付款人姓名
customerEmailMString客户邮箱
付款人邮箱地址
customerPhoneMString客户电话
付款人电话号码
validTimeMNumber有效期时间戳
交易过期时间(毫秒级时间戳)
cashierUrlMString收银台URL
用于跳转支付的收银台地址

响应示例

Content-type: application/json

收银台成功回跳

支付成功后,可将付款人浏览器回跳至商户指定页面。该能力默认关闭,如需使用请通过 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

请求体

与收银台模式相比,差异如下:

字段必填类型描述
methodMString(16)支付方式(印尼)
API 模式必传。示例:QRIS、DANA、BNI 等,完整列表见 地区支付说明 — 印尼

其余字段(含 notifyVersion)与收银台模式相同。

请求体示例

Content-type: application/json

响应字段

公共响应字段(success、code、msg、timeStamp 及 data 中的 orderNum、platOrderNum、amount、fee、method、productDetail、customerName、customerEmail、customerPhone、validTime)与收银台模式相同。API 模式重点关注:

字段必填类型描述
payDataMString支付数据
VA 账号、QRIS 字符串、跳转链接等,具体含义由 payDataType 决定
payDataTypeMString支付数据类型
取值:VA、QR_CODE、QR_URL、CASHIER_URL
cashierUrlOString收银台 URL
部分通道可能同时返回,API 模式请以 payData 为准

payDataType 说明

payDataType说明典型 method
VA虚拟账号,商户引导用户向该账号转账BNI、BCA、MANDIRI、BRI 等银行 VA
QR_CODEQRIS 二维码内容字符串,需自行渲染为二维码QRIS
QR_URL二维码图片或扫码页链接部分 QRIS / 钱包场景
CASHIER_URL上游支付页跳转链接DANA、OVO 等钱包

响应示例

Content-type: application/json

通知

两种下单方式的异步通知一致。报文版本由下单时保存的 notifyVersion 决定(未传则为 v1)。请用回调顶层字段 version 识别实际版本(V3 为 "version":"v3"),不要用下单参数名 notifyVersion 判断已经收到的回调。

HTTP请求

字段必填类型描述
Content-TypeMStringHTTP请求内容类型规范
固定值:application/json
指示JSON请求格式

通知体(v1 / 基础字段)

字段必填类型描述
platOrderNumMString平台订单号
系统生成的内部交易参考号
用于内部交易管理和支持
versionMString回调版本
与订单保存的 notifyVersion 一致
示例:v1、v2、v3
orderNumMString商户订单号
与原始请求中提供的orderNum相同
用于交易识别和验证
amountMNumber交易金额
确认的交易金额
feeMNumber手续费
交易产生的手续费
customerNameMString客户姓名
下单时填写的付款人姓名(非实际付款账户户名)
customerEmailMString客户邮箱
付款人邮箱地址
customerPhoneMString客户电话
付款人电话号码
statusMString交易状态
取值见 交易状态码
指示交易的最终状态
signMString签名
回调数据的数字签名
用于验证回调数据的真实性

通知体(v2 扩展字段)

当 notifyVersion 为 v2 或 v3,且 status 为 SUCCESS 时,若上游提供了有效付款人信息,回调可能额外包含下列字段。某一项没有有效值时,该项不出现在报文中:

字段必填类型描述
payerNameOString付款人姓名
实际付款账户户名(与下单 customerName 可能不同)
payerAccountNoOString付款人账号
实际付款账号
payerAccountBankOString付款账号开户行
实际付款银行或渠道名称

非成功状态的回调结构与 v1 相同,不含上述字段。是否返回取决于支付通道是否提供,请按字段缺失兼容处理。

通知体(v3 扩展字段)

v3 包含上面的基础字段和付款人字段。支付成功且上游提供有效检索参考号时,再增加:

字段必填类型描述
rrnOString检索参考号(Retrieval Reference Number)
QRIS 等成功交易的渠道检索号
按字符串接收,保留前导零,不要按数字解析
无有效值时不返回

v3 报文始终是一级 JSON。平台后续还可能增加与 rrn 同级的新字段,字段集合不是固定的。请忽略暂不使用的未知字段,不要按固定字段个数校验,也不要拒绝未知一级字段。

付款人字段与 rrn 相互独立:其中一项为空时只省略该项。空字符串和 null 不下发,也不参与签名。

v1、v2 回调不会出现 rrn 及后续新增的 V3 字段。支付成功后,代收订单查询 仅在该订单为 v3 时可能返回字符串 rrn;v1、v2 订单不返回。

回调验签

v1、v2、v3 使用同一套 RSA 规则,不新增签名类型。平台用平台私钥签名,商户使用后台 API 配置 中的平台公钥验签。拼接与解密方式见 签名规则。

验签配置:

  1. 用原始 JSON、Map 或 JSONObject 完整接收请求体,保留全部一级字段。
  2. 读取顶层 version。"version":"v3" 表示 V3。
  3. 排除 sign。其余实际收到的非空一级字段,按字段名 ASCII 升序排序,只拼接参数值,中间不加分隔符。
  4. 用平台公钥解密 sign,与第 3 步明文一致即通过。
  5. 验签成功后再读取业务字段、更新订单。成功处理后返回 HTTP 200,响应正文仅为字符串 SUCCESS。

v3 不能使用固定字段白名单验签。后续新增的同级字段必须参加验签。验签完成前不要反序列化成固定字段实体,否则未知字段被丢弃会导致验签失败。金额和 rrn 都按报文里的原始文本参与拼接,不要先转成数字再格式化。

以下方 v3 成功回调为例,参与签名的字段名按 ASCII 升序为 amount、customerEmail、customerName、customerPhone、fee、orderNum、payerAccountBank、payerAccountNo、payerName、platOrderNum、rrn、status、version,明文为:

100000budi@email.comBudi0812345678902000ID12345621BNI081234567890BUDI SANTOSOPRE2009165141186183168021116498933SUCCESSv3

报文里没有出现的可选字段不要补空值。请遍历实际收到的 Key 拼接,不要按示例写死字段列表。

返回

重要响应

通知响应: 请仅返回字符串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="
}