API 文档

重要提示

请妥善保管您的 API Key 和 Secret Key，不要泄露给他人。所有请求都需要进行签名验证。

接口地址

请联系客户经理获取

所有接口均使用 HTTPS 协议，请求/响应数据格式统一使用 JSON。

支付接口

创建代收订单

接口说明：创建一个新的代收订单，支持多种代收渠道和支付方式。

请求方式：POST

接口地址：/v1/collections

请求参数

参数名	类型	必填	说明
merchantOrderNo	string	是	商户订单号，必须唯一
channelCode	string	是	商户通道编码，必须唯一
amount	number	是	代收金额，单位为不同国家所对应货币单位，例如：10VND 20PKR 100IDR 0.5USD 0.05CNY
currency	string	是	货币类型，例如：VND PKR IDR USD CNY
notificationUrl	string	是	异步通知地址
channelParams	object	否	支付通道特有参数，根据不同支付通道有不同的要求
remark	string	否	备注信息

channelParams 参数说明

注意：请根据选择的支付通道提供相应的必要参数不同支付通道的channelParams参数要求：

印度尼西亚
- Dana通道channelParams对象内字段
  
  参数名类型必填说明
  userName string 是 dana支付用户的真实姓名
  - 如果不传channelParams 或者 channelParams为空或者没有传userName参数则返回的payUrl为空值,只能使用平台收银台无法自定义收银台
  - 无论是否传userName参数返回的cashierUrl值是平台收银台地址可向用户展示平台收银台会引导用户完成支付
巴基斯坦
- jz和ep通道channelParams对象内字段
  
  参数名类型必填说明
  channelCode string 是 jz或者ep二选一
  mobileNumber string 是举例03091667191 真实有效的用户手机号码即钱包账号
  - 如果传了channelParams且channelCode和mobileNumber有效返回的payUrl和cashierUrl都为空此时会直接在用户的手机端钱包APP显示一个支付请求用户确认即可支付成功
  - 如果不传channelParams 或者 channelParams为空或者没有传userName和mobileNumber参数或者无效不会直接对用户发起支付请求,返回的cashierUrl值是平台收银台地址可向用户展示平台收银台会引导用户完成支付

参数名	类型	必填	说明
userName	string	是	dana支付用户的真实姓名

参数名	类型	必填	说明
channelCode	string	是	jz或者ep二选一
mobileNumber	string	是	举例03091667191 真实有效的用户手机号码即钱包账号

返回参数

字段名	类型	示例值	说明
`code`	int	200	状态码，200 表示成功
`message`	string	success	状态描述信息
`data`	object	见下方	返回数据主体

`data` 对象字段

字段名	类型	示例值	说明
`amount`	int	1000000	金额
`qrCode`	string/null	null	二维码内容（如果有）
`createTime`	string	2025-06-23T13:21:01.732004298Z	创建时间（ISO8601 格式）
`transactionNo`	string	COLL1750684666668017132	系统交易号
`cashierUrl`	string/null	https://cashier.example.com/cashier/indonesia/?transactionNo=...	收银台跳转地址（如果有）
`currency`	string	IDR	币种（如 IDR 印尼盾）
`payUrl`	string/null	https://link.example.com/minta?full_url=https://qr.example.com/...	付款跳转链接（如果有）
`merchantOrderNo`	string	GX25061317364336334	商户订单号
`status`	string	PENDING	状态（如 `PENDING`）

请求示例

curl -X POST 'https://api.example.com/v1/collections' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your_api_key' \
  -H 'X-API-SIGN: your_signature' \
  -d '{
    "merchantOrderNo": "COL_123456",
    "channelCode": "DAN_530727",
    "amount": 1000000,
    "currency": "IDR",
    "notificationUrl": "https://merchant.example.com/notify",
    "channelParams": {
      "userName": "SUMIATI"
    },
    "remark": "代收测试"
  }'

响应示例

