跳至主要內容

快速开始

TOPPAY Team大约 8 分钟

概览

本页汇总全球化开放 API 的接入路径、环境选择、签名规则与常用接口，便于快速落地。详细流程请参考下方链接。

快速导航

地区支付说明

接入步骤（建议顺序）

  1. 选择环境并获取商户号

    • 沙箱：商户号前缀 SD，路径含 /sandbox/（示例链接见沙箱文档）。
    • 生产：使用正式商户号，路径不含 /sandbox/。

  2. 准备密钥

    • RSA PKCS#8（推荐 2048 位），保留商户私钥用于签名，将商户公钥上传后台。
    • 平台公钥从后台获取，用于回调验签。

  3. 确认必填参数

    • mchNo（环境对应的商户号）
    • sign（按签名规则生成）
    • downNotifyUrl（代收/代付各自回调）
    • timestamp（13 位毫秒级 Unix 时间戳）

  4. 构建请求域名与路径

    域名说明

    类型域名适用范围说明
    统一域名（推荐）openapi.toppayment.com全部法币国家及数字货币法币路径 /{countryCode}/...；数字货币路径 /crypto/...；原域名可继续使用
    国别域名（兼容）global-{countryCode}-openapi.toppayment.com全部法币国家例如 global-ng-openapi.toppayment.com
    数字货币原域名（兼容）global-digit-openapi.toppayment.com数字货币路径仍为 /crypto/...

    路径模板（{host} 按上表选择）：

    • 法币沙箱：https://{host}/sandbox/{countryCode}/...
    • 法币生产：https://{host}/{countryCode}/...
    • 数字货币沙箱：https://{host}/crypto/sandbox/...
    • 数字货币生产：https://{host}/crypto/...

    示例：

    • 尼日利亚（推荐）：https://openapi.toppayment.com/ng/pay/prePay
    • 尼日利亚（兼容老域）：https://global-ng-openapi.toppayment.com/ng/pay/prePay
    • 菲律宾（推荐）：https://openapi.toppayment.com/ph/pay/prePay
    • 印尼（推荐）：https://openapi.toppayment.com/id/pay/prePay

    {countryCode} 对照：ph（菲律宾）、id（印尼）、in（印度）、th（泰国）、vn（越南）、pe（秘鲁）、br（巴西）、mx（墨西哥）、co（哥伦比亚）、bo（玻利维亚）、pk（巴基斯坦）、bd（孟加拉）、ng（尼日利亚）。

  5. 选择接口

下表地址按推荐统一域名 openapi.toppayment.com 填写；原国别域名（如 global-ng-openapi.toppayment.com）仍可用。

代收下单

国家/地区文档与参数沙箱地址生产地址
菲律宾（ph）代收订单-菲律宾，method 见 地区说明 — 菲律宾https://openapi.toppayment.com/sandbox/ph/pay/prePayhttps://openapi.toppayment.com/ph/pay/prePay
印尼（id）代收订单-印尼，method 见 地区说明 — 印尼https://openapi.toppayment.com/sandbox/id/pay/prePayhttps://openapi.toppayment.com/id/pay/prePay
尼日利亚（ng）代收订单-尼日利亚，method 见 地区说明 — 尼日利亚https://openapi.toppayment.com/sandbox/ng/pay/prePayhttps://openapi.toppayment.com/ng/pay/prePay
印度（in）代收订单-印度，method 见 地区说明 — 印度https://openapi.toppayment.com/sandbox/in/pay/prePayhttps://openapi.toppayment.com/in/pay/prePay
泰国（th）代收订单-泰国，method 见 地区说明 — 泰国https://openapi.toppayment.com/sandbox/th/pay/prePayhttps://openapi.toppayment.com/th/pay/prePay
越南（vn）代收订单-越南，method 见 地区说明 — 越南https://openapi.toppayment.com/sandbox/vn/pay/prePayhttps://openapi.toppayment.com/vn/pay/prePay
秘鲁（pe）代收订单-秘鲁，method 见 地区说明 — 秘鲁https://openapi.toppayment.com/sandbox/pe/pay/prePayhttps://openapi.toppayment.com/pe/pay/prePay
巴西（br）代收订单-巴西，method 见 地区说明 — 巴西https://openapi.toppayment.com/sandbox/br/pay/prePayhttps://openapi.toppayment.com/br/pay/prePay
墨西哥（mx）代收订单-墨西哥，method 见 地区说明 — 墨西哥https://openapi.toppayment.com/sandbox/mx/pay/prePayhttps://openapi.toppayment.com/mx/pay/prePay
哥伦比亚（co）代收订单-哥伦比亚，method 见 地区说明 — 哥伦比亚https://openapi.toppayment.com/sandbox/co/pay/prePayhttps://openapi.toppayment.com/co/pay/prePay
玻利维亚（bo）代收订单-玻利维亚，method 见 地区说明 — 玻利维亚https://openapi.toppayment.com/sandbox/bo/pay/prePayhttps://openapi.toppayment.com/bo/pay/prePay
巴基斯坦（pk）代收订单-巴基斯坦，method 见 地区说明 — 巴基斯坦https://openapi.toppayment.com/sandbox/pk/pay/prePayhttps://openapi.toppayment.com/pk/pay/prePay
孟加拉（bd）代收订单-孟加拉，method 见 地区说明 — 孟加拉https://openapi.toppayment.com/sandbox/bd/pay/prePayhttps://openapi.toppayment.com/bd/pay/prePay

