NAV
代码示例

Payroad跨境支付API文档

1. 概述

1.1 编写目的

目的是约定商户与Payroad付款系统间的业务接口。包括通讯协议、交易接口规范、文件格式、加密和摘要规范。指 导商户开发人员依据本规范开发，并与Payroad付款系统对接。

1.2 定义和缩略语

UML时序图

UML时序图

1.3 平台测试/上线准备事项

测试联调阶段

平台开发完成进行系统联调测试前，需要准备如下事项：
1. 平台生成测试环境的RSA密钥对，并将公钥发提供给Payroad；
2. 申请开通测试环境平台号；

上线阶段

  1. 平台生成生产环境的RSA密钥对，并将公钥提供给Payroad；
  2. 向Payroad提供平台服务器IP地址
  3. 申请开通生产环境平台号

2. 通讯协议

2.1 协议约定

  1. 平台与Payroad之间基于HTTPS1.2协议通讯，报文组织形式采用 json 规范。
  2. 双方的报文都密文形式发送，必须同时将报文的密文、会话密钥密文和签名传输给对方。
  3. 平台和Payroad双方互为客户端和服务端。根据应用的要求，可以由平台作为客户端主动发起交易请求，Payroad 来做应答。也可以由Payroad主动发起交易请求，平台来做应答，平台在开户时需提前设置接收Payroad的请求地址。
  4. 客户端提交请求使用POST表单方式 (Content-Type:application/json) 提交，内容采用UTF-8编码。
  5. 请求和响应均由五个域：merchantNo=平台代码、jsonEnc=报文密文、keyEnc=会话密钥密文、sign=报文签名

3 交易接口规范

3.1 请求报文

交易报文遵循JSON规范。示例:

{
    "head":{
        "version":"1.0.1",          //--报文版本号
        "tradeType":"00",           //--00请求报文
        "tradeTime":"1551341750",   //--请求时间，10位unix时间戳
        "tradeCode":"pr1001",       //–请求交易代码
        "language":"cn",            //–语言
    },
    "body":{
        //…
    }
}
  1. 请求报文由两部分组成：请求报文头和请求报文体。其中请求报文头信息在报文头（head. 节点内，请求报文体信息 在报文体（body. 节点内。
  2. 报文头是每个交易都相同的。请求报文头信息的填写标准请参看“公共报文头说明”章节。
  3. 报文体根据每个交易的接口定义而各不相同。请求报文体的定义请参看“业务交易接口”章节。需按照每个交易的接 口定义组装和解析请求报文体。
  4. 客户端请求报文上送时，POST提交四个参数：merchantNo=平台代码;jsonEnc=报文密文；keyEnc=会话密钥密 文；sign=报文签名，其中merchantNo为Payroad为合作平台分配的商户号明文，jsonEnc参数的内容就是整个报文加 密以后的十六进制字符串，keyEnc参数为报文加密会话密钥的密文，sign参数的内容是本次报文的签名。

服务器端收到请求后按照HTTPS的方式获取参数后，按如下步骤处理：
步骤1：使用解密会话密钥
步骤2：对密文报文解密，得到报文明文；
步骤3：验证签名，签名通过后在解析报文内容。

报文加密、签名和校验方式请参看“加密及签名规范”章节

3.2 响应报文

交易报文遵循JSON规范。示例:

{
    "head":{
        "version":"1.0.0",          //--报文版本号
        "tradeType":"01",           //--01响应报文
        "tradeTime":"1551341750",   //--响应时间，10位unix时间戳
        "tradeCode":"pr1001",       //--对应请求的交易代码
        "respCode":"S00000",        //--请求返回码
        "respDesc":"请求成功"        //--请求返回码
    },
    "body":{
        //…
    }
}
  1. 交易应答报文由两部分组成：应答报文头和应答报文体。其中应答报文头信息在报文头（head）节点内，应答报文体 信息在报文体（body）节点内。
  2. 报文头是每个交易都相同的。应答报文头信息的填写标准请参看"公共报文头说明”章节。
  3. 报文体根据每个交易的接口定义而各不相同。应答报文体的定义请参看"交易报文接口”章节。需按照每个交易的接口 定义组装和解析应答报文体。
  4. 交易成功时的应答报文，报文头的respCode为S00000，respDesc为"交易成功”,此时报文体（body）节点根据 实际业务需要为空也可以不为空。
  5. 交易错误时的应答报文，错误码和错误信息填写在报文头的respCode（返回码）和respDesc（返回信息描述）域 中；报文体（body）节点为空。
  6. 服务器端响应报文返回时，将商户号、报文密文、会话密钥和签名以标准json字符串返回 {"merchantNo”:"",jsonEnc":"","keyEnc":"","sign":""}，然后将字符串的字节流写入http的返回对象。客户端收到服务器端的响应时将HTTP服务方返回的字节流按照相应格式的字符串进行报文和摘要参数的获取，参数获 取后，先要进行摘要校验，校验通过后在解析报文内容。

报文摘要生成和校验方式请参看"加密及签名规范”章节。

4 加密及签名规范

4.1 原则

  1. 交易报文传输都需要进行加密、签名和校验。
  2. 无论是请求端还是响应端接收到报文后，都需要进行签名验证，即按照约定算法重新生成签名，然后和收到的签名进 行对比，对比通过后才能进行报文内容的解析，否则报文或文件内容可能出现篡改、部分丢失、伪造的问题。
  3. 报文加密算法：DES/CBC/PKCS5Padding
  4. 会话密钥生成：KeyGenerator生成
  5. 会话密钥加密算法：RSA/ECB/PKCS1Padding
  6. 签名算法：SHA1withRSA