{
    "code": 200,
    "message": "success",
    "data": {
        "amount": 1000000,
        "qrCode": null,
        "createTime": "2025-06-23T13:21:01.732004298Z",
        "transactionNo": "COLL1750684666668017132",
        "cashierUrl": "https://cashier.example.com/cashier/indonesia/?transactionNo=COLL1750684666668017132",
        "currency": "IDR",
        "payUrl": "https://link.example.com/minta?full_url=https://qr.example.com/v1/281012012025023567556",
        "merchantOrderNo": "GX25061317364336334",
        "status": "PENDING"
    }
}

创建代付订单

接口说明：创建一个新的代付订单，支持多种代付渠道。

请求方式：POST

接口地址：/v1/payments

请求参数

参数名	类型	必填	说明
merchantOrderNo	string	是	商户订单号，必须唯一
channelCode	string	是	商户通道编码，必须唯一
amount	number	是	代付金额，单位为不同国家所对应货币单位，例如：10VND 20PKR 100IDR 0.5USD 0.05CNY
currency	string	是	货币类型，例如：VND PKR IDR USD CNY
bankCode	string	否	收款银行、支付机构编码有支付通道特有参数的时候不必填
accountName	string	否	收款人姓名有支付通道特有参数的时候不必填
accountNo	string	否	收款账号有支付通道特有参数的时候不必填
notificationUrl	string	是	异步通知地址
channelParams	object	否	支付通道特有参数
remark	string	否	备注信息

channelParams 参数说明

注意：请根据选择的支付通道提供相应的必要参数不同支付通道的channelParams参数要求：

巴基斯坦
- jz和ep通道channelParams对象内字段
  
  参数名类型必填说明
  channelCode string 是 jz或者ep二选一
  mobileNumber string 是举例03091667191 真实有效的用户手机号码即钱包账号
  - bankCode accountName accountNo参数不必填

参数名	类型	必填	说明
channelCode	string	是	jz或者ep二选一
mobileNumber	string	是	举例03091667191 真实有效的用户手机号码即钱包账号

请求示例

curl -X POST 'https://api.example.com/v1/payments' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your_api_key' \
  -H 'X-API-SIGN: your_signature' \
  -d '{
    "merchantOrderNo": "PAY_123456",
    "amount": 1000000,
    "currency": "VND",
    "channelCode": "CH001",
    "bankCode": "VCB",
    "accountName": "NGUYEN VAN A",
    "accountNo": "1234567890",
    "notificationUrl": "https://merchant.example.com/notify",
    "remark": "代付测试"
  }'

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "transactionNo": "PAY_123456789",
    "merchantOrderNo": "PAY_123456",
    "channelCode": "CH001",
    "amount": 1000000,
    "currency": "VND",
    "status": "PROCESSING",
    "payTime": "2024-01-15T10:25:00Z"
  }
}

查询接口

订单查询

接口说明：查询订单状态和详情，支持查询代收和代付订单。

请求方式：GET

接口地址：/v1/orders/{merchantOrderNo}

请求参数

参数名	类型	必填	说明
merchantOrderNo	string	是	平台订单号

请求示例

curl -X GET 'https://api.example.com/v1/orders/ORDER_123456789' \
  -H 'X-API-KEY: your_api_key' \
  -H 'X-API-SIGN: your_signature'

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "transactionNo": "ORDER_123456789",
    "merchantOrderNo": "ORDER_123456",
    "orderType": "COLLECTION",
    "amount": 1000000,
    "currency": "VND",
    "status": "SUCCESS"
  }
}

状态说明

状态	说明
PENDING	待支付，订单已创建但未收到支付
PROCESSING	处理中，已收到支付请求，正在处理
SUCCESS	支付成功，订单已完成
FAILED	支付失败，可能是余额不足或其他原因
EXPIRED	订单已过期，超过支付时间未完成支付
CANCELLED	订单已取消，可能是用户取消或管理员取消

余额查询

接口说明：查询商户账户余额。

请求方式：GET