代收查询

字段与示例见 代收订单查询；请求体需 orderNum 与 platOrderNum 至少其一。

国家/地区沙箱地址生产地址
菲律宾（ph）https://openapi.toppayment.com/sandbox/ph/pay/queryhttps://openapi.toppayment.com/ph/pay/query
印尼（id）https://openapi.toppayment.com/sandbox/id/pay/queryhttps://openapi.toppayment.com/id/pay/query
尼日利亚（ng）https://openapi.toppayment.com/sandbox/ng/pay/queryhttps://openapi.toppayment.com/ng/pay/query
印度（in）https://openapi.toppayment.com/sandbox/in/pay/queryhttps://openapi.toppayment.com/in/pay/query
泰国（th）https://openapi.toppayment.com/sandbox/th/pay/queryhttps://openapi.toppayment.com/th/pay/query
越南（vn）https://openapi.toppayment.com/sandbox/vn/pay/queryhttps://openapi.toppayment.com/vn/pay/query
秘鲁（pe）https://openapi.toppayment.com/sandbox/pe/pay/queryhttps://openapi.toppayment.com/pe/pay/query
巴西（br）https://openapi.toppayment.com/sandbox/br/pay/queryhttps://openapi.toppayment.com/br/pay/query
墨西哥（mx）https://openapi.toppayment.com/sandbox/mx/pay/queryhttps://openapi.toppayment.com/mx/pay/query
哥伦比亚（co）https://openapi.toppayment.com/sandbox/co/pay/queryhttps://openapi.toppayment.com/co/pay/query
玻利维亚（bo）https://openapi.toppayment.com/sandbox/bo/pay/queryhttps://openapi.toppayment.com/bo/pay/query
巴基斯坦（pk）https://openapi.toppayment.com/sandbox/pk/pay/queryhttps://openapi.toppayment.com/pk/pay/query
孟加拉（bd）https://openapi.toppayment.com/sandbox/bd/pay/queryhttps://openapi.toppayment.com/bd/pay/query

主子单查询

字段与示例见 主子单查询；请求体需 orderNum 与 platOrderNum 至少其一。

本接口仅提供生产环境，无沙箱地址。

国家/地区地址
墨西哥（mx）https://openapi.toppayment.com/mx/pay/querySubOrders
哥伦比亚（co）https://openapi.toppayment.com/co/pay/querySubOrders

代付下单