4.2 RSA密钥对获得

openssl genrsa –out rsa_private_key_2048.pem2048 
#生成rsa私钥，以X509编码，指定生成的密钥的位数:2048

openssl pkcs8 –topk8 –in rsa_private_key_2048.pem –out pkcs8_rsa_private_key_2048.pem –nocrypt
#将上一步生成的rsa私钥转换成PKCS#8编码

openssl rsa –in rsa_private_key_2048.pem –out rsa_public_key_2048.pem –pubout
#导出rsa公钥，以X509编码商户需要按上面步骤生成商户的公钥pem发给Payroad，
#或商户直接可以向Payroad索要密钥对的生成脚本，生成商户所需的公私钥。
#Payroad也需要把Payroad生成的对应的公钥pem发给商户。

对于商户来说，需要生成商户自己的RSA密钥对（包含公钥和私钥），其中，私钥合作方自己保留，同时公钥提供给Payroad。

对于Payroad来说，需要为每个商户生成对应的公私钥对。其中，私钥Payroad自己保留，公钥需要提供给商户。

4.3 报文加密及签名

加密及签名

  1. 对请求或响应Json报文明文（UTF-8编码. 使用发送方的私钥进行签名（SHA1withRSA. ，并将签名结果转换为HEX字符串，得到sign域。
  2. 使用KeyGenerator生成器，生成DES加密会话密钥SK；
  3. 使用SK对Json明文进行加密（DES/CBC/PKCS5Padding. ，并将加密结果转换为HEX字符串，得到jsonEnc 域。
  4. 使用接收方公钥对会话密钥SK加密（RSA/ECB/PKCS1Padding. ，并将结果转换为HEX字符串，得到keyEnc 域。

4.4 报文解密及验签

解密及验签

  1. 将keyEnc域转换为二进制byte数组，使用接收方放的私钥对会话密钥，得到明文SK；
  2. 将jsonEnc与转换为二进制byte数组，使用上一步得到的会话密钥SK解密，得到明文json；
  3. 使用上一步解密得到的明文、发送方公钥和sign域数据验证签名的有效性。

5 业务接口

本章节描述商户接入Payroad相关业务接口。
M表示必输字段，O表示可选字段

5.1 收款

5.1.1 查询收款账户

1 功能描述
交易代码 pr3020
功能名称 查询收款账户
功能描述 查询收款账户
调用方式 实时接口
调用流程 --
应用场景 查询收款账户

2 请求地址

Url： https://{baseUrl}/api/pr3020

Method： POST

请求示例:

{
    "accountCategory":"FIAT",
    "currency":"USD"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
账户类别 accountCategory String(10) M CRYPTO-数字货币 FIAT-法币
收款币种 currency String(10) M 要查询的单个币种 如法币传USD，数字货币传USDT
链上地址 cryptoAddress String(255) O 查询某个特定地址的数字货币账户时传入
法币银行账号 bankAccountNumber String(50) O 查询某个特定银行账号的法币货币账户时传入

返回示例:

{
  "list": [{
    "accountNo": "CN00000700",
    "accountCategory": "FIAT",
    "cryptoAddress": null,
    "fiatAccount": {
      "network": "SWIFT",
      "bankName": "招商",
      "bankAccountNumber": "123456",
      "accountHolderName": "张三",
      "bic": "1212",
      "fiatCurrency": "USD",
      "bankCity": "HK",
      "bankCountry": "HK",
      "bankAddress": "九龙"
    },
    "accountStatus": "ACTIVE"
  },
    {
      "accountNo": "CN00001500",
      "accountCategory": "FIAT",
      "cryptoAddress": null,
      "fiatAccount": {
        "network": "SWIFT",
        "bankName": "12312",
        "bankAccountNumber": "12312",
        "accountHolderName": "12312",
        "bic": "111",
        "fiatCurrency": "USD",
        "bankCity": "12",
        "bankCountry": "12",
        "bankAddress": "1231"
      },
      "accountStatus": "ACTIVE"
    }]
}

4 响应字段

名称 Json标签 类型 属性 取值说明
返回集合 list List<ReceiveAccountInfo> M

ReceiveAccountInfo 的字段

名称 Json标签 类型 属性 取值说明
账户编号 accountNo string(64) M
账户分类 accountCategory string(10) M
账户状态 accountStatus string(10) M ACTIVE-激活 INACTIVE-禁用 PENDING-开通中
加密货币账号 cryptoAddress CryptoAddress O 加密货币账号信息
法币账号 fiatAccount FiatAccount O 法币账号信息

CryptoAddress 的字段

名称 Json标签 类型 属性 取值说明
网络 network string(30) O ERC20 SPL Tron
加密货币地址 address string(255) O
支持币种 supportCurrency string(100) O

FiatAccount 的字段

名称 Json标签 类型 属性 取值说明
网络类型 network string(10) M SWIFT SEPA ACH
银行名称 bankName string(100) M
账户号码 bankAccountNumber string(50) M
账户持有人 accountHolderName string(100) M
bic/swift码 bic string(20) M
账户币种 fiatCurrency string(10) M
所在城市 bankCity string(128) O
所在国家 bankCountry string(2) M
具体地址 bankAddress string(512) M

5.1.2 添加汇款人

1 功能描述
交易代码 pr1021
功能名称 添加收款账户(此接口暂时只支持法币)
功能描述 添加收款账户
调用方式 实时接口
调用流程 --
应用场景 添加收款账户

2 请求地址

Url： https://{baseUrl}/api/pr1021

Method： POST

请求示例:

{
  "accountNo": "CN00000700",
  "fiatAccount": {
    "network": "SWIFT",
    "bankName": "招商",
    "bankAccountNumber": "123456",
    "accountHolderName": "张三",
    "bic": "1212",
    "fiatCurrency": "USD",
    "bankCity": "HK",
    "bankCountry": "HK",
    "bankAddress": "九龙"
  }
}

3 请求字段

名称 Json标签 类型 属性 取值说明
账户id channelNo String(64) M 收款账户查询接口返回的参数
法币账户 fiatAccount FiatAccount M

FiatAccount 的字段

名称 Json标签 类型 属性 取值说明
网络 network string(10) M SWIFT SEPA ACH
银行名称 bankName string(100) M
账户号码 bankAccountNumber string(50) M
账户持有人 accountHolderName string(100) M
bic/swift码 bic string(20) M
账户币种 fiatCurrency string(10) M
所在城市 bankCity string(128) O
所在国家 bankCountry string(2) O
具体地址 bankAddress string(512) O

返回示例:

{
  "accountNo": "CN00000700",
  "fiatAccount": {
    "network": "SWIFT",
    "bankName": "招商",
    "bankAccountNumber": "123456",
    "accountHolderName": "张三",
    "bic": "1212",
    "fiatCurrency": "USD",
    "bankCity": "HK",
    "bankCountry": "HK",
    "bankAddress": "九龙"
  }
}

4 响应字段

名称 Json标签 类型 属性 取值说明
渠道号 channelNo String(64) M 收款账户查询接口返回的参数
法币账户 fiatAccount FiatAccount M

FiatAccount 的字段

名称 Json标签 类型 属性 取值说明
网络 network string(10) M SWIFT SEPA ACH
银行名称 bankName string(100) M
账户号码 bankAccountNumber string(50) M
账户持有人 accountHolderName string(100) M
bic/swift码 bic string(20) M
账户币种 fiatCurrency string(10) M
所在城市 bankCity string(128) O
所在国家 bankCountry string(2) O
具体地址 bankAddress string(512) O

5.2 换汇

5.2.1 交易查询

1 功能描述
交易代码 pr3019
功能名称 交易查询
功能描述 查询某交易单号或者某商户某时间段的所有交易单号
调用方式 实时接口
调用流程 --
应用场景 在进行FX牌价查询前，需要先查询此接口获取交易单号

2 请求地址

Url： https://{baseUrl}/api/pr3019

Method： POST

请求示例:

{
    "pageNum": 1,
    "pageSize": 10,
    "transactionNo":"156165641688"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
第几页 pageNo Integer O 查询第几页
每页多少条 pageSize Integer O 每页多少条，每页最多支持100条
查询起始时间 beginDate Long O Unix13位时间戳，查询开始时间，闭区间
查询结束时间 endDate Long O Unix13位时间戳，查询结束时间，闭区间
交易单号 transactionNo String(32) O 指定交易单号

返回示例:

{
  "pageNo": 1,
  "pageSize": 10,
  "totalRecord": 7,
  "totalPage": 1,
  "results": [
    {
      "transactionNo": "PT01",
      "payCurrency": "USD",
      "payAmount": 2,
      "paymentType": "FIAT_PAYIN",
      "exrateStatus": "P"
    },
    {
      "transactionNo": "PT00001100",
      "payCurrency": "USD",
      "payAmount": 100,
      "paymentType": "FIAT_PAYIN",
      "exrateStatus": "N"
    },
    {
      "transactionNo": "PT00000902",
      "payCurrency": "USD",
      "payAmount": 102,
      "paymentType": "FIAT_PAYIN",
      "exrateStatus": "N"
    },
    {
      "transactionNo": "PT00000500",
      "payCurrency": "USD",
      "payAmount": 2,
      "paymentType": "FIAT_PAYIN",
      "exrateStatus": "Y"
    },
    {
      "transactionNo": "PT00001200",
      "payCurrency": "USD",
      "payAmount": 1000,
      "paymentType": "FIAT_PAYIN",
      "exrateStatus": "N"
    },
    {
      "transactionNo": "PT00001400",
      "payCurrency": "USD",
      "payAmount": 1222,
      "paymentType": "FIAT_PAYIN",
      "exrateStatus": "N"
    },
    {
      "transactionNo": "PT00001101",
      "payCurrency": "USD",
      "payAmount": 222,
      "paymentType": "FIAT_PAYIN",
      "exrateStatus": "N"
    }
  ]
}

4 响应字段

名称 Json标签 类型 属性 取值说明
当前页码 pageNum Integer M
页显示数 pageSize Integer M
总条数 totalRecord Integer M
总页数 totalPage Integer M
交易信息集合 list List<QueryTransactionNoRes> M

QueryTransactionNoRes 的字段

名称 Json标签 类型 属性 取值说明
交易单号 transactionNo string(32) M 下方查询牌价时传入得参数
支付币种 payCurrency string(10) M
支付金额 payAmount decimal(28,10) M
支付类型 paymentType string(32) M 法币收入-FIAT_PAYIN
是否换汇 exrateStatus string(1) M N-未换汇 P-待换汇 Y-已换汇

5.2.2 牌价查询

1 功能描述
交易代码 pr1002
功能名称 牌价查询
功能描述 查询某币种的FX牌价
调用方式 实时接口
调用流程 --
应用场景 在进行FX交易前，需要先询价

2 请求地址

Url： https://{baseUrl}/api/pr1002

Method： POST

请求示例:

{
    "merOrderNo":"1734276289293",
    "buyCurrency":"USDT",
    "transactionNo":"PT00000902"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
商户订单号 merOrderNo String(32) M 商户自定义的唯一订单号
交易单号 transactionNo String(32) O 5.1.1接口中返回的参数
买入币种 buyCurrency String(10) M 买入币种

返回示例:

{
    "sellCurrency":"USD",
    "buyCurrency":"USDT",
    "rate":"0.9988",
    "sellAmount":"1000.000000",
    "buyAmount":"998.800000",
    "quoteId": 7843892398239,
    "expireTime": 1576560599598,
    "merOrderNo":"32894398349",
    "feeAmount": "2.000000",
    "feeCurrency":"USDT"
}

4 响应字段

名称 Json标签 类型 属性 取值说明
卖出币种 sellCurrency String(10) M 卖出币种
买入币种 buyCurrency String(10) M 买入币种
汇率 rate String(18) M 汇率报价
卖出金额 sellAmount String(18) M 卖出金额
买入金额 buyAmount String(20) M 买入金额
报价ID quoteId Long M 报价ID
报价有效期 expireTime Long M unix时间戳，此次询价的有效时间。如若过了有效时间，此次询价作废
商户订单号 merOrderNo String(32) M 商户传入的订单号
手续费 feeAmount String(18) O 手续费
手续费币种 feeCurrency String(10) O 手续费币种

5.2.3 FX交易

1 功能描述
交易代码 pr1003
功能名称 FX交易
功能描述 根据询价后的牌价，发起FX交易
调用方式 实时接口
调用流程 在发起牌价查询接口后，根据所得到的quoteId，发起相应的FX交易
应用场景 --

2 请求地址

Url： https://{baseUrl}/api/pr1003

Method： POST

请求示例:

{
    "quoteId": 7843892398239,
    "callbackUrl":"https://xxxx.xxxx.xxxx/xxxx/xxxx",
    "transactionNo":"PT00000902"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
报价ID quoteId Long M 报价ID
回调url callbackUrl String(256) M 回调通知Url
交易单号 transactionNo String(32) O 5.1.1接口中返回的参数

返回示例:

{
    "sellCurrency":"USD",
    "buyCurrency":"CNY",
    "rate":"7.0102",
    "sellAmount":"1000.00",
    "buyAmount":"7010.20",
    "quoteId": 7843892398239,
    "expireTime": 1576560599598,
    "merOrderNo":"32894398349"
}

4 响应字段

名称 Json标签 类型 属性 取值说明
卖出币种 sellCurrency String(10) M 卖出币种
买入币种 buyCurrency String(10) M 买入币种
汇率 rate String(18) M 汇率报价
卖出金额 sellAmount String(18) M 卖出金额
买入金额 buyAmount String(20) M 买入金额
报价ID quoteId Long M 报价ID
结果码 code String M Fx交易结果码
结果描述 message String M 交易结果描述
交易流水号 bizFlow String(32) M 对应Fx交易的唯一流水号
手续费金额 feeAmount String(18) O 手续费金额
手续费币种 feeCurrency String(10) O 手续费币种

5.2.4 换汇历史交易查询

1 功能描述

交易代码 pr3003
功能名称 换汇历史交易查询
功能描述 换汇历史交易查询
调用方式 实时接口
调用流程 --
应用场景 查询以往的换汇历史交易

2 请求地址

Url： https://{baseUrl}/api/pr3003

Method： POST

3 请求字段

名称 Json标签 类型 属性 取值说明
查询起始时间 startTime Long O Unix13位时间戳，查询开始时间，闭区间
查询结束时间 endTime Long O Unxi13位时间戳，查询结束时间，闭区间
报价ID quoteId Long O 报价ID

说明： 若startTime与endTime没填，则quoteId为必填。若quoteId没填，则startTime与endTime为必填，且间隔不能超过24小时。

返回示例:

[
    {
        "sellCurrency":"USD",
        "buyCurrency":"CNY",
        "rate":"7.0102",
        "sellAmount":"1000.00",
        "buyAmount":"7010.20",
        "quoteId": 7843892398239,
        "code": "AR0021",
        "message":"not enough balance",
        "bizFlow":"983788743"
    },
    {
        "sellCurrency":"USD",
        "buyCurrency":"CNY",
        "rate":"7.0102",
        "sellAmount":"1000.00",
        "buyAmount":"7010.20",
        "quoteId": 7843892398240,
        "code": "S00000",
        "message":"success",
        "bizFlow":"983788743"
    }
]

4 响应字段

接口返回对象为: List<ExchangeHistory>

ExchangeHistory 字段：

名称 Json标签 类型 属性 取值说明
卖出币种 sellCurrency String(10) M 卖出币种
买入币种 buyCurrency String(10) M 买入币种
汇率 rate String(18) M 汇率报价
卖出金额 sellAmount String(20) M 卖出金额
买入金额 buyAmount String(20) M 买入金额
报价ID quoteId Int M 报价ID
结果码 code String M Fx交易结果码
结果描述 message String M 交易结果描述
业务流水号 bizFlow String(32) M 对应唯一业务流水号

5.2.5 FX交易结果通知

1 功能描述
交易代码 pr2002
功能名称 FX交易结果通知
功能描述 Fx的交易结果异步通知
调用方式 通知接口
调用流程 --
应用场景 5.4.2 Fx交易发起成功且交易处理完毕后，
将根据5.4.2 Fx交易参数内的回调Url进行回调通知最终结果。

2 请求地址

Url： 5.4.2 Fx交易中的 callbackUrl

Method： POST

请求示例:

 {
    "sellCurrency":"USD",
    "buyCurrency":"CNY",
    "rate":"7.0102",
    "sellAmount":"1000.00",
    "buyAmount":"7010.20",
    "quoteId": 7843892398239,
    "code": "AR0021",
    "message":"not enough balance",
    "bizFlow":"983788743"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
卖出币种 sellCurrency String(10) M 卖出币种
买入币种 buyCurrency String(10) M 买入币种
汇率 rate String(18) M 汇率报价
卖出金额 sellAmount String(20) M 卖出金额
买入金额 buyAmount String(20) M 买入金额
报价ID quoteId Long M 报价ID
结果码 code String M Fx交易结果码
结果描述 message String M 交易结果描述
业务流水号 bizFlow String(32) M 业务流水号

5.2.6 查询支持换汇币种对

1 功能描述

交易代码 pr3002
功能名称 查询换汇支持币种对
功能描述 查询换汇支持币种对，可在当前支持的币种内进行FX交易
调用方式 实时接口
调用流程 --
应用场景 需要查询目前已支持的FX币种

2 请求地址

Url： https://{baseUrl}/api/pr3002

Method： POST

3 请求字段

无

4 响应字段

接口返回对象为: List<CurrencyPair>

CurrencyPair字段：

名称 Json标签 类型 属性 取值说明
卖出币种 sellCurrency String(10) M 卖出币种
买入币种 buyCurrency String(10) M 买入币种

5.3 付款

5.3.1 增加付款人

1 功能描述
交易代码 pr4001
功能名称 增加付款人
功能描述 增加付款人用于创建付款订单
调用方式 实时接口
调用流程 --
应用场景 增加付款人

2 请求地址

Url： https://{baseUrl}/api/pr4001

Method： POST

请求示例:

{
  "relationshipType": "THIRD_PARTY",
  "accountType": "CRYPTO",
  "thirdPartParam": {
    "beneficiaryType": "INDIVIDUAL",
    "phone": "13800138000",
    "email": "beneficiary@example.com",
    "companyParam": {
      "legalName": "",
      "registrationNumber": "",
      "businessLicenseNo": "",
      "address": "",
      "countryCode": ""
    },
    "personalParam": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-05-15",
      "idCardNo": "ID123456789012",
      "passportNo": "",
      "countryCode": "CN"
    }
  },
  "cryptoParam": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "memo": "MEMO123456",
    "network": "TRC20",
    "currency": "USDT"
  },
  "fiatParam": {
    "bankAccountNumber": "",
    "bankAccountHolder": "",
    "bankName": "",
    "bic": "",
    "bankCurrency": "",
    "bankCountryCode": "",
    "bankCity": "",
    "bankAddress": "",
    "referenceMessage": ""
  }
}

3 请求字段

名称 Json标签 类型 属性 取值说明
账户类型 accountType String(6) M CRYPTO-数字货币 FIAT-法币
关系类型 relationshipType String(15) M SELF_OWNED-自有 THIRD_PARTY-第三方
第三方信息 thirdPartParam ThirdPartParam M 关系类型为THIRD_PARTY时填写
数字货币账户信息 cryptoParam CryptoParam M 账户类型为CRYPTO时填写
法币账户信息 fiatParam FiatParam M 账户类型为FIAT时填写

ThirdPartParam字段：

名称 Json标签 类型 属性 取值说明
付款人类型 beneficiaryType String(15) C 关系类型为第三方时必填 INDIVIDUAL-个人 COMPANY-公司
电话 phone String(32) C 关系类型为第三方时必填
邮箱 email String(128) C 关系类型为第三方时必填
公司信息 companyParam CompanyParam C 付款人类型为COMPANY时填写
个人信息 personalParam PersonalParam C 付款人类型为INDIVIDUAL时填写

CompanyParam字段：

名称 Json标签 类型 属性 取值说明
公司名称 legalName String(255) C 关系类型为第三方且付款人为公司时必填（到address字段）
国家 countryCode String(2) C 关系类型为第三方时必填 国家二字码 如：CN US
公司注册号 registrationNumber String(255) C 国家为非CN时填写
营业执照号 businessLicenseNo String(255) C 国家为CN时填写
公司地址 address String(512) C

PersonalParam字段：

名称 Json标签 类型 属性 取值说明
名 firstName String(255) C 关系类型为第三方且付款人为个人时必填（到passportNo字段）
姓 lastName String(255) C
出生日期 dateOfBirth String(15) C 格式 yyyy-mm-dd
国家 countryCode String(2) C 关系类型为第三方时必填 国家二字码 如：CN US
身份证号 idCardNo String(255) C 国家为CN时填写
护照号 passportNo String(255) C 国家为非CN时填写

CryptoParam字段：

名称 Json标签 类型 属性 取值说明
加密货币地址 address String(512) C 账户类型为数字货币时填写
区块链网络 network String(32) C 区块链网络 TRC20, ERC20, SPL
加密货币币种 currency String(32) C 加密货币币种 暂只支持 USDC USDT
加密货币备注 memo String(255) O 加密货币备注

FiatParam字段：

名称 Json标签 类型 属性 取值说明
银行账号 bankAccountNumber String(255) C 账户类型为法币时填写
账户持有人姓名 bankAccountHolder String(255) C
BIC/SWIFT代码 bic String(32) C
银行账户币种 bankCurrency String(8) C 法币币种如USD EUR CNY
银行所在国家 bankCountryCode String(2) C 国家二字码 如：CN US
银行所在城市 bankCity String(255) C
银地址 bankAddress String(512) C

返回示例:

{
  "merchantNo": "MERCHANT20260324001",
  "beneficiaryNo": "11476040318471700003",
  "beneficiaryName": "John Doe",
  "relationshipType": "THIRD_PARTY",
  "accountType": "CRYPTO",
  "thirdPartParam": {
    "beneficiaryType": "INDIVIDUAL",
    "phone": "13800138000",
    "email": "beneficiary@example.com",
    "companyParam": {
      "legalName": "",
      "registrationNumber": "",
      "businessLicenseNo": "",
      "address": "",
      "countryCode": ""
    },
    "personalParam": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-05-15",
      "idCardNo": "ID123456789012",
      "passportNo": "PASS1234567",
      "countryCode": "CN"
    }
  },
  "cryptoParam": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "memo": "MEMO123456",
    "network": "TRC20",
    "currency": "USDT"
  },
  "fiatParam": {
    "bankAccountNumber": "",
    "bankAccountHolder": "",
    "bankName": "",
    "bic": "",
    "bankCurrency": "",
    "bankCountryCode": "",
    "bankCity": "",
    "bankAddress": "",
    "referenceMessage": ""
  }
}

4 响应字段

名称 Json标签 类型 属性 取值说明
账户类型 accountType String(6) M CRYPTO-数字货币 FIAT-法币
关系类型 relationshipType String(15) M SELF_OWNED-自有 THIRD_PARTY-第三方
第三方信息 thirdPartParam ThirdPartParam C 关系类型为THIRD_PARTY时填写
数字货币账户信息 cryptoParam CryptoParam C 账户类型为CRYPTO时填写
法币账户信息 fiatParam FiatParam C 账户类型为FIAT时填写

ThirdPartParam字段：

名称 Json标签 类型 属性 取值说明
商户号 merchantNo String(64) M 系统分配给商户的唯一编号
付款人编号 beneficiaryNo String(64) M 该付款人的编号，手续付款时需要传入
付款人名称 beneficiaryName String(100) M 付款人名称
付款人类型 beneficiaryType String(15) C 关系类型为第三方时必填 INDIVIDUAL-个人 COMPANY-公司
电话 phone String(32) C 关系类型为第三方时必填
邮箱 email String(128) C 关系类型为第三方时必填
公司信息 companyParam CompanyParam C 付款人类型为COMPANY时填写
个人信息 personalParam PersonalParam C 付款人类型为INDIVIDUAL时填写

CompanyParam字段：

名称 Json标签 类型 属性 取值说明
公司名称 legalName String(255) C 关系类型为第三方且付款人为公司时必填（到address字段）
国家 countryCode String(2) C 关系类型为第三方时必填 国家二字码 如：CN US
公司注册号 registrationNumber String(255) C 国家为非CN时填写
营业执照号 businessLicenseNo String(255) C 国家为CN时填写
公司地址 address String(512) C

PersonalParam字段：

名称 Json标签 类型 属性 取值说明
名 firstName String(255) C 关系类型为第三方且付款人为个人时必填（到passportNo字段）
姓 lastName String(255) C
出生日期 dateOfBirth String(15) C 格式 yyyy-mm-dd
国家 countryCode String(2) C 关系类型为第三方时必填 国家二字码 如：CN US
身份证号 idCardNo String(255) C 国家为CN时填写
护照号 passportNo String(255) C 国家为非CN时填写

CryptoParam字段：

名称 Json标签 类型 属性 取值说明
加密货币地址 address String(512) C 账户类型为数字货币时填写
区块链网络 network String(32) C 区块链网络 TRC20, ERC20, SPL
加密货币币种 currency String(32) C 加密货币币种 暂只支持 USDC USDT
加密货币备注 memo String(255) O 加密货币备注

FiatParam字段：

名称 Json标签 类型 属性 取值说明
银行账号 bankAccountNumber String(255) C 账户类型为法币时填写
账户持有人姓名 bankAccountHolder String(255) C
BIC/SWIFT代码 bic String(32) C
银行账户币种 bankCurrency String(8) C 法币币种如USD EUR CNY
银行所在国家 bankCountryCode String(2) C 国家二字码 如：CN US
银行所在城市 bankCity String(255) C
银地址 bankAddress String(512) C

5.3.2 付款人查询接口

1 功能描述
交易代码 pr4002
功能名称 付款人查询接口
功能描述 付款人查询接口
调用方式 实时接口
调用流程 --
应用场景 付款人查询接口

2 请求地址

Url： https://{baseUrl}/api/pr4002

Method： POST

请求示例:

{
  "beneficiaryNo": "11406032717474000002"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
付款人编号 beneficiaryNo String(64) O pr4001接口创建后返回的参数，如果不传怎么返回该商户号下所有的付款人信息

返回示例:

[
  {
    "merchantNo": "006147100000",
    "beneficiaryNo": "11476040318471700003",
    "beneficiaryName": "John Doe",
    "relationshipType": "THIRD_PARTY",
    "accountType": "CRYPTO",
    "thirdPartParam": {
      "beneficiaryType": "INDIVIDUAL",
      "phone": "13800138000",
      "email": "beneficiary@example.com",
      "companyParam": null,
      "personalParam": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-05-15",
        "idCardNo": "ID123456789012",
        "passportNo": "PASS1234567",
        "countryCode": "CN"
      }
    },
    "cryptoParam": {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "memo": "MEMO123456",
      "network": "TRC20",
      "currency": "USDT"
    },
    "fiatParam": null
  },
  {
    "merchantNo": "006147100000",
    "beneficiaryNo": "11476040317402300002",
    "beneficiaryName": "John Doe",
    "relationshipType": "THIRD_PARTY",
    "accountType": "CRYPTO",
    "thirdPartParam": {
      "beneficiaryType": "INDIVIDUAL",
      "phone": "13800138000",
      "email": "beneficiary@example.com",
      "companyParam": null,
      "personalParam": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-05-15",
        "idCardNo": "ID123456789012",
        "passportNo": "PASS1234567",
        "countryCode": "CN"
      }
    },
    "cryptoParam": {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "memo": "MEMO123456",
      "network": "TRC20",
      "currency": "USDT"
    },
    "fiatParam": null
  }
]