接口地址：/v1/balance

请求参数

参数名	类型	必填	说明
currency	string	否	货币类型，例如：VND PKR IDR USD CNY。不传则返回所有货币类型的余额

请求示例

curl -X GET 'https://api.example.com/v1/balance?currency=VND' \
  -H 'X-API-KEY: your_api_key' \
  -H 'X-API-SIGN: your_signature'

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "IDR":{
      "available":2958.00,
      "frozen":0,
      "settling":0
    }
  }
}

退款接口

创建退款订单

接口说明：创建新的退款订单。

请求方式：POST

接口地址：/v1/refunds

请求参数

参数名	类型	必填	说明
merchantRefundId	string	是	商户退款单号，必须唯一
transactionNo	string	是	原订单号
amount	number	是	退款金额，单位为不同国家所对应货币单位，例如：10VND 20PKR 100IDR 0.5USD 0.05CNY
reason	string	否	退款原因

请求示例

curl -X POST 'https://api.example.com/v1/refunds' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your_api_key' \
  -H 'X-API-SIGN: your_signature' \
  -d '{
    "merchantRefundId": "REF_123456",
    "transactionNo": "ORDER_123456789",
    "amount": 1000000,
    "reason": "客户退款"
  }'

响应示例

{
  "code": 503,
  "message": "不支持此功能",
  "data": {}
}

通知接口

异步通知

当订单状态发生变化时，系统会向商户配置的通知地址发送异步通知。

通知参数

参数名	类型	必填	说明
transactionNo	string	是	平台订单号
merchantOrderNo	string	是	商户订单号
amount	number	是	订单金额，单位为不同国家所对应货币单位，例如：10VND 20PKR 100IDR 0.5USD 0.05CNY
currency	string	是	货币类型
status	string	是	订单状态: SUCCESS

通知示例

通知请求头中包含 'X-Signature: signature' 请用自己的Secret Key解密验证

{
  "transactionNo": "ORDER_123456789",
  "merchantOrderNo": "ORDER_123456",
  "amount": 1000000,
  "currency": "VND",
  "status": "SUCCESS"
}

通知应答

商户接收到通知后，需要返回小写字符串 "success"，否则系统会重复发送通知。

错误码说明

错误码	说明	解决方案
1001	签名验证失败	检查签名算法和参数是否正确
1002	API Key 无效	确认 API Key 是否正确且在有效期内
1003	请求参数错误	检查必填参数是否完整，参数格式是否正确
1004	余额不足	请确保账户有足够的余额
1005	订单号重复	更换订单号重新发起请求

签名验证

所有请求都需要进行签名验证，签名算法支持 HMAC-SHA256 和 MD5。详细说明请参考签名示例。

重要提示​

接口地址​

支付接口​

创建代收订单​

请求参数​

channelParams 参数说明​

印度尼西亚​

巴基斯坦​

返回参数​

data 对象字段​

请求示例​

响应示例​

创建代付订单​

请求参数​

channelParams 参数说明​

巴基斯坦​

请求示例​

响应示例​

查询接口​

订单查询​

请求参数​

请求示例​

响应示例​

状态说明​

余额查询​

请求参数​

请求示例​

响应示例​

退款接口​

创建退款订单​

请求参数​

请求示例​

响应示例​

通知接口​

异步通知​

通知参数​

通知示例​

通知应答​

错误码说明​

签名验证​

重要提示

接口地址

支付接口

创建代收订单

请求参数

channelParams 参数说明

印度尼西亚

巴基斯坦

返回参数

`data` 对象字段

请求示例

响应示例

创建代付订单

请求参数

channelParams 参数说明

巴基斯坦

请求示例

响应示例

查询接口

订单查询

请求参数

请求示例

响应示例

状态说明

余额查询

请求参数

请求示例

响应示例

退款接口

创建退款订单

请求参数

请求示例

响应示例

通知接口

异步通知

通知参数

通知示例

通知应答

错误码说明

签名验证