国家/地区文档与参数沙箱地址生产地址
菲律宾（ph）代付订单-菲律宾，bankCode 见 地区说明 — 菲律宾https://openapi.toppayment.com/sandbox/ph/disbursement/cashhttps://openapi.toppayment.com/ph/disbursement/cash
印尼（id）代付订单-印尼，bankCode 见 地区说明 — 印尼https://openapi.toppayment.com/sandbox/id/disbursement/cashhttps://openapi.toppayment.com/id/disbursement/cash
尼日利亚（ng）代付订单-尼日利亚，bankCode 见 地区说明 — 尼日利亚https://openapi.toppayment.com/sandbox/ng/disbursement/cashhttps://openapi.toppayment.com/ng/disbursement/cash
印度（in）代付订单-印度，bankCode 见 地区说明 — 印度https://openapi.toppayment.com/sandbox/in/disbursement/cashhttps://openapi.toppayment.com/in/disbursement/cash
泰国（th）代付订单-泰国，bankCode 见 地区说明 — 泰国https://openapi.toppayment.com/sandbox/th/disbursement/cashhttps://openapi.toppayment.com/th/disbursement/cash
越南（vn）代付订单-越南，bankCode 见 地区说明 — 越南https://openapi.toppayment.com/sandbox/vn/disbursement/cashhttps://openapi.toppayment.com/vn/disbursement/cash
秘鲁（pe）代付订单-秘鲁，bankCode 见 地区说明 — 秘鲁https://openapi.toppayment.com/sandbox/pe/disbursement/cashhttps://openapi.toppayment.com/pe/disbursement/cash
巴西（br）代付订单-巴西，bankCode 见 地区说明 — 巴西https://openapi.toppayment.com/sandbox/br/disbursement/cashhttps://openapi.toppayment.com/br/disbursement/cash
墨西哥（mx）代付订单-墨西哥，bankCode 见 地区说明 — 墨西哥https://openapi.toppayment.com/sandbox/mx/disbursement/cashhttps://openapi.toppayment.com/mx/disbursement/cash
哥伦比亚（co）代付订单-哥伦比亚，bankCode 见 地区说明 — 哥伦比亚https://openapi.toppayment.com/sandbox/co/disbursement/cashhttps://openapi.toppayment.com/co/disbursement/cash
玻利维亚（bo）代付订单-玻利维亚，bankCode 见 地区说明 — 玻利维亚https://openapi.toppayment.com/sandbox/bo/disbursement/cashhttps://openapi.toppayment.com/bo/disbursement/cash
巴基斯坦（pk）代付订单-巴基斯坦，bankCode 见 地区说明 — 巴基斯坦https://openapi.toppayment.com/sandbox/pk/disbursement/cashhttps://openapi.toppayment.com/pk/disbursement/cash
孟加拉（bd）代付订单-孟加拉，bankCode 见 地区说明 — 孟加拉https://openapi.toppayment.com/sandbox/bd/disbursement/cashhttps://openapi.toppayment.com/bd/disbursement/cash

代付查询

字段与示例见 代付订单查询；请求体需 orderNum 与 platOrderNum 至少其一。

国家/地区沙箱地址生产地址
菲律宾（ph）https://openapi.toppayment.com/sandbox/ph/disbursement/queryhttps://openapi.toppayment.com/ph/disbursement/query
印尼（id）https://openapi.toppayment.com/sandbox/id/disbursement/queryhttps://openapi.toppayment.com/id/disbursement/query
尼日利亚（ng）https://openapi.toppayment.com/sandbox/ng/disbursement/queryhttps://openapi.toppayment.com/ng/disbursement/query
印度（in）https://openapi.toppayment.com/sandbox/in/disbursement/queryhttps://openapi.toppayment.com/in/disbursement/query
泰国（th）https://openapi.toppayment.com/sandbox/th/disbursement/queryhttps://openapi.toppayment.com/th/disbursement/query
越南（vn）https://openapi.toppayment.com/sandbox/vn/disbursement/queryhttps://openapi.toppayment.com/vn/disbursement/query
秘鲁（pe）https://openapi.toppayment.com/sandbox/pe/disbursement/queryhttps://openapi.toppayment.com/pe/disbursement/query
巴西（br）https://openapi.toppayment.com/sandbox/br/disbursement/queryhttps://openapi.toppayment.com/br/disbursement/query
墨西哥（mx）https://openapi.toppayment.com/sandbox/mx/disbursement/queryhttps://openapi.toppayment.com/mx/disbursement/query
哥伦比亚（co）https://openapi.toppayment.com/sandbox/co/disbursement/queryhttps://openapi.toppayment.com/co/disbursement/query
玻利维亚（bo）https://openapi.toppayment.com/sandbox/bo/disbursement/queryhttps://openapi.toppayment.com/bo/disbursement/query
巴基斯坦（pk）https://openapi.toppayment.com/sandbox/pk/disbursement/queryhttps://openapi.toppayment.com/pk/disbursement/query
孟加拉（bd）https://openapi.toppayment.com/sandbox/bd/disbursement/queryhttps://openapi.toppayment.com/bd/disbursement/query

账号校验（印尼）

字段与示例见 账号校验-印尼；同步接口，无回调；仅生产环境。

国家/地区地址
印尼（id）https://openapi.toppayment.com/id/disbursement/bankVerify

余额查询

说明与 currency 见 余额查询；各国家货币代码与地区说明见下表链接。