4 响应字段

付款人查询接口返回字段同pr4001字段的集合：

5.3.3 提交付款订单

1 功能描述
交易代码 pr4003
功能名称 提交付款订单
功能描述 提交付款订单
调用方式 实时接口
调用流程 --
应用场景 提交付款订单

2 请求地址

Url： https://{baseUrl}/api/pr4003

Method： POST

请求示例:

{
  "beneficiaryNo": "11406032717474000002",
  "payCurrency": "USDT",
  "payAmount": 3,
  "purpose": "COMMISSION",
  "arriveCurrency": "USD",
  "merOrderNo": "147852"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
商户付款订单号 merOrderNo String(64) M 商户提交付款订单的系统唯一编号
付款人编号 beneficiaryNo String(64) M pr4001返回的付款人唯一编号
支付币种 payCurrency String(8) M
支付金额 payAmount decimal(20,8) C 填写payAmount即无需填写arriveAmount
收款币种 arriveCurrency String(8) M
收款金额 arriveAmount decimal(20,8) C 填写arriveAmount即无需填写payAmount
付款目的 purpose String(30) M 6.1.2付款目的
订单备注 memo String(512) O

返回示例:

{
  "beneficiaryNo": "11406032717474000002",
  "arriveCurrency": "USD",
  "arriveAmount": 3,
  "payCurrency": "USDT",
  "payAmount": 3,
  "status": "01",
  "purpose": "COMMISSION",
  "merOrderNo": "147852",
  "quoteId": 4196032719075000002,
  "expireTime": 1774855289,
  "rate": 0.99886
}

4 响应字段

名称 Json标签 类型 属性 取值说明
报价id quoteId Long M 报价id
商户付款订单号 merOrderNo String(64) M 商户提交付款订单的系统唯一编号
付款人编号 beneficiaryNo String(64) M pr4001返回的付款人唯一编号
支付币种 payCurrency String(8) M
支付金额 payAmount decimal(20,8) M
收款币种 arriveCurrency String(8) M
收款金额 arriveAmount decimal(20,8) M
付款目的 purpose String(30) M
过期时间 expireTime Long M
汇率 rate Long M

5.3.4 确认付款订单

1 功能描述
交易代码 pr4004
功能名称 确认付款订单
功能描述 对上一步提交的付款订单进行确认动作
调用方式 实时接口
调用流程 --
应用场景 确认付款订单

2 请求地址

Url： https://{baseUrl}/api/pr4004

Method： POST

请求示例:

{
  "quoteId": 4196032719075000002,
  "callbackUrl": "https://xxxx.xxxx.xxxx/xxxx/xxxx"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
报价id quoteId Long M 报价id
回调url callbackUrl String(2) M 回调通知Url

返回示例:

{
  "beneficiaryNo": "11406032717474000002",
  "status": "02",
  "quoteId": 4196032719075000002,
  "merOrderNo": "147852"
}

4 响应字段

名称 Json标签 类型 属性 取值说明
报价id quoteId String(64) M
商户付款订单号 merOrderNo String(64) M
付款人编号 beneficiaryNo String(64) M
订单状态 status String(2) M 01-处理中 02-通过 03-拒绝 04-已确认处理中
支付币种 payCurrency String(8) M
支付金额 payAmount decimal(20,8) M
收款币种 arriveCurrency String(8) M
收款金额 arriveAmount decimal(20,8) M
汇率 rate Long M

5.3.5 查询付款订单

1 功能描述
交易代码 pr4005
功能名称 查询付款订单
功能描述 查询付款订单
调用方式 实时接口
调用流程 --
应用场景 查询付款订单

2 请求地址

Url： https://{baseUrl}/api/pr4005

Method： POST

请求示例:

{
  "pageNum": 1,
  "pageSize": 10,
  "beneficiaryNo":"11406032717474000002",
  "merOrderNo":"147258"
}

3 请求字段

名称 Json标签 类型 属性 取值说明
第几页 pageNum Integer O 查询第几页
每页多少条 pageSize Integer O 每页多少条，每页最多支持100条
付款人编号 beneficiaryNo String(64) O
商户付款订单 merOrderNo String(32) O 商户提交付款订单的系统唯一编号

返回示例:

{
  "pageNum": 1,
  "pageSize": 10,
  "total": 2,
  "list": [
    {
      "beneficiaryNo": "11406032717474000002",
      "payCurrency": "USDT",
      "payAmount": 3.00000000,
      "purpose": "COMMISSION",
      "arriveCurrency": "USD",
      "arriveAmount": 2.99000000,
      "merOrderNo": "00000001",
      "quoteId": 1488196350887432192,
      "expireTime": 1774855289,
      "rate": 0.9988600000
    },
    {
      "beneficiaryNo": "11406032717474000002",
      "payCurrency": "USDT",
      "payAmount": 3.00000000,
      "purpose": "COMMISSION",
      "arriveCurrency": "USD",
      "arriveAmount": 2.99000000,
      "merOrderNo": "00000001",
      "quoteId": 1488196350887432192,
      "expireTime": 1774855289,
      "rate": 0.9988600000
    }
  ]
}

4 响应字段

名称 Json标签 类型 属性 取值说明
当前页码 pageNum Integer M
页显示数 pageSize Integer M
总数 total Integer M
交易信息集合 list List<CryptoPayoutApiResp> M

CryptoPayoutApiResp 的字段

名称 Json标签 类型 属性 取值说明
报价id quoteId String(64) M 系统付款唯一编号
商户付款订单号 merOrderNo String(64) M 商户提交付款订单的系统唯一编号
付款人编号 beneficiaryNo String(64) M pr4001返回的付款人唯一编号
支付币种 payCurrency String(8) M
支付金额 payAmount decimal(20,8) M
收款币种 arriveCurrency String(8) M
收款金额 arriveAmount decimal(20,8) M
付款目的 purpose String(30) M
订单状态 status String(2) M 01-处理中 02-通过 03-拒绝
过期时间 expireTime Long M
汇率 rate Long M

5.4 账务

5.4.1 账户余额查询

1 功能描述

交易代码 pr3004
功能名称 账户余额查询
功能描述 当前账户余额查询
调用方式 实时接口
调用流程 --
应用场景 当前账户余额查询

2 请求地址

Url： https://{baseUrl}/api/pr3004

Method： POST

3 请求字段

名称 Json标签 类型 属性 取值说明
币种 currency String(10) O 币种，若不传则为查询所有币种账户

返回示例:

[
    {
        "currency": "USD",
        "balance": "2000.00",
        "status":"on"
    },
    {
        "currency": "CNY",
        "balance": "8231.22",
        "status":"off"
    }
]

4 响应字段

接口返回对象为: List<CurrencyBalance>

CurrencyBalance 字段：

名称 Json标签 类型 属性 取值说明
币种 currency String(10) M 币种
余额 balance String(10) M 账户余额
账户状态 status String(3) M 账户状态: on 为启用， off为禁用

5.4.2 账务流水交易查询

1 功能描述

交易代码 pr3009
功能名称 账务流水历史交易查询
功能描述 账务流水历史交易查询
调用方式 实时接口
调用流程 --
应用场景 查询以往的账务流水历史交易

2 请求地址

Url： https://{baseUrl}/api/pr3009

Method： POST

3 请求字段

名称 Json标签 类型 属性 取值说明
查询起始时间 beginDate Long O Unix13位时间戳，查询开始时间，闭区间
查询结束时间 endDate Long O Unix13位时间戳，查询开始时间，闭区间
业务订单号 batchNo String(32) O Payroad生成的唯一流水号
币种 currency String(10) O 币种
收支类型 flowType String(3) O 收支类型 1: "入金", 2: "出金"
流水类型 busiType String(3) O 6.1.6流水类型
第几页 pageNum Integer O 查询第几页
每页多少条 pageSize Integer O 每页多少条，每页最多支持100条

返回示例:

{
    "pageNum": 1,
    "pageSize": 10,
    "total": 9668,
    "list": [{
        "currency": "USD",
        "busiType": "C11",
        "busiDate": "2020-05-28 19:32:14",
        "inAmount": null,
        "outAmount": 7.0000,
        "vailAmount": 5572.3100,
        "batchNo": "41200528653124170019"
    }, {
        "currency": "USD",
        "busiType": "C07",
        "busiDate": "2020-05-27 17:52:56",
        "inAmount": null,
        "outAmount": 2218.0000,
        "vailAmount": 5628.3100,
        "batchNo": "41200527728820950004"
    }]
}

4 响应字段

名称 Json标签 类型 属性 取值说明
当前页码 pageNum Int M --
页显示数 pageSize Int M --
总数 total Int M --
账务流水信息集合 list List<CurFlowRes> M --

CurFlowRes 的字段

名称 Json标签 类型 属性 取值说明
账务流水订单 batchNo string(32) M 账务流水订单
币种 currency string(10) M 账务流水币种
流水类型 busiType String(3) M 6.1.1流水类型
入金 inAmount decimal(18,2) M 入金金额
出金 outAmount decimal(18,2) M 出金金额
可用金额 vailAmount decimal(18,2) M 可用金额
交易时间 busiDate Date M 交易时间

6 附录

6.1.1 busiType 流水类型

字段值 说明
C00 充值
C01 换汇
C02 换汇退回
C11 手续费
C12 手续费退回
C25 付款
C26 收款
C31 付款退回

6.1.2 purpose 类型

字段值 说明
REFUND 因订单取消、超额支付或服务不满产生的退款
GOODS_SERVICES 为购买实物商品、数字产品或接受服务所支付的款项
COMMISSION 经纪人费用、前端费、承诺费、担保费及托管费
ROYALTY_DIVIDENDS 特许权使用费、著作权使用费、专利许可费或股息分配款项
LOAN_REPAY 贷款本金、利息的偿还，或相关贷款债务的清偿
TREASURY 企业内部资金划转、资金管理或账户间资金分配
RENT 房地产、办公场地、设备或其他租赁资产的租金款项
OTHERS 保险费或其他未做分类的支付用途
REJECT_RETURN 因支付被驳回、交易失败或收款方信息无效导致的资金退回

7 mock说明

为了方便api对接过程中的流畅性，按照如下规则提交交易会进行自动审核，一般在五分钟之内会完成自动审核。

7.1 pr1003

调用pr1002牌价查询接口时，根据金额个位数字，0,1,2,3则换汇成功，4,5,6则换汇失败，7,8,9则是处理中 状态，0,1,2,3则付款成功，4,5,6则付款失败，7,8,9则是处理中

代码示例