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 参数说明

不同支付通道的参数要求：

DigiMone：{channelCode: "jazzcash|easypaisa"} 二选一
Dana：{userName: "SUMIATI"} dana用户的真实姓名
Essa: {"channelCode": "jz|ep","mobileNumber": "03091667191"} channelCode二选一 mobileNumber需要真实有效的手机号码即用户的账号

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

请求示例

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": "CH001",
    "amount": 1000000,
    "currency": "VND",
    "notificationUrl": "https://merchant.example.com/notify",
    "channelParams": {
      "channelCode": "jazzcash"
    },
    "remark": "代收测试"
  }'

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "transactionNo": "COL_123456789",
    "merchantOrderNo": "COL_123456",
    "amount": 1000000,
    "currency": "VND",
    "status": "PENDING",
    "expireTime": "2024-01-15T10:30:00Z",
    "payUrl": "https://api.example.com/checkout/COL_123456789"
  }
}

创建代付订单

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

请求方式：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	否	备注信息

请求示例

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-API-SIGN: 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 参数说明​

请求示例​

响应示例​

创建代付订单​

请求参数​

请求示例​

响应示例​

查询接口​

订单查询​

请求参数​

请求示例​

响应示例​

状态说明​

余额查询​

请求参数​

请求示例​

响应示例​

退款接口​

创建退款订单​

请求参数​

请求示例​

响应示例​

通知接口​

异步通知​

通知参数​

通知示例​

通知应答​

错误码说明​

签名验证​

重要提示

接口地址

支付接口

创建代收订单

请求参数

channelParams 参数说明

请求示例

响应示例

创建代付订单

请求参数

请求示例

响应示例

查询接口

订单查询

请求参数

请求示例

响应示例

状态说明

余额查询

请求参数

请求示例

响应示例

退款接口

创建退款订单

请求参数

请求示例

响应示例

通知接口

异步通知

通知参数

通知示例

通知应答

错误码说明

签名验证