国家/地区货币沙箱地址生产地址
菲律宾（ph）PHP, 地区说明https://openapi.toppayment.com/sandbox/ph/balance/v1https://openapi.toppayment.com/ph/balance/v1
印尼（id）IDR, 地区说明https://openapi.toppayment.com/sandbox/id/balance/v1https://openapi.toppayment.com/id/balance/v1
尼日利亚（ng）NGN, 地区说明https://openapi.toppayment.com/sandbox/ng/balance/v1https://openapi.toppayment.com/ng/balance/v1
印度（in）INR, 地区说明https://openapi.toppayment.com/sandbox/in/balance/v1https://openapi.toppayment.com/in/balance/v1
泰国（th）THB, 地区说明https://openapi.toppayment.com/sandbox/th/balance/v1https://openapi.toppayment.com/th/balance/v1
越南（vn）VND, 地区说明https://openapi.toppayment.com/sandbox/vn/balance/v1https://openapi.toppayment.com/vn/balance/v1
秘鲁（pe）PEN, 地区说明https://openapi.toppayment.com/sandbox/pe/balance/v1https://openapi.toppayment.com/pe/balance/v1
巴西（br）BRL, 地区说明https://openapi.toppayment.com/sandbox/br/balance/v1https://openapi.toppayment.com/br/balance/v1
墨西哥（mx）MXN, 地区说明https://openapi.toppayment.com/sandbox/mx/balance/v1https://openapi.toppayment.com/mx/balance/v1
哥伦比亚（co）COP, 地区说明https://openapi.toppayment.com/sandbox/co/balance/v1https://openapi.toppayment.com/co/balance/v1
玻利维亚（bo）BOB, 地区说明https://openapi.toppayment.com/sandbox/bo/balance/v1https://openapi.toppayment.com/bo/balance/v1
巴基斯坦（pk）PKR, 地区说明https://openapi.toppayment.com/sandbox/pk/balance/v1https://openapi.toppayment.com/pk/balance/v1
孟加拉（bd）BDT, 地区说明https://openapi.toppayment.com/sandbox/bd/balance/v1https://openapi.toppayment.com/bd/balance/v1

数字货币（Crypto）

数字货币不按国家区分，推荐 Host 使用统一域名 openapi.toppayment.com，路径前缀固定为 /crypto；原域名 global-digit-openapi.toppayment.com 仍可用。请求头必须携带 Nonce。详细字段与示例见 数字货币接入总览。

API 直连路径命名（沙箱与生产不同）

沙箱直连代收为 /crypto/sandbox/pay/directlyPay；生产为 /crypto/pay/orderDirectly。沙箱与生产路径名不同，请求体与响应体一致。

场景沙箱地址生产地址文档
代收下单（收银台）https://openapi.toppayment.com/crypto/sandbox/pay/prePayhttps://openapi.toppayment.com/crypto/pay/prePay数字货币代收
代收下单（API 直连）https://openapi.toppayment.com/crypto/sandbox/pay/directlyPayhttps://openapi.toppayment.com/crypto/pay/orderDirectly数字货币代收
代收查询https://openapi.toppayment.com/crypto/sandbox/pay/queryhttps://openapi.toppayment.com/crypto/pay/query订单查询
代付下单https://openapi.toppayment.com/crypto/sandbox/disbursement/cashhttps://openapi.toppayment.com/crypto/disbursement/cash数字货币代付
代付查询https://openapi.toppayment.com/crypto/sandbox/disbursement/queryhttps://openapi.toppayment.com/crypto/disbursement/query订单查询
余额查询https://openapi.toppayment.com/crypto/sandbox/balance/v1https://openapi.toppayment.com/crypto/balance/v1余额查询

  1. 签名与验签

    • 生成签名：按签名规则文档，Key ASCII 排序，仅拼接非空参数值，用商户私钥 RSA 加密并 Base64。
    • 回调验签：移除回调参数中的 sign，按同样规则拼接，使用平台公钥解密比对。
    • 详见 签名 中的步骤与示例代码。

  2. 回调与联调

    • 回调发送到下单传入的 downNotifyUrl（代收/代付独立）。
    • 沙箱可在后台手动模拟回调（见沙箱文档“回调与状态模拟”）。

对接检查清单

术语说明

  • 代收（Pay-In）：客户向商户付款的收款交易。
  • 代付（Pay-Out）：商户向受益人发起的出款交易。
  • 国家码：URL 路径中使用小写 ISO 码（如 id、ph、ng）。

参考资料

Copyright © 2026 TOPPAY Team