OTT PAY HK跨境支付API文档

1. 概述

1.1 编写目的

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

1.2 定义和缩略语

UML时序图

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

测试联调阶段

平台开发完成进行系统联调测试前，需要准备如下事项：

平台生成测试环境的RSA密钥对，并将公钥发提供给Ottpayhk；
申请开通测试环境平台号；

上线阶段

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

1.4 更新日志

1.0.51 优化结汇下发功能 2023-11-01

人民币付款接口TP1001交易编码更新
人民币付款接口TP1001还原材料列表收款人姓名/收款人证件号必填条件变更，新增收款人账号字段

1.0.50 新增委托换汇功能 2023-09-14

新增委托换汇申请接口TP1027
新增委托换汇取消接口TP1028

1.0.49 商户收款/结汇/国际汇款功能优化 2023-05-25

贸易收款到账通知接口TP2007新增非必填字段汇款附言
收款VA入账查询接口接口TP3015新增非必填返回字段汇款附言
人民币付款接口TP1001中收款信息新增非必填请求字段汇款附言
国际汇款接口接口TP1004新增非必填字段是否POBO

1.0.48 商户收款功能/国际汇款功能优化 2023-03-30

新增商户新增账户持有人接口TP1024
新增商户修改账户持有人接口TP1025
新增商户账户持有人补充信息接口TP1026
新增商户账户持有人状态变更通知接口TP2013
新增异常退款状态通知接口TP2014
新增商户查询账户持有人接口TP3018
商户VA开户申请TP1017新增持有人ID，用于申请入网的持有人信息

1.0.47 商户结汇付款功能优化 2023-02-09

新增商户新增结汇收款人接口TP1021
新增商户修改结汇收款人接口TP1022
新增商户删除结汇收款人接口TP1023
新增商户查询结汇收款人接口TP3017

1.0.46 人民币付款功能优化 2022-12-08

人民币付款申请接口tp1001收款人信息字段新增部分非必填字段
人民币付款申请接口tp1001收款人信息字段cNAPSCode联行号改为条件必传，企业必填，个人非必填

1.0.45 商户入网功能优化 2022-12-08

新增商户入网与VA整合接口TP1020
作废商户入网接口TP1015
作废商户入网修改接口TP1018

1.0.44 人民币付款功能优化 2022-11-04

人民币付款申请接口tp1001新增入参字段扣款币种，扣款金额，结汇类型选填字段
人民币付款申请接口tp1001新增返回字段报价ID，汇率，报价的有效时间等字段
新增人民币付款确认接口tp1019
人民币付款通知接口tp2001新增返回字段结汇类型，汇率，扣款币种等字段
人民币付款查询接口tp3001新增返回字段结汇类型，汇率，扣款币种等字段

1.0.43 VA开户申请优化 2022-09-22

修改VA开户申请接口tp1017

1.0.42 商户入网功能优化 2022-08-25

修改商户入网接口tp1015
新增商户入网修改接口tp1018

1.0.41 新增VA开通功能 2022-07-26

新增VA开户申请接口tp1017
新增VA开户结果通知接口tp2012
修改VA开户查询接口tp3012

1.0.40 新增电商收款功能 2022-07-23

新增电商订单申请接口tp1016
新增电商额度查询接口tp3016
修改贸易收款到账通知接口tp2007
修改贸易收款VA入账查询接口tp3015

1.0.39 商户入网字段调整 2022-06-14

tp1015 商户入网字段更新调整

1.0.38 新增交易mock功能 2022-06-01

新增交易mock功能，详细说明请看"mock说明”

1.0.37 新增充值成功通知接口 2022-05-26

新增充值成功通知接口tp2011
充值交易历史查询接口响应字段新增实际入账金额

1.0.36 人民币接口电商类型还原材料改为选填 2022-05-17

人民币付款时，电商类型的订单，还原材料改为选填

1.0.35 新增代理商商户入网接口 2022-05-10

新增代理商商户入网接口 tp1015
关闭一级商户入网，原来对接的可以继续用

1.0.34 新增一级商户入网接口 2022-03-04

新增商户入网接口

1.0.33 人名币付款接口更新还原材料字段 2022-01-17

人民币付款接口更新字段

1.0.32 牌价查询接口增加T2锁汇类型 2022-01-07

牌价查询接口增加T2锁汇类型

1.0.31 贸易合同申请接口更新 2021-09-07

贸易订单申请新增服务贸易字段信息TP1012

1.0.30 追加退款通知接口 2021-08-06

新增人民币和国际汇款的退款通知接口(tp2010)

1.0.29 新增贸易收款相关接口 2021-06-23

新增贸易订单申请tp1012/收款流水和贸易订单关联tp1013/回调地址设置tp1014
贸易收款到账通知tp2007/贸易订单申请结果通知tp2008/收款流水和贸易订单关联结果通知tp2009
新增贸易订单申请信息查询接口tp3013/新增收款流水和贸易订单关联查询接口tp3014/贸易收款VA入账查询接口tp3015
人民币付款tp1001增加手机号必填项

1.0.28 修改5.1.7 商户入网 2021-06-18

修改商户入网字段

1.0.27 修改tp1001接口请求字段 2021-06-01

新增payReduceList还原材料字段（仅限游戏、电商、一般贸易时填写）

1.0.26 增加5.1.10 VA账户开户申请tp1011和5.3.16 VA账户查询tp3012 2021-05-31

新增5.1.10 VA账户开户申请tp1011。
新增5.3.16 VA账户查询tp3012。

1.0.25 增加5.1.9商户间转账接口tp1010 2021-04-21

新增5.1.9商户间转账接口tp1010，支持同为OTT注册的商户完成内部转账。

1.0.24 修改tp1004接口请求字段 2021-03-17

tp1004国际汇款，新增debitAmount扣款金额，可支持锁定扣款金额或付款金额2种。

1.0.23 修改tp3005接口返回字段 2021-03-15

更新purpose汇款目的

1.0.22 修改tp3005接口返回字段 2021-03-09

增加selectOption枚举值返回

1.0.21 修改tp1001接口请求字段 2021-01-12

PayOrderRequest内新增必填字段payeeName收款方姓名
cNAPSCode改为唯一必填项

1.0.20 修改tp3006接口返回字段 2020-11-12

tp3006返回code和message修改为resCode和resMessage

1.0.19 增加一天一价牌价查询接口 2020-10-12

新增5.3.15 一天一价牌价查询

1.0.18 增加商户查询充值流水列表、账务流水列表以及手续费流水列表 2020-08-06

新增5.3.12 充值交易历史查询
新增5.3.13 账务流水交易查询
新增5.3.14 手续费交易历史查询

1.0.17 增加商户入网接口&人民币接口修改 2020-07-31

新增5.1.7商户入网/5.1.8商户入网信息完善/5.2.4商户入网结果通知
5.1.1人民币付款请求参数增加feeFlag，返回参数增加feeCurrency/feeAmount/actualPayAmount
5.3.1人民币付款查询，返回参数增加feeCurrency/feeAmount/actualPayAmount

1.0.16 新增tp2006国际汇款付款凭证通知 2020-06-04

1.0.15 tp3005增加银行列表字段 2020-04-22

1.0.14 国际汇款修改 2020-03-20

国际汇款增加汇款附言
更新 purpose 汇款目的
更新 purpose 汇款目的

1.0.13 国际汇款增加关联fx订单字段 2020-03-17

1.0.12 修改人民币付款接口字段 2020-03-01

1.0.11 FX和国际汇款修改 2020-02-28

FX 接口增加支持 T0 T1 锁汇
对国际汇款相关接口字段修改：增加汇款目的

1.0.10 人民币下发申请字段修改 2020-02-13

人民币下发申请接口新增字段
首次收款人提交营业执照和法人照片

1.0.9 人民币下发回调新增字段respCode 2020-01-22

1.0.8 增加国际汇款相关接口 2020-01-17

1.0.7 增加联行号查询接口 2020-01-16

1.0.6 人民币付款添加受理状态 2019-12-30

1.0.5 修改批量付款请求 2019-12-26

1.0.4 增加FX相关接口 2019-12-18

1.0.3 修改批量上传接口参数 2019-12-17

1.0.2 修改批量上传接口 2019-12-16

1.0.1 增加5.3.1和6.1 2019-05-13

1.0.0 新建 2019-04-29

2. 通讯协议

2.1 协议约定

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

3 交易接口规范

3.1 请求报文

{
  "head": {
    "version": "1.0.0",
    //--报文版本号
    "tradeType": "00",
    //--00请求报文
    "tradeTime": "1551341750",
    //--请求时间，10位unix时间戳
    "tradeCode": "tp1001",
    //–请求交易代码
    "language": "cn"
    //–语言
  },
  "body": {
    //…
  }
}

请求报文由两部分组成：请求报文头和请求报文体。其中请求报文头信息在报文头（head. 节点内，请求报文体信息在报文体（body. 节点内。
报文头是每个交易都相同的。请求报文头信息的填写标准请参看JSON规范示例。
报文体根据每个交易的接口定义而各不相同。请求报文体的定义请参看“业务交易接口”章节。需按照每个交易的接口定义组装和解析请求报文体。
客户端请求报文上送时，POST提交四个参数：merchantNo=平台代码;jsonEnc=报文密文；keyEnc=会话密钥密文；sign=报文签名，其中merchantNo 为Ottpayhk为合作平台分配的商户号明文，jsonEnc参数的内容就是整个报文加密以后的十六进制字符串，keyEnc参数为报文加密会话密钥的密文，sign参数的内容是本次报文的签名。

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

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

3.2 响应报文

{
  "head": {
    "version": "1.0.0",
    //--报文版本号
    "tradeType": "01",
    //--01响应报文
    "tradeTime": "1551341750",
    //--响应时间，10位unix时间戳
    "tradeCode": "tp3001",
    //--对应请求的交易代码
    "respCode": "S00000",
    //--请求返回码
    "respDesc": "请求成功"
    //--请求返回描述
  },
  "body": {
    //…
  }
}

交易应答报文由两部分组成：应答报文头和应答报文体。其中应答报文头信息在报文头（head）节点内，应答报文体信息在报文体（body）节点内。
报文头是每个交易都相同的。应答报文头信息的填写标准请参看JSON规范示例。
报文体根据每个交易的接口定义而各不相同。应答报文体的定义请参看"交易报文接口”章节。需按照每个交易的接口定义组装和解析应答报文体。
交易成功时的应答报文，报文头的respCode为S00000，respDesc为"交易成功”,此时报文体（body）节点根据实际业务需要为空也可以不为空。
交易错误时的应答报文，错误码和错误信息填写在报文头的respCode（返回码）和respDesc（返回信息描述）域中；报文体（body）节点为空。
服务器端响应报文返回时，将商户号、报文密文、会话密钥和签名以标准json字符串返回 {"merchantNo”:"",jsonEnc":"","keyEnc":"","sign":""} ，然后将字符串的字节流写入http的返回对象。客户端收到服务器端的响应时将HTTP服务方返回的字节流按照相应格式的字符串进行报文和摘要参数的获取，参数获取后，先要进行摘要校验，校验通过后在解析报文内容。

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

4 加密及签名规范

4.1 原则

交易报文传输都需要进行加密、签名和校验。
无论是请求端还是响应端接收到报文后，都需要进行签名验证，即按照约定算法重新生成签名，然后和收到的签名进行对比，对比通过后才能进行报文内容的解析，否则报文或文件内容可能出现篡改、部分丢失、伪造的问题。
报文加密算法：DES/CBC/PKCS5Padding
会话密钥生成：KeyGenerator生成
会话密钥加密算法：RSA/ECB/PKCS1Padding
签名算法：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发给Ottpayhk，
#或商户直接可以向Ottpayhk索要密钥对的生成脚本，生成商户所需的公私钥。
#Ottpayhk也需要把Ottpayhk生成的对应的公钥pem发给商户。

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

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

4.3 报文加密及签名

加密及签名

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

4.4 报文解密及验签

解密及验签

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

4.5 accessToken 使用说明

以 FX 询价接口为例，在 head 内增加参数 accessToken，即代表当前用户主体发起操作。 Sample:

{
  "head": {
    "accessToken": "7c4a8d09ca3762af61e59520943dc26494",
    "version": "1.0.0",
    "tradeType": "00",
    "tradeTime": "1551341750",
    "tradeCode": "TP1002",
    "language": "cn"
  },
  "body": {
    "sellCurrency": "USD",
    "buyCurrency": "CNY",
    "rate": "7.0102",
    "sellAmount": "1000.00",
    "buyAmount": "7010.20",
    "quoteId": "7843892398239",
    "expireTime": "1576560599598",
    "merOrderNo": "32894398349"
  }
}

5 业务接口

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

5.1 商户入网

5.1.1 代理商商户入网和VA开户整合

1 功能描述


交易代码	TP1020
功能名称	代理商商户入网和VA开户整合
功能描述	收集商户资料，完成商户入网和VA开户，分为新增和修改功能，存在字段bizFlow为修改功能，修改功能仅支持拒绝字段修改，非拒绝字段不予处理，拒绝会同步拒绝VA，请求修改接口且需要同步开通VA时需同时重新上传VA信息
调用方式	实时接口
调用流程	--
应用场景	本指引目的为OTTPAY HK收集商户资料信息， OTTPAY HK方资质审查后，予以商户资质审批通过和VA审批通过，可为商户提供后续服务。

2 请求地址

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

{
  "addMaterial": "0",
  "addressMaterial": [
    "uploadFile/hzfr.jpg"
  ],
  "addressType": "2",
  "authorization": [
    "uploadFile/hzfr.jpg"
  ],
  "brExpiryDate": "2031-11-11",
  "branchCompany": [
    {
      "country": "CN",
      "name": "companyInfo1"
    },
    {
      "country": "US",
      "name": "companyInfo2"
    }
  ],
  "branchRemark": "1",
  "businessCountry": [
    "UZ"
  ],
  "businessNature": {
    "natureType": "0",
    "natures": [
      "8",
      "4"
    ]
  },
  "callBackUrl": "https://www.baidu.com",
  "certificate": [
    "uploadFile/hzfr.jpg"
  ],
  "certificateNumber": "02224230995",
  "clientCountry": [
    "UZ"
  ],
  "companyCertificate": [
    "uploadFile/hzfr.jpg",
    "uploadFile/hzfr.jpg"
  ],
  "companyCertificateNumber": "87361378062",
  "companyWebsite": "https://www.baidu.com",
  "countryCode": "CN",
  "customer": [
    {
      "address": "紫禁之巅",
      "birthDate": "1977-07-21",
      "certificateDate": "2038-07-21",
      "certificates": [
        "uploadFile/hzfr.jpg"
      ],
      "idNumber": "370121197707211040",
      "issuPlace": "CN",
      "name": "test001",
      "nationality": "CN",
      "residenceCountry": "CN",
      "type": "0"
    },
    {
      "address": "紫禁之巅",
      "birthDate": "1977-07-21",
      "certificateDate": "2038-07-21",
      "certificates": [
        "uploadFile/hzfr.jpg"
      ],
      "idNumber": "370121197707211040",
      "issuPlace": "HK",
      "name": "test002",
      "nationality": "HK",
      "residenceCountry": "HK",
      "type": "0"
    }
  ],
  "customerIdentity": [
    "0",
    "1"
  ],
  "director": [
    {
      "address": "紫禁之巅",
      "birthDate": "1977-07-21",
      "certificateDate": "2038-07-21",
      "certificates": [
        "uploadFile/hzfr.jpg"
      ],
      "idNumber": "370121197707211040",
      "issuPlace": "CN",
      "name": "test001",
      "nationality": "CN",
      "residenceCountry": "CN",
      "type": "0"
    },
    {
      "address": "紫禁之巅",
      "birthDate": "1977-07-21",
      "certificateDate": "2038-07-21",
      "certificates": [
        "uploadFile/hzfr.jpg"
      ],
      "idNumber": "370121197707211040",
      "issuPlace": "HK",
      "name": "test002",
      "nationality": "HK",
      "residenceCountry": "HK",
      "type": "0"
    }
  ],
  "email": "12042736@00.com",
  "enterprisePath": [
    "uploadFile/hzfr.jpg"
  ],
  "establishDate": "2011-11-11",
  "inCountry": [
    "UZ"
  ],
  "lastYearTurnover": "1",
  "legalPerson": [
    {
      "address": "紫禁之巅",
      "birthDate": "1977-07-21",
      "certificateDate": "2038-07-21",
      "certificates": [
        "uploadFile/hzfr.jpg"
      ],
      "idNumber": "370121197707211040",
      "issuPlace": "CN",
      "name": "test001",
      "nationality": "CN",
      "residenceCountry": "CN",
      "type": "0"
    }
  ],
  "merNameEn": "LNQ169275783313408",
  "merOrderNo": "LNQ1692757833134",
  "mermorandum": [
    "uploadFile/hzfr.jpg"
  ],
  "nar1Path1": [
    "uploadFile/hzfr.jpg"
  ],
  "nnc1Path": [
    "uploadFile/hzfr.jpg"
  ],
  "noticeMarker": "0",
  "otherPath": "uploadFile/hzfr.jpg",
  "outCountry": [
    "UZ"
  ],
  "ownerShipPath": [
    "uploadFile/hzfr.jpg",
    "uploadFile/hzfr.jpg"
  ],
  "parentCertificate": [
    "uploadFile/hzfr.jpg",
    "uploadFile/hzfr.jpg"
  ],
  "parentCompany": [
    {
      "country": "CN",
      "name": "companyInfo1"
    },
    {
      "country": "US",
      "name": "companyInfo2"
    }
  ],
  "parentRemark": "1",
  "participantsType": [
    "0"
  ],
  "paymentPurpose": [
    "4",
    "5"
  ],
  "phoneAreaCode": "86",
  "phoneNum": "18734183423",
  "postscript": "",
  "realCompanyAddress": "紫禁之巅",
  "referralChannel": "0000000000",
  "registrationAddress": "紫禁之巅",
  "riskCountryTransaction": "0",
  "shareholder": [
    {
      "address": "紫禁之巅",
      "birthDate": "1977-07-21",
      "certificateDate": "2038-07-21",
      "certificates": [
        "uploadFile/hzfr.jpg"
      ],
      "idNumber": "370121197707211040",
      "issuPlace": "CN",
      "name": "test001",
      "nationality": "CN",
      "residenceCountry": "CN",
      "type": "0"
    },
    {
      "address": "紫禁之巅",
      "birthDate": "1977-07-21",
      "certificateDate": "2038-07-21",
      "certificates": [
        "uploadFile/hzfr.jpg"
      ],
      "idNumber": "370121197707211040",
      "issuPlace": "HK",
      "name": "test002",
      "nationality": "HK",
      "residenceCountry": "HK",
      "type": "0"
    }
  ],
  "sourceFunds": [
    "4",
    "5"
  ],
  "suppliersCountry": [
    "UZ"
  ],
  "transaction": [
    {
      "country": "CN",
      "tradeOption": "1",
      "tradeType": "0"
    }
  ],
  "transactionAmount": "1",
  "vaFlag": "1",
  "vaInfo": [
    {
      "acctSimpleName": "LNQ1692757833134",
      "applyCode": "ELECTRONIC_OPTICAL_PRODUCTS",
      "area": "US",
      "callbackUrl": "https://www.baidu.com",
      "currency": "USD",
      "isSameName": "Y",
      "merOrderNo": "VA_LNQ1692757833134_01",
      "parentCode": "T",
      "shopName": "https://www.baidu.com",
      "webSiteUrl": "https://www.baidu.com"
    },
    {
      "acctSimpleName": "LNQ1692757833134",
      "applyCode": "ELECTRONIC_OPTICAL_PRODUCTS",
      "area": "US",
      "callbackUrl": "https://www.baidu.com",
      "currency": "USD",
      "isSameName": "Y",
      "merOrderNo": "VA_LNQ1692757833134_02",
      "parentCode": "T",
      "shopName": "https://www.baidu.com",
      "webSiteUrl": "https://www.baidu.com"
    }
  ],
  "webSiteOrApp": "https://www.baidu.com"
}

3 请求参数

名称	Json标签	类型	属性	取值说明
商户唯一订单号	merOrderNo	string(32)	M	商户唯一订单号
入网申请唯一订单号	bizFlow	string(32)	C	入网申请唯一订单号，仅修改功能必传，由新增功能同步返回
入网邮箱	email	string(64)	M	唯一入网邮箱
手机区号	phoneAreaCode	string(10)	M	手机号区号
手机号	phoneNum	string(32)	M	唯一入网手机号
推荐代理商	referralChannel	string(16)	M	注册推荐代理商编号 (OTT提供) 测试环境默认： 0000000000
商户注册国家/地区	countryCode	string(2)	M	注册国家/地区 iso 二字码
商户英文名	merNameEn	string(255)	M	唯一入网商户的英文名
商户中文名	merNameCn	string(255)	C	入网商户的中文名，注册国家为中国时必填
公司成立日期	establishDate	string(16)	M	公司成立日期，格式：yyyy-MM-dd
商业登记证或企业证件到期日	brExpiryDate	string(16)	M	商业登记证或企业证件到期日，格式：yyyy-MM-dd
公司注册地址	registrationAddress	string(255)	M	公司注册地址
全国工商企业文件	enterprisePath	`List<String>`	C	全国工商企业文件，注册国家为中国大陆时必填请至https://www.gsxt.gov.cn/index.html注册下载报告
是否具有母公司	parentRemark	string(2)	M	是否具有母公司 0：无 1：有
股权架构图	ownerShipPath	`List<String>`	C	当具有母公司时，该值必传
母公司注册证明	parentCertificate	`List<String>`	C	当具有母公司并且非中国大陆时，该值必传
母公司信息	parentCompany	`List<companyInfo>`	C	当具有母公司时，该值必传
是否具有子公司	branchRemark	String(2)	M	是否具有子公司或分公司 0：无 1：有
分公司/子公司信息	branchCompany	`List<companyInfo>`	C	当有子公司或者分公司时必传
商户注册文件	certificate	`List<String>`	M	商户注册证明，中国大陆提供营业执照，香港提供商业登记证，境外传公司注册证明
商户注册证件号	certificateNumber	String(255)	M	商户注册证件号，中国大陆提供营业执照证件号，香港提供商业登记证（BR）号码，境外传公司注册证书（CI）号码
公司注册证书	companyCertificate	`List<String>`	C	公司注册证书(文件)，当公司属于香港时必传
公司注册证书号码	companyCertificateNumber	String(255)	C	公司注册证书（CI）号码，当公司属于香港时必传
收款付款参与方	participantsType	`List<String>`	M	主要的收款付款参与方是公司还是个人 0:公司 1:个人
法团成立表	nnc1Path	`List<String>`	C	当公司为非中国大陆必传上传最新法团成立表NNC1的照片或扫描件
周年年报	nar1Path1	`List<String>`	O	当公司为境外公司选传若您公司成立一年以上，请上传最新周年年报的照片或扫描件
公司章程	mermorandum	`List<String>`	C	当公司为境外公司必传
被授权人身份	customerIdentity	`List<String>`	M	入网客户被授权人的身份参数详见6.1.10字段说明
被授权人信息	customer	`List<personalInfo>`	M	被授权人信息
持股25%以上股东	shareholder	`List<personalInfo>`	M	持股25%以上股东的信息
公司董事	director	`List<personalInfo>`	C	公司董事信息，非中国大陆国家必传
法人	legalPerson	`List<personalInfo>`	C	法人信息，国家为中国大陆时必传
董事会议授权书	authorization	`List<String>`	M	董事会议授权书注：需要满足以下条件：授权书需加盖公章，董事/法人签字或签章以及被授权人签字
资金来源	sourceFunds	`List<String>`	M	资金主要来源参数详见6.1.8字段说明
付款目的	paymentPurpose	`List<String>`	M	付款主要目的参数详见6.1.9字段说明
风险交易国家/地区	riskCountryTransaction	String(2)	M	0：无 1：有是否有伊朗、朝鲜、古巴地区有任何直接或间接的业务
风险国家信息	riskCountries	`List<companyInfo>`	C	当有和以上风险国家企业交易时，提供企业信息
是否为补充请求	addMaterial	String(2)	O	0：否 1：是当回调code为80000时，需要请求加上补充材料
补充材料	reMaterial	`reMaterial`	O	回调code为80000时，需要传参
公司真实营业地址	realCompanyAddress	string(255)	M	公司真实营业地址
公司真实营业地址证明材料	addressMaterial	`List<String>`	O	公司真实营业地址证明材料一、当注册主体为中国大陆, 请至少以下提供一种：1.近三个月内同名公司银行对账单，首页需包含地址（优先提供）；2.近三个月内同名公司的增值税发票，需包含地址（优先提供）；3.近三个月内同名公司的官方水电费账单，需包含地址；4.包含地址的公司产品目录、服务手册、广告单或宣传单张等。二、当注册主体是香港公司,但其总公司在中国大陆或在中国大陆有直接联系的公司，请提供该中国大陆公司营业执照。注：提供该信息有助于加快入网
公司地址类型	addressType	string(1)	M	公司地址类型 0自租办公室 1秘书处地址 2共享办公室
公司官网	companyWebsite	string(128)	O	公司官网地址注：提供该信息有助于加快入网
主要客户所在国家/地区	clientCountry	`List<String>`	M	主要客户所在国家/地区 (国家二字码)
业务所在国家/地区	businessCountry	`List<String>`	M	在哪个国家/地区经营（开展）业务 (国家二字码)
目前合作伙伴和供应商所在国家/地区	suppliersCountry	`List<String>`	M	目前合作伙伴和供应商所在国家/地区 (国家二字码)
目前和预计需要的收款服务的汇入国家/地区	inCountry	`List<String>`	M	目前和预计需要的收款服务的汇入国家/地区 (国家二字码)
目前和预计需要的付款服务的汇出国家/地区	outCountry	`List<String>`	M	目前和预计需要的付款服务的汇出国家/地区 (国家二字码)
去年的营业额（USD）	lastYearTurnover	string(2)	M	去年的营业额（USD）参数详见6.1.16字段说明
预估交易量 (每月)(USD)	transactionAmount	string(2)	M	预估交易量 (每月)(USD) 参数详见6.1.17字段说明
交易模式	transaction	`List<Transaction>`	M	交易模式
销售网址或者app名	webSiteOrApp	string(350)	C	销售网址或者app名 transaction中tradeType存在1时填写
业务性质	businessNature	`BusinessNature`	M	业务性质
是否通知	noticeMarker	string(1)	M	是否邮件短信通知商户 0不通知 1通知
回调地址	callBackUrl	String(255)	M	用于接收商户入网结果,必须http/https开头
其他附件	otherPath	String(255)	O	其他附件（仅允许单个地址，多个文件打包上传）
附言	postscript	String(255)	O	附言
是否同步开通VA	vaFlag	string(1)	M	是否同步开通VA，0不开通，1开通
VA信息	vaInfo	`List<VaInfo>`	C	开通VA信息，vaFlag=1时必填

Transaction

名称	Json标签	类型	属性	取值说明
交易模式	tradeType	string(1)	M	交易模式 0:线下交易 1:线上交易
交易模式分类	tradeOption	string(1)	M	选项 tradeType为0时{0:品牌商 1:代理商} tradeType为1时{0:WEB 1:APP}
品牌代理商所在国家/地区	country	string(1)	C	国家/地区（国家二字码） tradeType为0时填写

BusinessNature

名称	Json标签	类型	属性	取值说明
业务性质类型	natureType	String(2)	M	性质类型 0货贸 1服贸
业务性质	natures	`List<String>`	M	业务性质明细 natureType为0时参数详见6.1.11字段说明 natureType为1时参数详见6.1.12字段说明

reMaterial

名称	Json标签	类型	属性	取值说明
财务报表或公司税务申报表/完税证明	financialStatements	`List<String>`	M	财务报表或公司税务申报表/完税证明
调查表	questionnaire	`List<String>`	M	调查表
表现最好的3家客户	bestCustomer	`List<companyInfo>`	M	表现最好的3家企业信息
表现最好的3家供应商/合作伙伴公司	bestPartner	`List<companyInfo>`	M	表现最好的3家供应商/合作伙伴公司信息

personalInfo

名称	Json标签	类型	属性	取值说明
证件类型	type	String(2)	M	证件类型 0 身份证 1 护照
姓名	name	String(255)	M	客户姓名
证件签发国家/地区	issuPlace	String(2)	M	国家ISO 二字码
国籍	nationality	String(2)	M	国家ISO 二字码
有效证件号码	idNumber	String(64)	M	有效证件号码
出生日期	birthDate	String(16)	M	出生日期，格式：yyyy-MM-dd
证件到期日期	certificateDate	String(16)	M	证件到期日期，格式：yyyy-MM-dd
居住国家/地区	residenceCountry	String(2)	M	国家ISO 二字码
居住地址	address	String(255)	C	居住地址除被授权人外其余必传
证件文件	certificates	`List<String>`	M	证件sftp地址

companyInfo

名称	Json标签	类型	属性	取值说明
公司名称	name	String(64)	M	公司注册名称
公司注册国家/地区	country	String (2)	M	公司所在国家/地区

VaInfo

名称	Json标签	类型	属性	取值说明
商户唯一订单号	merOrderNo	string(32)	M	商户唯一订单号
申请大类	parentCode	string(1)	M	申请大类，暂时只支持 S:平台电商 D:独立站电商 T:线下一般货贸 F:服务贸易
申请子类	applyCode	string(64)	M	申请子类,填写业务子英文名详见6.1.13申请子类字段
收款国家/地区	area	string(2)	M	收款国家/地区标准2字代码
收款币种	currency	string(3)	M	收款币种，3位标准货币代码
账户简称	acctSimpleName	string(128)	M	账户简称
银行类	bankType	string(3)	O	银行类，填写银行类枚举值，仅线下一般货贸、服务贸易选填详见6.1.14bankType 银行类
店铺名称	shopName	string(128)	M	店铺名称
店铺链接	shopUrl	string(350)	O	店铺链接，平台电商、独立站电商必填
收单方式	collectType	string(12)	O	收单方式，枚举值：PayPal,stripe,other 仅独立站中自建站必填
收单方式名称	collectName	string(127)	O	收单方式名称，collectType为 other时填写
销售地址	webSiteUrl	string(350)	O	销售地址，线下一般货贸、服务贸易填写，与业务说明文件必填其一，可全填
是否同名	isSameName	string(1)	M	是否同名 Y:是 N:否
业务说明文件	busDesDocument	`List<String>`	O	多个附件文件地址数组，线下一般货贸、服务贸易填写，与销售地址必填其一，可全填
店铺持有证明	storeHoldCertify	`List<String>`	O	多个附件文件地址数组，电商、独立站提交
回调地址	callBackUrl	String(255)	M	用于接收商户VA申请结果
VA其他附件	otherPath	String(255)	O	其他附件（仅允许单个地址，多个文件打包上传）
VA附言	postscript	String(255)	O	附言

{
  "bizFlow": "230823103034820183",
  "code": "S00001",
  "merOrderNo": "LNQ1692757833134",
  "message": "Processing",
  "status": "ACCEPT"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
业务流水号	bizFlow	string(32)	M	入网申请唯一订单号
商户唯一订单号	merOrderNo	string(32)	O	商户唯一订单号
状态	status	string(6)	M	申请状态码 ACCEPT:接收成功，等待回调 SUCC:审核通过 FAIL:失败 REFUSE:审核拒绝
结果码	code	string(6)	M	响应结果代码，S00001 代表已接收成功，等待OTTPAY HK审核后回调
结果描述	message	string(255)	M	响应描述

5.1.2 商户入网结果通知

1 功能描述


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

2 请求地址

Url： 商户入网信息完善中的 callbackUrl

Method： POST

{
  "authorizeCode": "6406903b413c0abaeb7afb6c76025074",
  "bizFlow": "230823103034820183",
  "code": "S00000",
  "merNameEn": "LNQ169275783313408",
  "merOrderNo": "LNQ1692757833134",
  "merchantNo": "008850102219",
  "message": "Success",
  "status": "SUCC"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
业务流水号	bizFlow	string(32)	M	入网申请唯一订单号
商户唯一订单号	merOrderNo	string(32)	O	商户唯一订单号
结果码	code	string(6)	M	响应结果代码，S00000 代表入网成功
结果描述	message	string(255)	M	响应描述
商户号	merchantNo	string(32)	M	商户号，为商户的唯一标识号码
商户英文名称	merNameEn	string(255)	M	商户英文名称
授权码	authorizeCode	string(32)	M	授权码

5.2 授权

5.2.1 申请授权

1 功能描述


交易代码	TP9001
功能名称	申请授权
功能描述	用户需在OTTPAY HK 侧完成OAuth 认证，用户在完成授权后，代理商可获得对用户数据操作的权限。
调用方式	浏览器链接
调用流程	--
应用场景	名下商户获取接口的权限

2 请求地址

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

Method： 链接

3 请求字段

名称	Json标签	类型	属性	取值说明
重定向URL	redirectUrl	string(255)	M	重定向 url，生产https://msp.ottpayhk.com/ 测试https://uat.msp.ottpayhk.com/
商户编号	merchantNo	string(255)	M	代理商的商户号

4 响应字段

名称	Json标签	类型	属性	取值说明
授权码	authorizeCode	string(32)	M	授权码

5.2.2 申请token

1 功能描述


交易代码	TP9002
功能名称	申请token
功能描述	获取商户唯一token，用于后续接口交易
调用方式	实时接口
调用流程	--
应用场景	代理商需要为名下商户提交交易时

2 请求地址

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

Method： POST

{
  "authorizeCode": "e10adc3949ba59abbe56e057f20f883e"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
授权码	authorizeCode	string(32)	M	授权码

{
  "accessToken": "7c4a8d09ca3762af61e59520943dc26494"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
授权token	accessToken	string(32)	M	授权 Token(目前 Token 永久有效)

5.3 收款

5.3.1 VA开户申请

1 功能描述

交易代码	TP1017
功能名称	VA开户申请
功能描述	商户发起VA开户申请，等待OTT审核后，商户可通过VA查询接口查询具体VA账户信息
调用方式	异步接口
调用流程	--
应用场景	商户发起VA开户申请

2 请求地址

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

Method： POST

 {
  "acctSimpleName": "test001",
  "applyCode": "SHOPEE_IN",
  "area": "ID",
  "callbackUrl": "https://ottp",
  "collectName": "",
  "collectType": "PayPal",
  "currency": "IDR",
  "isSameName": "N",
  "merOrderNo": "LNQ1692771393185",
  "parentCode": "S",
  "shopName": "31312",
  "shopUrl": "https://test001",
  "webSiteUrl": "https://test001"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
订单号	merOrderNo	string(32)	M	商户唯一订单号
申请大类	parentCode	string(1)	M	申请大类，暂时只支持 S:平台电商 D:独立站电商 T:线下一般货贸 F:服务贸易
申请子类	applyCode	string(64)	M	申请子类,填写业务子英文名详见6.1.13申请子类字段
收款国家/地区	area	string(2)	M	收款国家/地区标准2字代码
收款币种	currency	string(3)	M	收款币种，3位标准货币代码
账户简称	acctSimpleName	string(128)	M	账户简称
银行类	bankType	string(3)	O	银行类，填写银行类枚举值，仅线下一般货贸、服务贸易选填详见6.1.14bankType 银行类
店铺名称	shopName	string(128)	M	店铺名称
店铺链接	shopUrl	string(350)	O	店铺链接，平台电商、独立站电商必填
收单方式	collectType	string(12)	O	收单方式，枚举值：PayPal,stripe,other 仅独立站中自建站必填
收单方式名称	collectName	string(127)	O	收单方式名称，collectType为 other时填写
销售地址	webSiteUrl	string(350)	O	销售地址，线下一般货贸、服务贸易填写，与业务说明文件必填其一，可全填
是否同名	isSameName	string(1)	M	是否同名 Y:是 N:否
回调URL	callbackUrl	string(255)	M	回调URL
业务说明文件	busDesDocument	Array	O	多个附件文件地址数组，线下一般货贸、服务贸易填写，与销售地址必填其一，可全填
店铺持有证明	storeHoldCertify	Array	O	多个附件文件地址数组，电商、独立站提交
其他附件	otherPath	string(255)	O	其他附件其他补充附件，多个附件以,相隔
附言	postscript	string(255)	O	附言其他补充说明文字
账户持有人ID	holderId	string(64)	O	账户持有人ID ，不传默认以企业主体开通VA

具体申请条件详见6.1.15申请条件明细

{
  "bizFlow": "80823082314163300199",
  "status": "ACCEPT"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
业务流水号	bizFlow	string(32)	M	OTT侧唯一业务订单号
结果状态	status	string(6)	M	结果状态 ACCEPT:接收成功 FAIL：失败

5.3.2 VA开户查询

1 功能描述


交易代码	TP3012
功能名称	VA开户查询接口
功能描述	VA开户查询接口，提交VA申请后，通过此接口查询账户具体信息
调用方式	实时接口
调用流程	--
应用场景	VA开户查询接口

2 请求地址

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

Method： POST

{
  "bizFlow": "80823082314163300199"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
查询起始时间	startTime	Long(13)	O	Unix13位时间戳，查询开始时间，闭区间
查询结束时间	endTime	Long(13)	O	Unxi13位时间戳，查询结束时间，闭区间
OTT侧业务订单号	bizFlow	String(32)	O	VA开户时返回的订单号
商户订单号	merOrderNo	String(32)	O	商户订单号

{
  "list": [
    {
      "bizFlow": "80823082314163300199",
      "merOrderNo": "LNQ1692771393185",
      "vaInfos": [
        {
          "accountName": "XDT-GUANGZHOU HELIBAO PAYMENT CO LTD",
          "accountNo": "8808999911436641",
          "area": "ID",
          "bankAddress": "Wisma BNI, Jakarta",
          "bankCode": "016",
          "bankName": "Bank Negara Indonesia（BNI）",
          "branchCode": "478",
          "codeName": "Bank Code",
          "createTime": 1692771393951,
          "currency": "IDR",
          "parentCode": "S",
          "remark": "",
          "status": "ON",
          "swiftCode": "0090081",
          "updateTime": 1692771615635
        }
      ]
    }
  ]
}

4 响应字段

名称	Json标签	类型	属性	取值说明
商户订单号	merOrderNo	String(32)	M	商户订单号
OTT侧业务订单号	bizFlow	String(32)	M	VA开户时返回的订单号
VA详细信息	vaInfos	List	M	VA详细信息

VaInfo 的字段

名称	Json标签	类型	属性	取值说明
VA账户名称	accountName	string(255)	O	VA账户名称
VA账户号	accountNo	string(64)	O	VA账户号
SwiftCode	swiftCode	string(11)	O	银行的SwiftCode
银行名称	bankName	string(128)	O	银行名称
银行地址	bankAddress	string(255)	O	银行地址
国家/地区	area	string(64)	O	国家/地区
银行Code	bankCode	string(12)	O	银行Code
分行号	branchCode	string(12)	O	分行号
支持币种	currency	string(255)	O	支持币种，多币种之间按照
VA账户状态	status	string(8)	M	VA账户状态, ON:启用，OFF：禁用/拒绝 OPENING：开户中
备注	remark	string(8)	O	当为OFF时，会展示具体禁用/拒绝原因
申请时间	createTime	long	M	VA开户的申请时间
修改时间	updateTime	long	M	VA开户的修改时间

5.3.3 贸易收款到账通知

1 功能描述

交易代码	TP2007
功能名称	贸易收款到账通知
功能描述	贸易收款到账通知
调用方式	通知接口
调用流程	--
应用场景	在商户的VA子账户收款收到后，OTTPAYHK会向商户发送贸易收款资金到账的通知

2 请求地址

Url： 【待补充】callbackUrl

Method： POST

{
  "actualReceiveAmount": 1000,
  "availableFlag": "0",
  "feeAmount": 5,
  "feeCurrency": "USD",
  "flowNo": "62323082314263700034",
  "receiveAmount": 1000,
  "receiveCurrency": "IDR",
  "receiveTime": "1692772093",
  "receiveType": "S",
  "senderAccount": "",
  "senderName": "20230823002.ltd",
  "tradeComments": "",
  "vaAccount": "8808999911436641"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
到账流水号	flowNo	string(32)	M	贸易收款到账唯一流水号
到账金额	receiveAmount	decimal(18,2)	M	VA到账金额
到账币种	receiveCurrency	string(3)	M	VA到账币种
入账VA账户号	vaAccount	string(16)	M	入账的VA账户号
付款方名称	senderName	string(64)	O	付款方名称
付款方账号	senderAccount	string(32)	O	付款方账号
入账时间	receiveTime	string(10)	M	入账时间，10位unix时间戳
手续费金额	feeAmount	decimal(18,2)	O	手续费金额
手续费币种	feeCurrency	string(3)	O	手续费币种
实际入账金额	actualReceiveAmount	decimal(18,2)	M	实际入账金额
金额是否可用	availableFlag	string(1)	M	金额是否可用 0:不可用 1:可用
交易类型	receiveType	string(1)	M	交易类型 S:平台电商 D:独立站电商 T:线下一般货贸 F:服务贸易
汇款附言	tradeComments	string(1024)	O	汇款附言

5.3.4 收款VA入账查询接口

1 功能描述


交易代码	TP3015
功能名称	收款VA入账查询接口
功能描述	收款VA入账查询接口
调用方式	实时接口
调用流程	--
应用场景	可以查询VA账户具体的到账流水

2 请求地址

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

Method： POST

{
  "flowNo": "62323082314263700034"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
查询起始时间	startTime	Long(13)	O	Unix13位时间戳，查询开始时间，闭区间
查询结束时间	endTime	Long(13)	O	Unxi13位时间戳，查询结束时间，闭区间
VA入账订单号	flowNo	string(32) O	VA入账订单号

{
  "list": [
    {
      "actualReceiveAmount": 1000,
      "availableFlag": "0",
      "feeAmount": 5,
      "feeCurrency": "USD",
      "flowNo": "62323082314263700034",
      "receiveAmount": 1000,
      "receiveCurrency": "IDR",
      "receiveTime": "1692772093",
      "receiveType": "S",
      "senderAccount": "",
      "senderName": "20230823002.ltd",
      "tradeComments": "",
      "vaAccount": "8808999911436641"
    }
  ]
}

4 响应字段

名称	Json标签	类型	属性	取值说明
交易流水号	flowNo	string(32)	M	贸易收款到账唯一流水号
到账金额	receiveAmount	decimal(18,2)	M	VA到账金额
到账币种	receiveCurrency	string(3)	M	VA到账币种
入账VA账户号	vaAccount	string(16)	M	入账的VA账户号
付款方名称	senderName	string(64)	O	付款方名称
付款方账号	senderAccount	string(32)	O	付款方账号
入账时间	receiveTime	string(10)	M	入账时间，10位unix时间戳
手续费金额	feeAmount	decimal(18,2)	O	手续费金额
手续费币种	feeCurrency	string(3)	O	手续费币种
实际入账金额	actualReceiveAmount	decimal(18,2)	M	实际入账金额
金额是否可用	availableFlag	string(1)	M	金额是否可用 0:不可用 1:可用
交易类型	receiveType	string(1)	M	交易类型 S:平台电商 D:独立站电商 T:线下一般货贸 F:服务贸易
汇款附言	tradeComments	string(1024)	O	汇款附言

5.3.5 贸易订单申请

1 功能描述

交易代码	TP1012
功能名称	商户创建贸易的订单合同
功能描述	收集订单信息
调用方式	实时接口
调用流程	商户发送申请，ottpay返回合同订单号
应用场景	商户收集订单信息以及合规材料，提供商户新建贸易订单，并提供合同号

2 请求地址

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

Method： POST

 {
  "amount": 8000,
  "buyerArea": "HK",
  "buyerName": "COMPANY LIMITED",
  "callbackUrl": "http://www.baidu.com",
  "currency": "USD",
  "goodsList": [
    {
      "orderName": "goodsName",
      "orderNum": "500"
    }
  ],
  "logCompany": "",
  "logNo": "",
  "logStatus": "0",
  "merOrderNo": "LNQ1692772694542",
  "serviceTrade": {
},
  "tradeType": "00",
  "transcationCert": [
    "uploadFile/test.pdf"
  ],
  "transcationDate": "2023-08-22"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
回调接口地址	callbackUrl	string(60)	M	用来通知订单状态
商户唯一订单号	merOrderNo	string(32)	M	商户唯一订单号
订单币种	currency	string(3)	M	订单币种
订单总金额	amount	Decimal(18,2)	M	订单总金额
贸易类型	tradeType	string(2)	M	贸易类型默认：00-货物贸易 01-服务贸易
采购方名称	buyerName	string(64)	M	采购方名称
采购方所属地区	buyerArea	string(64)	M	采购方所属地区
物品信息	goodsList	`List<goodsList>`	M	物品信息物品数量不超过10个
交易日期	transcationDate	string(10)	M	交易日期格式：yyyy-MM-dd
交易凭证	transcationCert	`Array`	M	多个凭证文件地址数组 (文件大小不超过20M)
物流状态	logStatus	string(1)	O	当贸易类型为00-货物贸易时必填 0-未发货 1-已发货如果是已发货logNo、logCompany、annexUrl三个字段必填
物流单号	logNo	string(64)	O	物流单号
物流公司名称	logCompany	string(128)	O	物流公司名称
附件	annexUrl	`Array`	O	多个附件文件地址数组 (文件大小不超过20M)
服务贸易信息	serviceTrade	`Object`	O	当贸易类型为01-服务贸易时必填

goodsList

名称	Json标签	类型	属性	取值说明
交易物品名称	orderName	string(64)	M	交易物品名称
交易物品数量	orderNum	string(10)	M	交易物品数量

serviceTrade

名称	Json标签	类型	属性	取值说明
服务贸易状态	serviceCondition	string(1)	O	服务贸易完成状态 0-未完成 1-已完成
证明文件	proveUrl	`Array`	O	当服务贸易状态为1 此项必填
预计完成时间	conditionDate	string(10)	O	当服务贸易状态为0 此项必填格式 yyyy-MM-dd

{
  "contractNo": "63733082314292600682"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
贸易订单号	contractNo	string(32)	M	贸易订单号（唯一）

5.3.6 贸易订单申请结果通知

1 功能描述

交易代码	TP2008
功能名称	回传贸易订单结果状态通知
功能描述	运营审核后通知商户订单申请结果
调用方式	通知接口
调用流程	--
应用场景	[5.1.13 贸易订单申请]发起成功，根据回调Url进行回调通知最终结果。

2 请求地址

Url： [5.3.5 贸易订单申请]中的 callbackUrl

Method： POST

{
  "contractNo": "63823082314103100198",
  "merOrderNo": "LNQ1692772694542",
  "message": "成功",
  "status": "SUCC"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
贸易订单编号	contractNo	string(32)	M	贸易订单编号 (唯一)
商户订单号	merOrderNo	string(32)	M	商户订单号(唯一)
状态	status	string(8)	M	'ACCEPT-处理中 SUCC-成功 FAIL-失败'
结果描述	message	string(64)	M	交易结果描述

5.3.7 贸易订单申请信息查询

1 功能描述


交易代码	TP3013
功能名称	贸易合同结果信息查询
功能描述	提供商户查询贸易合同创建状态
调用方式	实时接口
调用流程	--
应用场景	商户需要查询订单合同的状态

2 请求地址

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

Method： POST

{
  "endTime": "1692806399",
  "startTime": "1692720000"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
查询起始时间	startTime	Long(13)	O	Unix10位时间戳，查询开始时间，闭区间
查询结束时间	endTime	Long(13)	O	Unxi10位时间戳，查询结束时间，闭区间
贸易合同号	contractNo	string(32)	O	[5.1.13 贸易订单申请]返回贸易合同号
订单号	merOrderNo	string(32)	O	商户提供的订单号

{
  "contractList": [
    {
      "amount": 100,
      "annexUrl": [
        "app/test.png"
      ],
      "buyerArea": "HK",
      "buyerName": "COMPANY LIMITED",
      "callbackUrl": "https://www.baidu.com",
      "contractNo": "63823082314103100198",
      "currency": "USD",
      "goodList": [
        {
          "orderName": "goodsName",
          "orderNum": "500"
        }
      ],
      "logCompany": "",
      "logNo": "",
      "logStatus": "0",
      "merOrderNo": "LNQ1692772694542",
      "message": "成功",
      "serviceTrade": {
        "proveUrl": [
        ]
      },
      "status": "SUCC",
      "tradeType": "00",
      "transcationCert": [
        "app/test.pdf"
      ],
      "transcationDate": "2023-08-22"
    }
  ]
}

4 响应字段

名称	Json标签	类型	属性	取值说明
贸易订单	contractList	`List<contractList>`	M	贸易订单集合

contractList

名称	Json标签	类型	属性	取值说明
商户唯一订单号	merOrderNo	string(32)	M	商户唯一订单号
订单币种	currency	string(3)	M	订单币种
订单总金额	amount	Decimal(18,2)	M	订单总金额
贸易类型	tradeType	string(2)	M	贸易类型默认：00-货物贸易
采购方名称	buyerName	string(64)	M	采购方名称
采购方所属地区	buyerArea	string(64)	M	采购方所属地区
物品信息	goodsList	`List<goodsList>`	M	物品信息物品数不超过10个
交易日期	transcationDate	string(10)	M	交易日期格式：yyyy-MM-dd
交易凭证	transcationCert	`Array`	M	多个凭证文件地址数组 (文件大小不超过20M)
物流状态	logStatus	string(1)	O	0-未发货 1-已发货
物流单号	logNo	string(64)	O	物流单号
物流公司名称	logCompany	string(64)	O	物流公司名称
物流附件	annexUrl	`Array`	O	物流附件 (文件大小不超过20M)
服务贸易信息	serviceTrade	`Object`	O	服务贸易信息
贸易订单号	contractNo	string(32)	M	贸易订单号（唯一）
贸易订单状态	status	string(8)	M	贸易订单状态 ACCEPT-处理中 SUCC-成功 FAIL-失败
查询结果描述	message	string(128)	M	查询结果描述

serviceTrade

名称	Json标签	类型	属性	取值说明
服务贸易状态	serviceCondition	string(1)	O	服务贸易完成状态 0-未完成 1-已完成
证明文件	proveUrl	`Array`	O	证明文件路径 serviceCondition 为0时必填
预计完成时间	conditionDate	string(10)	O	serviceCondition 为1时必填格式"yyyy-MM-dd"

5.3.8 收款流水和贸易订单关联

1 功能描述


交易代码	TP1013
功能名称	收款流水和贸易订单关联
功能描述	收款流水和贸易订单关联
调用方式	实时接口
调用流程	--
应用场景	商户的贸易收款订单被审核通过后，将收款流水和贸易订单做关联

2 请求地址

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

Method： POST

{
  "contactNo": "63291062211570000002",
  "flowNo": "62291060316483300005",
  "callbackUrl": "https://www.baidu.com"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
贸易订单编码	contactNo	string(32)	M	贸易订单编码，tp2008返回
收款流水编码	flowNo	string(32)	M	收款流水编码，tp3015返回
入账通知地址	callbackUrl	string(255)	M	贸易收款入账成功后的通知地址

{
  "bizFlow":"1143915555060752384"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
业务流水号	bizFlow	string(32)	M	OTT侧唯一业务订单号

5.3.9 收款流水和贸易订单关联结果通知

1 功能描述

交易代码	TP2009
功能名称	收款流水和贸易订单关联结果通知
功能描述	收款流水和贸易订单关联后，给商户发的通知
调用方式	通知接口
调用流程	--
应用场景	[5.3.8 收款流水和贸易订单关联]发起成功且交易处理完毕后，将根据[5.3.8 收款流水和贸易订单关联]参数内的回调Url进行回调通知最终结果。

2 请求地址

Url： [5.3.8 收款流水和贸易订单关联]中的 callbackUrl

Method： POST

{
  "amount": 43444.8,
  "approveTime": 1692774260350,
  "bizFlow": "1143915555060752384",
  "contactNo": "63291062211570000002",
  "flowNo": "62291060316483300005",
  "currency": "CNY",
  "feeAmt": 130.33,
  "feeCurty": "CNY",
  "merchantNo": "004401100035",
  "message": "",
  "status": "02"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
贸易订单编码	contactNo	string(32)	M	贸易订单编码
收款流水编码	flowNo	string(32)	M	收款流水编码
入账币种	currency	string	M	入账币种，3位标准货币代码
入账金额	amount	decimal(18,2)	M	收款金额
手续费币种	feeCurty	String	M	手续费币种，3位标准货币代码
手续费金额	feeAmt	decimal(18,2)	M	OTT PAY收取手续费
入账时间	approveTime	bigInt(13)	M	入账时间戳(毫秒)
状态	status	string(2)	M	'02-通过 03-驳回'
结果描述	message	string(255)	M	交易结果描述

5.3.10 收款流水和贸易订单关联查询

1 功能描述


交易代码	TP3014
功能名称	收款流水和贸易订单关联查询接口
功能描述	提交收款流水和贸易订单关联申请后，通过此接口查询贸易收款是否入账
调用方式	实时接口
调用流程	--
应用场景	提交收款流水和贸易订单关联申请后（TP1013），通过此接口查询贸易收款是否入账

2 请求地址

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

Method： POST

{
  "contactNo": "63291062211570000002",
  "flowNo": "62291060316483300005"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
查询起始时间	startTime	Long(13)	O	Unix13位时间戳，查询开始时间，闭区间
查询结束时间	endTime	Long(13)	O	Unxi13位时间戳，查询结束时间，闭区间
贸易订单编码	contactNo	string(32)	O	贸易订单编码，tp2008返回
收款流水编码	flowNo	string(32)	O	收款流水编码，tp3015返回
业务流水号	bizFlow	string(32)	O	OTT侧唯一业务订单号，tp1013返回

{
  "relateList": [
    {
      "amount": 11197.08,
      "bizFlow": "1143915555060752384",
      "callbackUrl": "https://www.baidu.com",
      "contactNo": "63291062211570000002",
      "currency": "USD",
      "feeAmt": 0,
      "feeCurty": "USD",
      "flowNo": "62291060316483300005",
      "id": 5593,
      "merchantNo": "004401100035",
      "status": "01"
    }
  ]
}

4 响应字段

名称	Json标签	类型	属性	取值说明
信息集合	relateList	`List<ConfirmRelatetionReq>`	M	--

ConfirmRelatetionReq 字段：

名称	Json标签	类型	属性	取值说明
贸易订单编码	contactNo	string(32)	M	贸易订单编码
收款流水编码	flowNo	string(32)	M	收款流水编码
入账币种	currency	string	M	入账币种，3位标准货币代码
入账金额	amount	decimal(18,2)	M	收款金额
手续费币种	feeCurty	String	M	手续费币种，3位标准货币代码
手续费金额	feeAmt	decimal(18,2)	O	OTT PAY收取手续费
入账时间	approveTime	bigInt(13)	M	入账时间戳(毫秒)
状态	status	string(2)	M	'01-审核中 02-通过 03-驳回'
结果描述	message	string(64)	M	交易结果描述

5.3.11 电商订单申请

1 功能描述

交易代码	TP1016
功能名称	电商订单申请
功能描述	上传商户的电商类的收款的还原材料
调用方式	实时接口
调用流程	商户发送申请，ottpay返回成功还是失败
应用场景	商户收款后上传电商类的订单信息以及合规材料

2 请求地址

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

Method： POST

 {
  "orderList": [
    {
      "amount": 11000,
      "commodity": "时尚首饰",
      "currency": "USD",
      "dateTime": "2023-07-22",
      "logisticsName": "FedEx",
      "logisticsNo": "20230823001",
      "orderNo": "20230823001",
      "platform": "阿里巴巴",
      "purpose": "GOODSTRADE",
      "quantity": 30,
      "shopUrl": "https://www.baidu.com"
    }
  ],
  "transType": "S"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
还原材料集合	orderList	`List<orderList>`	M	还原材料集合，1到500条数据内
交易类型	transType	string(1)	M	交易类型，暂时只支持 S:平台电商 D:独立站电商

orderList

名称	Json标签	类型	属性	取值说明
订单号	orderNo	string(32)	M	订单号
金额	amount	decimal(18,2)	M	金额，保留两位小数，大于0小于300000
币种	currency	string(3)	M	币种，3位标准货币代码
订单日期	dateTime	string(10)	M	订单日期，格式为yyyy-MM-dd
商品名称	commodity	string(512)	M	商品名称
商品数量	quantity	int	M	商品数量
物流公司名称	logisticsName	string(255)	M	物流公司名称
物流单号	logisticsNo	string(255)	M	物流单号
平台名称	platform	string(100)	M	平台名称
店铺Url	shopUrl	string(128)	M	店铺Url

{
  "code": "success"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
返回接收状态	code	string(32)	M	返回接收状态

5.3.12 电商额度查询

1 功能描述

交易代码	TP3016
功能名称	电商额度查询
功能描述	查询商户当前可用的电商额度查询
调用方式	实时接口
调用流程	商户发送申请，ottpay返回电商额度
应用场景	商户收款后或还原材料上传后，查询电商额度

2 请求地址

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

Method： POST

 {
  "transType": "D"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
交易类型	transType	string(1)	M	交易类型，暂时只支持 S:平台电商 D:独立站电商

{
  "list": [
    {
      "availableAmount": 1000.0,
      "currency": "CNY"
    }
  ]
}

4 响应字段

名称	Json标签	类型	属性	取值说明
返回额度列表	list	`List<list>`	M	返回额度列表

list

名称	Json标签	类型	属性	取值说明
可用余额	availableAmount	decimal(18,2)	M	可用余额
币种	currency	string(3)	M	币种，3位标准货币代码

5.3.13 VA开户结果通知

1 功能描述

交易代码	TP2012
功能名称	VA开户结果通知
功能描述	商户发起VA开户申请OTT审核后，通知商户VA开户的结果
调用方式	通知接口
调用流程	--
应用场景	[5.3.1 VA开户申请]发起成功且审核完毕后，将根据[5.3.1 VA开户申请]参数内的回调Url进行回调通知最终结果。

2 请求地址

Url： [5.3.1 VA开户申请]中的 callbackUrl

Method： POST

{
  "accountName": "XDT-GUANGZHOU HELIBAO PAYMENT CO LTD",
  "accountNo": "8808999911436641",
  "area": "ID",
  "bankAddress": "Wisma BNI, Jakarta",
  "bankCode": "016",
  "bankName": "Bank Negara Indonesia（BNI）",
  "bizFlow": "80823082314163300199",
  "branchCode": "478",
  "codeName": "Bank Code",
  "codeValue": "0090081",
  "currency": "IDR",
  "merOrderNo": "LNQ1692771393185",
  "parentCode": "S",
  "remark": "",
  "status": "ON"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
订单号	merOrderNo	string(32)	O	商户唯一订单号
流水号	bizFlow	string(32)	O	流水号
VA账户名称	accountName	string(255)	O	VA账户名称
VA账户号	accountNo	string(64)	O	VA账户号
code信息	codeValue	string(16)	O	银行的Code
code名称	codeName	string(64)	O	ACH Routing Number，Bank Code，Sort Code，SWIFT CODE
银行名称	bankName	string(128)	O	银行名称
银行地址	bankAddress	string(255)	O	银行地址
国家/地区	area	string(64)	O	国家/地区
银行Code	bankCode	string(12)	O	银行Code
分行号	branchCode	string(12)	O	分行号
支持币种	currency	string(255)	O	支持币种，多币种之间按照
VA账户状态	status	string(8)	M	VA账户状态, ON:启用，OFF：禁用/拒绝 OPENING：开户中
备注	remark	string(8)	O	当为OFF时，会展示具体禁用/拒绝原因

5.3.14 新增账户持有人

1 功能描述


交易代码	TP1024
功能名称	新增账户持有人
功能描述	新增账户持有人，为申请VA的持有人做准备。
调用方式	实时接口
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "holderType": "00",
  "holderCertificateType": "01",
  "callbackUrl": "https://www.baidu.com",
  "holderArea": "CN",
  "holderCertificate": [
    "uploadFile/dshjy.png"
  ],
  "holderCertificateNumber": "342211199101011111",
  "holderIdentity": "04",
  "holderName": "持有人",
  "holderNameEn": "chiyouren",
  "holderProveDocument": [
    "uploadFile/dshjy.png"
  ],
  "holderRealAddress": "上海外滩",
  "holderRegistratDate": "1991-07-08",
  "holderSex": "M",
  "postalCode": "10080"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
持有人类型	holderType	String(2)	M	持有人类型：00-个人，01-企业
持有人身份	holderIdentity	String(3)	M	持有人身份参数详见字段说明
其他持有人身份描述	otherTypeName	String(255)	C	其他持有人身份描述当持有人身份为其他时必传
身份证明文件	holderProveDocument	`List<String>`	M	身份证明文件
持有人身份文件	holderCertificate	`List<String>`	M	持有人身份文件
持有人英文名称	holderNameEn	String(255)	M	持有人英文名称
持有人中文名称	holderName	String(255)	C	持有人中文名称个人-注册地区为CN及HK时，必填企业-注册地区为CN时，必填
持有人所在地区	holderArea	String(2)	M	持有人所在国家/地区，传二字码
持有人证件类型	holderCertificateType	String(3)	M	持有人证件类型参数详见字段说明
持有人证件号	holderCertificateNumber	String(32)	M	持有人证件号
持有人地址	holderRealAddress	String(128)	M	持有人注册地址/持有人真实营业地址
持有人注册出生日期	holderRegistratDate	String(16)	M	持有人注册出生日期格式 yyyy-MM-dd
邮编	postalCode	String(32)	M	邮编
持有人性别	holderSex	String(2)	C	持有人性别 M:男 F:女个人必填
最终受益人信息	finalBeneficialReqs	`List<FinalBeneficialReq>`	C	最终受益人信息企业必填，最多5个
扩展字段	extensionField	`List<Object>`	O	扩展字段(其余扩展字段存放)
回调URL	callbackUrl	String(255)	M	回调URL

FinalBeneficialReq

名称	Json标签	类型	属性	取值说明
最终受益人名称	beneficialName	string(255)	M	最终受益人名称
最终受益人地区	beneficialArea	string(2)	M	最终受益人国家/地区
最终受益人证件类型	beneficialCertificateType	string(3)	M	最终受益人证件类型参数详见字段说明
最终受益人证件号码	beneficialCertificateNumber	string(32)	M	最终受益人证件号码
最终受益人出生日期	beneficialDate	string(16)	M	最终受益人出生日期格式 yyyy-MM-dd
最终受益人性别	beneficialSex	String(2)	M	最终受益人性别
备注	remark	string(255)	M	备注

{
  "code": "S00000",
  "msg": "请求成功",
  "data": {
    "holderId": "7be43506-35b5-4c53-b0ec-687526cfe45e",
    "status": "10"
  },
  "succ": true
}

4 响应字段

名称	Json标签	类型	属性	取值说明
账户持有人ID	holderId	String(64)	M	账户持有人ID 持有人唯一ID
账户持有人状态	status	String(2)	M	账户持有人状态参数详见字段说明

5.3.15 修改账户持有人

1 功能描述


交易代码	TP1025
功能名称	修改账户持有人
功能描述	修改账户持有人，为申请VA的持有人做准备。仅限于持有人状态为拒绝的客户可传
调用方式	实时接口
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "holderId": "7be43506-35b5-4c53-b0ec-687526cfe45e",
  "holderType": "00",
  "holderCertificateType": "01",
  "callbackUrl": "https://www.baidu.com",
  "holderArea": "CN",
  "holderCertificate": [
    "uploadFile/dshjy.png"
  ],
  "holderCertificateNumber": "342211199101011111",
  "holderIdentity": "04",
  "holderName": "持有人",
  "holderNameEn": "chiyouren",
  "holderProveDocument": [
    "uploadFile/dshjy.png"
  ],
  "holderRealAddress": "上海外滩",
  "holderRegistratDate": "1991-07-08",
  "holderSex": "M",
  "postalCode": "10080"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
账户持有人ID	holderId	String(64)	M	账户持有人ID 持有人唯一ID
持有人类型	holderType	String(2)	M	持有人类型：00-个人，01-企业
持有人身份	holderIdentity	String(3)	M	持有人身份参数详见字段说明
其他持有人身份描述	otherTypeName	String(255)	C	其他持有人身份描述当持有人身份为其他时必传
身份证明文件	holderProveDocument	`List<String>`	M	身份证明文件
持有人身份文件	holderCertificate	`List<String>`	M	持有人身份文件
持有人英文名称	holderNameEn	String(255)	M	持有人英文名称
持有人中文名称	holderName	String(255)	C	持有人中文名称个人-注册地区为CN及HK时，必填企业-注册地区为CN时，必填
持有人所在地区	holderArea	String(2)	M	持有人所在国家/地区，传二字码
持有人证件类型	holderCertificateType	String(3)	M	持有人证件类型参数详见字段说明
持有人证件号	holderCertificateNumber	String(32)	M	持有人证件号
持有人地址	holderRealAddress	String(128)	M	持有人注册地址/持有人真实营业地址
持有人注册出生日期	holderRegistratDate	String(16)	M	持有人注册出生日期格式 yyyy-MM-dd
邮编	postalCode	String(32)	M	邮编
持有人性别	holderSex	String(2)	C	持有人性别 M:男 F:女个人必填
最终受益人信息	finalBeneficialReqs	`List<FinalBeneficialReq>`	C	最终受益人信息企业必填，最多5个
扩展字段	extensionField	`List<Object>`	O	扩展字段(其余扩展字段存放)
回调URL	callbackUrl	String(255)	M	回调URL

FinalBeneficialReq

名称	Json标签	类型	属性	取值说明
最终受益人名称	beneficialName	string(255)	M	最终受益人名称
最终受益人地区	beneficialArea	string(2)	M	最终受益人国家/地区
最终受益人证件类型	beneficialCertificateType	string(3)	M	最终受益人证件类型参数详见字段说明
最终受益人证件号码	beneficialCertificateNumber	string(32)	M	最终受益人证件号码
最终受益人出生日期	beneficialDate	string(16)	M	最终受益人出生日期格式 yyyy-MM-dd
最终受益人性别	beneficialSex	String(2)	M	最终受益人性别
备注	remark	string(255)	M	备注

{
  "code": "S00000",
  "msg": "请求成功",
  "data": {
    "holderId": "7be43506-35b5-4c53-b0ec-687526cfe45e",
    "status": "10"
  },
  "succ": true
}

4 响应字段

名称	Json标签	类型	属性	取值说明
账户持有人ID	holderId	String(64)	M	账户持有人ID 持有人唯一ID
账户持有人状态	status	String(2)	M	账户持有人状态参数详见字段说明

5.3.16 账户持有人补充信息

1 功能描述


交易代码	TP1026
功能名称	账户持有人补充信息
功能描述	账户持有人补充信息，为申请VA的持有人做准备。仅限于持有人状态为待补充信息和补充审核拒绝的客户可传，字段仅可传查询接口获取的待补充字段
调用方式	实时接口
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "holderId": "51f29956-e603-43ff-ab59-2e681be2ef93",
  "holderType": "01",
  "holderIdentity": "11",
  "holderProveDocument": [
    "uploadFile/dszj.jpg"
  ],
  "holderNameEn": "qiye",
  "holderName": "企业",
  "otherTypeName": "代理",
  "holderArea": "CN",
  "holderCertificateType": "03",
  "holderCertificateNumber": "9023546645481",
  "holderRealAddress": "上海",
  "holderRegistratDate": "2022-02-27",
  "callbackUrl": "http://."
}

3 请求字段

名称	Json标签	类型	属性	取值说明
账户持有人ID	holderId	String(64)	M	账户持有人ID 持有人唯一ID
持有人类型	holderType	String(2)	C	持有人类型：00-个人，01-企业
持有人身份	holderIdentity	String(3)	C	持有人身份参数详见字段说明
其他持有人身份描述	otherTypeName	String(255)	C	其他持有人身份描述当持有人身份为其他时必传
身份证明文件	holderProveDocument	`List<String>`	C	身份证明文件
持有人身份文件	holderCertificate	`List<String>`	C	持有人身份文件
持有人英文名称	holderNameEn	String(255)	C	持有人英文名称
持有人中文名称	holderName	String(255)	C	持有人中文名称个人-注册地区为CN及HK时，必填企业-注册地区为CN时，必填
持有人所在地区	holderArea	String(2)	C	持有人所在国家/地区，传二字码
持有人证件类型	holderCertificateType	String(3)	C	持有人证件类型参数详见字段说明
持有人证件号	holderCertificateNumber	String(32)	C	持有人证件号
持有人地址	holderRealAddress	String(128)	C	持有人注册地址/持有人真实营业地址
持有人注册出生日期	holderRegistratDate	String(16)	C	持有人注册出生日期格式 yyyy-MM-dd
邮编	postalCode	String(32)	C	邮编
持有人性别	holderSex	String(2)	C	持有人性别 M:男 F:女个人必填
回调URL	callbackUrl	String(255)	C	回调URL

{
  "code": "S00000",
  "msg": "请求成功",
  "data": {
    "holderId": "51f29956-e603-43ff-ab59-2e681be2ef93",
    "status": "10"
  },
  "succ": true
}

4 响应字段

名称	Json标签	类型	属性	取值说明
账户持有人ID	holderId	String(64)	M	账户持有人ID 持有人唯一ID
账户持有人状态	status	String(2)	M	账户持有人状态参数详见字段说明

5.3.17 账户持有人查询

1 功能描述


交易代码	TP3018
功能名称	账户持有人查询
功能描述	查询账户持有人信息
调用方式	实时接口
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "holderId": "7be43506-35b5-4c53-b0ec-687526cfe45e"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
账户持有人ID	holderId	String(64)	O	账户持有人ID 持有人唯一ID
持有人英文名称	holderNameEn	String(255)	O	持有人英文名称
持有人证件号	holderCertificateNumber	String(32)	O	持有人证件号
查询起始时间	startTime	Long(13)	O	Unix13位时间戳，查询开始时间，闭区间
查询结束时间	endTime	Long(13)	O	Unix13位时间戳，查询结束时间，闭区间
页数	pageNo	Int	O	分页页数，默认1
页显示数	pageSize	Int	O	分页页显示数，默认10，最大100

{
  "list": [
    {
      "holderArea": "CN",
      "holderCertificateNumber": "342211199101011111",
      "holderCertificateType": "01",
      "holderId": "7be43506-35b5-4c53-b0ec-687526cfe45e",
      "holderIdentity": "04",
      "holderNameEn": "chiyouren",
      "holderRegistratDate": "1991-07-08",
      "holderType": "00",
      "id": 21174,
      "resMessage": "",
      "status": "10"
    }
  ],
  "pageNum": 1,
  "pageSize": 10,
  "pages": 1,
  "prePage": 0,
  "size": 1,
  "startRow": 1,
  "total": 1
}

4 响应字段

名称	Json标签	类型	属性	取值说明
账户持有人ID	holderId	String(64)	M	账户持有人ID 持有人唯一ID
持有人类型	holderType	String(2)	M	持有人类型：00-个人，01-企业
持有人身份	holderIdentity	String(3)	M	持有人身份参数详见字段说明
持有人英文名称	holderNameEn	String(255)	M	持有人英文名称
持有人所在地区	holderArea	String(2)	M	持有人所在国家/地区，传二字码
持有人证件类型	holderCertificateType	String(3)	M	持有人证件类型参数详见字段说明
持有人证件号	holderCertificateNumber	String(32)	M	持有人证件号
持有人注册出生日期	holderRegistratDate	String(16)	M	持有人注册出生日期格式 yyyy-MM-dd
账户持有人状态	status	String(2)	M	账户持有人状态参数详见字段说明
结果描述	resMessage	String(255)	O	审核结果描述
待补充字段	replenishField	`List<String>`	C	待补充字段(状态为待补充材料和待补充审核拒绝存在)

5.3.18 账户持有人审核结果通知

1 功能描述


交易代码	TP2013
功能名称	账户持有人审核结果通知
功能描述	账户持有人审核结果通知
调用方式	实时接口
调用流程	---
应用场景	在商户的账户持有人信息审核成功后，OTTPAYHK会向商户发送账户持有人审核结果通知

2 请求地址

Url： 【待补充】callbackUrl

Method： POST

{
  "holderArea": "CN",
  "holderCertificateNumber": "342211199101011111",
  "holderCertificateType": "01",
  "holderId": "7be43506-35b5-4c53-b0ec-687526cfe45e",
  "holderIdentity": "04",
  "holderNameEn": "chiyouren",
  "holderRegistratDate": "1991-07-08",
  "holderType": "00",
  "id": 0,
  "resMessage": "信息有误",
  "status": "20"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
账户持有人ID	holderId	String(64)	M	账户持有人ID 持有人唯一ID
持有人类型	holderType	String(2)	M	持有人类型：00-个人，01-企业
持有人身份	holderIdentity	String(3)	M	持有人身份参数详见字段说明
持有人英文名称	holderNameEn	String(255)	M	持有人英文名称
持有人所在地区	holderArea	String(2)	M	持有人所在国家/地区，传二字码
持有人证件类型	holderCertificateType	String(3)	M	持有人证件类型参数详见字段说明
持有人证件号	holderCertificateNumber	String(32)	M	持有人证件号
持有人注册出生日期	holderRegistratDate	String(16)	M	持有人注册出生日期格式 yyyy-MM-dd
账户持有人状态	status	String(2)	M	账户持有人状态参数详见字段说明
结果描述	resMessage	String(255)	O	审核结果描述

5.4 换汇

5.4.1 牌价查询

1 功能描述


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

2 请求地址

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

Method： POST

{
  "amount": "1",
  "buyCurrency": "HKD",
  "lockDirection": "SELL",
  "merOrderNo": "LNQ1692790975123",
  "sellCurrency": "USD"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
商户订单号	merOrderNo	String(32)	M	商户自定义的唯一订单号
卖出币种	sellCurrency	String(3)	O	卖出币种
买入币种	buyCurrency	String(3)	M	买入币种
锁定方向	lockDirection	String(4)	M	锁定卖出或买入币种;传SELL则锁定卖出币种的金额，传BUY则锁定买入币种的金额
锁定金额	amount	String(20)	M	指定的FX金额注：您申请的换汇金额等值不足100USD，可能导致换汇失败
锁汇类型	lockType	String(2)	O	选填字段：目前支持可选T0、T1,当不传时，即为实时换汇

{
  "buyAmount": "7.84",
  "buyCurrency": "HKD",
  "expireTime": 1692790988000,
  "merOrderNo": "LNQ1692790975123",
  "quoteId": 1143993799583002600,
  "rate": "7.8400000000",
  "sellAmount": "1",
  "sellCurrency": "USD"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
卖出币种	sellCurrency	String(3)	M	卖出币种
买入币种	buyCurrency	String(3)	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	商户传入的订单号
锁汇类型	lockType	String(2)	O	锁汇类型 T0、T1,当不传时，即为实时换汇

5.4.2 FX交易

1 功能描述


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

2 请求地址

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

Method： POST

{
  "callbackUrl": "https://www.baidu.com",
  "quoteId": 1143993799583002600
}

3 请求字段

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

{
  "bizFlow": "21823082319430400222",
  "buyAmount": "7.84",
  "buyCurrency": "HKD",
  "code": "S00001",
  "message": "Processing",
  "quoteId": 1143993799583002600,
  "rate": "7.8400000000",
  "sellAmount": "1.00",
  "sellCurrency": "USD"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
卖出币种	sellCurrency	String(3)	M	卖出币种
买入币种	buyCurrency	String(3)	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交易的唯一流水号
锁汇类型	lockType	String(2)	O	锁汇类型 T0、T1

5.4.3 换汇历史交易查询

1 功能描述

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

2 请求地址

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

Method： POST

3 请求字段

{
  "endTime": 1692806399000,
  "startTime": 1692720000000
}

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

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

{
  "list": [
    {
      "bizFlow": "21823082319430400222",
      "buyAmount": "7.84",
      "buyCurrency": "HKD",
      "code": "S00000",
      "message": "Success",
      "quoteId": 1143993799583002600,
      "rate": "7.8400000000",
      "sellAmount": "1.00",
      "sellCurrency": "USD"
    }
  ]
}

4 响应字段

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

ExchangeHistory 字段：

名称	Json标签	类型	属性	取值说明
卖出币种	sellCurrency	String(3)	M	卖出币种
买入币种	buyCurrency	String(3)	M	买入币种
汇率	rate	String(18)	M	汇率报价
卖出金额	sellAmount	String(20)	M	卖出金额
买入金额	buyAmount	String(20)	M	买入金额
报价ID	quoteId	Int	M	报价ID
结果码	code	String	M	Fx交易结果码 S00000-成功 S00001-处理中 S00002-待生效 S00003-已取消 S00004-已过期其余暂为失败
结果描述	message	String	M	交易结果描述
业务流水号	bizFlow	String(32)	M	对应唯一业务流水号

5.4.4 FX交易结果通知

1 功能描述


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

2 请求地址

Url： 5.4.2 Fx交易中的 callbackUrl

Method： POST

 {
  "bizFlow": "21823082319430400222",
  "buyAmount": "7.84",
  "buyCurrency": "HKD",
  "code": "S00000",
  "message": "Success",
  "quoteId": 1143993799583002600,
  "rate": "7.8400000000",
  "sellAmount": "1.00",
  "sellCurrency": "USD"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
卖出币种	sellCurrency	String(3)	M	卖出币种
买入币种	buyCurrency	String(3)	M	买入币种
汇率	rate	String(18)	M	汇率报价
卖出金额	sellAmount	String(20)	M	卖出金额
买入金额	buyAmount	String(20)	M	买入金额
报价ID	quoteId	Long	M	报价ID
结果码	code	String	M	Fx交易结果码 S00000-成功 S00001-处理中 S00002-待生效 S00003-已取消 S00004-已过期其余暂为失败
结果描述	message	String	M	交易结果描述
业务流水号	bizFlow	String(32)	M	业务流水号

5.4.5 查询支持换汇币种对

1 功能描述

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

2 请求地址

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

Method： POST

3 请求字段

无

4 响应字段

 {
  "list": [
    {
      "buyCurrency": "CHF",
      "sellCurrency": "NOK"
    },
    {
      "buyCurrency": "AUD",
      "sellCurrency": "CHF"
    }
  ]
}

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

CurrencyPair字段：

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

5.4.6 委托换汇提交申请

1 功能描述

交易代码	TP1027
功能名称	委托换汇申请提交
功能描述	指定委托汇率，交易申请提交
调用方式	实时接口
调用流程	--
应用场景	需要委托换汇，按照指定汇率进行交割的换汇场景

2 请求地址

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

Method： POST

3 请求字段

名称	Json标签	类型	属性	取值说明
卖出币种	sellCurrency	String(3)	M	卖出币种
买入币种	buyCurrency	String(3)	M	买入币种
委托汇率	entrustRate	String(18)	M	委托汇率
卖出金额	sellAmount	String(20)	M	卖出金额
买入金额	buyAmount	String(20)	M	买入金额
锁定方向	lockDirection	String(4)	M	锁定卖出或买入币种;传SELL则锁定卖出币种的金额，传BUY则锁定买入币种的金额
截止日期	deadLineDate	String(20)	M	截止日期：格式：yyyy-MM-dd
回调通知地址	callbackUrl	String(256)	M	回调通知地址

 {
     "callbackUrl": "http://www.baidu.com",
     "merOrderNo": "12345678116",
     "sellCurrency": "USD",
     "buyCurrency": "CNY",
     "lockDirection": "SELL",
     "sellAmount": "10",
     "buyAmount": "72",
     "entrustRate": "7.2",
     "deadLineDate": "2023-08-29"
 }

4 响应字段

名称	Json标签	类型	属性	取值说明
卖出币种	sellCurrency	String(3)	M	卖出币种
买入币种	buyCurrency	String(3)	M	买入币种
委托汇率	entrustRate	String(18)	M	委托汇率
卖出金额	sellAmount	String(20)	M	卖出金额
买入金额	buyAmount	String(20)	M	买入金额
结果码	code	String	M	交易结果码
结果描述	message	String	M	交易结果描述
业务流水号	bizFlow	String(32)	M	业务流水号
换汇类型	lockType	String(20)	M	换汇类型：委托换汇（ENTRUST_EXCHANGE）

{
    "sellCurrency": "USD",
    "buyCurrency": "CNY",
    "entrustRate": "7.2",
    "sellAmount": "10",
    "buyAmount": "72",
    "code": "S00001",
    "message": "Processing",
    "bizFlow": "21803082911294500002",
    "lockType": "ENTRUST_EXCHANGE"
}

5.4.7 委托换汇申请取消

1 功能描述

交易代码	TP1028
功能名称	委托换汇申请取消
功能描述	指定委托汇率，交易申请取消
调用方式	实时接口
调用流程	--
应用场景	委托换汇，按照指定汇率进行交割前的申请取消

2 请求地址

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

Method： POST

3 请求字段

名称	Json标签	类型	属性	取值说明
业务流水号	bizFlow	String(32)	M	业务流水号

{
    "bizFlow": "21733082910452000003"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
结果码	code	String	M	交易结果码
结果描述	message	String	M	交易结果描述
业务流水号	bizFlow	String(32)	M	业务流水号

{
    "code": "S00000",
    "message": "S00000",
    "bizFlow": "21733082910452000003"
}

5.5 人民币付款

5.5.1 人民币付款

1 功能描述


交易代码	TP1001
功能名称	人民币付款
功能描述	发起人民币付款请求，将收款人信息发送至Ottpayhk
调用方式	实时接口
调用流程	先通过sftp将还原材料提交至Ottpayhk，再调用此接口发送付款信息
应用场景	需要将人民币付给国内持卡人

2 请求地址

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

Method： POST

{
  "callbackUrl": "https://www.baidu.com",
  "merOrderNo": "LNQ004401100035001",
  "payOrderList": [
    {
      "amount": 20000,
      "cNAPSCode": "103584003015",
      "declarationCurrency": "CNY",
      "identity": "52242419950721981931",
      "merSingleNo": "LNQ004401100035003",
      "mobile": "13800000000",
      "payMethod": "cash_on_delivery",
      "payeeAccountNo": "6228480000000000000",
      "payeeName": "刘某",
      "registrationRegion": "HK",
      "senderIncorporationNo": "9144040000X",
      "tradeCodeType": "TRADE"
    }
  ],
  "payReduceList": [
    {
      "goodNumber": "1",
      "goodsName": "棉花",
      "orderAmount": 20000,
      "orderCurrency": "CNY",
      "orderDate": "2023-07-30",
      "orderNo": "202308-025",
      "platformName": "百度",
      "purpose": "GOODSTRADE",
      "storeLink": "https://www.baidu.cn",
      "wlName": "百度",
      "wlSeqno": "BD20230823001",
      "payeeAcctNo": "6228480000000000000"
    }
  ],
  "paymentType": "B2C",
  "settlementType": "00"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
订单号	merOrderNo	String(32)	M	本次交易唯一订单号
还原材料路径	fileUrlPath	String(128)	O	上传至sftp文件服务器的还原材料路径
交易类型	paymentType	String	M	参数详见字段说明
结汇类型	settlementType	String(3)	O	10极速结汇，00普通结汇，若不填则默认00普通结汇
回调地址	callbackUrl	String	M	用于结果通知的地址
收款人列表	payOrderList	`List<PayOrderRequest>`	M	收款信息
还原材料列表	payReduceList	`List<payReduceList>`	O	当收款信息交易编码为游戏、电商、一般货物贸易-网络购物填写参数详见字段说明

PayOrderRequest信息

名称	Json标签	类型	属性	取值说明
单笔订单号	merSingleNo	String	O	单个付款记录对应的订单号
收款方账号	payeeAccountNo	String	M	收款方银行账号
收款方姓名	payeeName	String	M	收款方银行账户名
身份证号/统一社会信用代码	identity	String	M	若收款方账户类型为0，则填写身份证号，为1则填写统一社会信用代码
金额	amount	Decimal	C	付款金额，单位为分，例：若付款200.00元，应填写20000最小为1，和debitAmount强制2选1
扣款币种	debitCurrency	String	O	扣款币种,默认为CNY (如果入参存在并且不为CNY，则返回后需调用确认接口) (批次内仅允许选择一种币种)
扣款金额	debitAmount	Decimal	C	扣款金额，单位为分，例：若付款200.00元，应填写20000最小为1，和amount强制2选1
联行号	cNAPSCode	String	C	收款方银行联行号企业必填，个人非必填
手机号	mobile	String	M	手机号
交易编码	tradeCodeType	String	M	参数详见字段说明
付款方式	payMethod	String	O	参数详见字段说明, tradeCodeType为TRADE并且paymentType为B2B时不能为空, 默认：cash_on_delivery
报关币种	declarationCurrency	String	O	payMethod值为cash_on_delivery不能为空，默认CNY
预付比例	advanceProportion	Float	O	payMethod值为advance ,0 < advanceProportion < 1 ,小数点后最多两位
结算账期	settlementDate	String	O	payMethod值为advance结算账期不能为空单位天
付款方名称	senderName	String	M	真实付款方名称
付款方公司注册号	senderIncorporationNo	String	M	付款方公司注册号
付款方注册地	registrationRegion	String	M	付款人住的区域swift国家地区
付款方银行名称	senderBankName	String	M	付款方银行名称
资金源	sourceFounds	String	O	选填
付款方银行账户	senderBankAccountNo	String	O	付款方银行账户选填
汇款附言	tradeComments	string(1024)	O	汇款附言

payReduceList信息

名称	Json标签	类型	属性	取值说明
订单号	orderNo	String	M	单个付款记录对应的订单号(不超过32位)
订单币种	orderCurrency	String	M	收款币种
订单金额	orderAmount	Decimal	M	收款金额，单位为分，例：若付款200.00元，应填写20000最小为1
订单日期	orderDate	String	M	收款日期，格式为"yyyy-MM-dd"
收款人姓名	sellerName	String	C	收款人姓名 (交易编码为游戏或者一般货物贸易-网络购物(批次内多个收款人下发)时必填)
收款人证件号	sellerId	String	C	收款方证件号(长度不超过18位)(交易编码为游戏或者一般货物贸易-网络购物(批次内多个收款人下发)时必填)
商品名	goodsName	String	M	商品名 (4~512长度)
商品种类	goodsCategory	String	C	商品种类 (交易编码为游戏时必填)
商品数量	goodNumber	String	M	商品数量
物流公司	wlName	String	C	物流公司名 (交易编码为一般货物贸易-网络购物或者电商时必填)
物流单号	wlSeqno	String	C	物流单号 (交易编码为一般货物贸易-网络购物或者电商时必填)
店铺链接	storeLink	String	C	店铺链接地址 (交易编码为一般货物贸易-网络购物或者电商时必填)
平台名称	platformName	String	C	平台名称 (交易编码为一般货物贸易-网络购物或者电商时必填)
汇款用途	purpose	String	C	汇款用途代码参数 (交易编码为一般货物贸易-网络购物或者电商时必填)
买家银行名	buyerBankName	String	O	买家银行名
买家银行卡号	buyerBankCard	String	O	买家银行卡号
交易方式	sendType	String	O	发货方式
快递金额	sendAmount	Decimal	O	快递金额，单位为分，例：若付款200.00元，应填写20000最小为1
税费金额	taxAmount	Decimal	O	税费金额，单位为分，例：若付款200.00元，应填写20000最小为1
其他金额	otherAmount	Decimal	O	其他金额，单位为分，例：若付款200.00元，应填写20000最小为1
申报人类型	applyType	String	O	申报人类型
收款人账号	payeeAcctNo	String	C	收款人账号 (一般货物贸易-网络购物(批次内多个收款人下发)时必填)

{
  "amount": 20000,
  "bizFlowNo": "31733082318111101613",
  "debitAmount": 20000,
  "debitCurrency": "CNY",
  "merOrderNo": "LNQ004401100035001",
  "rate": 1,
  "status": "3"
}

4 响应字段

若响应报文头内respCode为S00000，则为受理成功，请等待异步通知（见5.5.3 系统通知商户付款结果）付款结果。报文体：当 respCode为S00000时：

名称	Json标签	类型	属性	取值说明
订单号	merOrderNo	String(32)	M	原样返回
业务流水号	bizFlowNo	String(32)	M	Ottpayhk生成的唯一业务流水号，与订单号一一对应
状态	status	String(1)	M	"0":"接受", "1":"成功", "2":"失败", "3":"处理中", "6":"待确认"
手续费币种	feeCurrency	String(3)	O	所收取的手续费币种
手续费币种	feeAmount	Decimal	O	所收取的手续费金额
实际付款金额	actualPayAmount	Decimal	O	实际付款金额
扣款币种	debitCurrency	String	M	扣款币种
汇率	rate	Decimal	O	汇率
扣款金额	debitAmount	Decimal	M	扣款金额
收款金额	amount	Decimal	M	收款金额
报价ID	quoteId	long	O	报价ID
报价有效期	expireTime	long	O	unix时间戳，此次询价的有效时间。

5.5.2 人民币付款业务查询

1 功能描述

交易代码	TP3001
功能名称	人民币付款业务查询
功能描述	商户自行查询人民币付款最终结果
调用方式	实时接口
调用流程	商户发送人民币付款请求后，查询对应订单结果
应用场景	商户需要知晓人民币付款最终结果

2 请求地址

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

Method： POST

{
  "bizFlowNo":"31183081711294000016"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
订单号	merOrderNo	String(32)	O	付款发起时的订单号
业务流水号	bizFlowNo	String(32)	O	Ottpayhk 生成的唯一业务流水号，与订单号一一对应注：订单号与业务流水号仅需填写一个，若同时填写，以业务流水号为准

{
  "actualPayAmount": 35900,
  "amount": 35900,
  "bizFlowNo": "31183081711294000016",
  "debitAmount": 35900,
  "debitCurrency": "CNY",
  "feeAmount": 600,
  "feeCurrency": "CNY",
  "merOrderNo": "LNQ202308230001",
  "merchantNo": "004401100035",
  "payeeList": [
    {
      "acctType": "1",
      "amount": 35900,
      "applyNo": "32183081711294000017",
      "bankBranchName": "中国工商银行",
      "bankCity": "654300",
      "bankName": "中国工商银行",
      "bankProvince": "650000",
      "debitAmount": 35900,
      "identity": "450923199201011113",
      "merSingleNo": "LNQ202308230001_0001",
      "mobile": "13212345678",
      "payeeAccountNo": "6226151810004564",
      "payeeName": "VKB",
      "status": "3",
      "tradeCodeType": "TRADE",
      "tradeComments": "fuyan"
    }
  ],
  "rate": 1,
  "settlementType": "00",
  "status": "3"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
订单号	merOrderNo	String(32)	M	付款请求发起时的订单号
业务流水号	bizFlowNo	String(32)	M	付款请求返回的业务流水号
状态	status	String(1)	M	"0":"接受", "1":"成功", "2":"失败", "3":"处理中", "6":"待确认"
结果代码	respCode	String(6)	M	付款交易结果代码
结果描述	respDesc	String(50)	M	付款交易结果详情描述
收款人列表	payeeList	`List<payee>`	M	收款人列表
手续费币种	feeCurrency	String(3)	O	所收取的手续费币种
手续费币种	feeAmount	Decimal	O	所收取的手续费金额
实际付款金额	actualPayAmount	Decimal	O	实际付款金额
结汇类型	settlementType	String(3)	O	10极速结汇，00普通结汇，若不填则默认00普通结汇
扣款币种	debitCurrency	String	M	扣款币种
扣款金额	debitAmount	Decimal	M	扣款金额
收款金额	amount	Decimal	M	收款金额
汇率	rate	Decimal	O	汇率

payee 的字段

名称	Json标签	类型	属性	取值说明
单笔订单号	merSingleNo	String(32)	M	单个付款记录对应的订单号
收款方户名	payeeName	String(64)	M	收款方银行账户户名
收款方账号	payeeAccountNo	String(32)	M	收款方银行账号
收款方账户类型	acctType	String(1)	M	0 : 对私账户 1：对公账户
身份证号/ 统一社会信用代码	identity	String(32)	M	若收款方账户类型为 0，则填写身份证号，为 1 则填写统一社会信用代码
金额	amount	String(18)	M	付款金额，单位为分，例：若付款 200.00 元，应填写 20000
扣款金额	debitAmount	String(18)	M	扣款金额，单位为分，例：若付款 200.00 元，应填写 20000
联行号	cNAPSCode	String(64)	M	联行号
手机号	mobile	String(13)	M	手机号
开户行名称	bankName	String(32)	M	收款方银行名称
开户行省份	bankProvince	String(32)	M	收款方银行所在省份
开户行市名	bankCity	String(32)	M	收款方银行所在市名
支行名称	bankBranchName	String(32)	M	收款方银行支行名称
交易编码	tradeCodeType	String(6)	M	对应交易属性类型，参见参数详见字段说明
单笔结果代码	respCode	String(6)	M	单笔交易对应的结果代码
单笔结果描述	respDesc	String(50)	M	单笔交易对应的结果描述
付款方式	payMethod	String	F	tradeCodeType为 TRADE，并且 paymentType 为 B2B 时不能为空参数详见字段说明
报关币种	declarationCurrency	String	F	payMethod 值为 cash_on_delivery 不能为空
预付比例	advanceProportion	Float	F	payMethod 值为 advanc 0 < advanceProportion < 1 小数点后最多两位
结算账期	settlementDate	String	F	payMethod 值为 advance 结算账期不能为空单位天
付款方名称	senderName	String	M	真实付款方名称
付款方公司注册号	senderIncorporationNo	String	M	付款方公司注册号
付款方注册地	registrationRegion	String	M	付款人住的区域 swift 国家地区
付款方银行名称	senderBankName	String	M	付款方银行名称
资金源	sourceFounds	String	F	选填
付款方银行账户	senderBankAccountNo	String	F	付款方银行账户选填

5.5.3 系统通知商户付款结果

1 功能描述

交易代码	TP2001
功能名称	付款回调
功能描述	Ottpayhk 通知商户付款结果
调用方式	实时接口
调用流程	商户先调用 5.5.1 人民币付款向 Ottpayhk 发起人民币付款请求，Ottpayhk 将交易。处理完毕后，通知商户。若规定时间内未及时回调通知商户，商户应该发起主动查询
应用场景	商户需要知晓人民币付款最终结果

2 请求地址

Url： 5.1.1 人民币付款中的 callbackUrl

Method： POST

{
  "amount": 35900,
  "bizFlowNo": "31183081711294000016",
  "debitAmount": 35900,
  "debitCurrency": "CNY",
  "faultCount": 0,
  "merOrderNo": "LNQ202308230001",
  "payeeList": [
      {
          "amount": 35900,
          "applyNo": "32183081711294000017",
          "debitAmount": 35900,
          "merSingleNo": "LNQ202308230001_0001",
          "respCode": "00000",
          "respDesc": "成功",
          "status": "1"
      }
  ],
  "rate": 1,
  "settlementType": "00",
  "successCount": 1
}

3 请求字段

名称	Json标签	类型	属性	取值说明
订单号	merOrderNo	String(32)	M	原样返回
业务流水号	bizFlowNo	String(32)	M	Ottpayhk 生成的唯一业务流水号，与订单号一一对应
成功笔数	successCount	Int	M	返回成功笔数
失败笔数	faultCount	Int	M	返回失败笔数
付款详情	payeeList	`List<payee>`	M	付款详情列表不分页
结汇类型	settlementType	String(3)	O	10极速结汇，00普通结汇，若不填则默认00普通结汇
扣款币种	debitCurrency	String	M	扣款币种
扣款金额	debitAmount	Decimal	M	扣款金额
收款金额	amount	Decimal	M	收款金额
汇率	rate	Decimal	O	汇率

payee 字段:

名称	Json标签	类型	属性	取值说明
单笔详情外部商户号	merSingleNo	String	M	商户传入的管理商户系统的凭证号
系统订单号	applyNo	String		M Ottpayhk 生成的订单号
金额	amount	Decimal(18,2)	M	付款金额
扣款金额	debitAmount	Decimal(18,2)	M	扣款金额
状态	status	Int	M	"0":"接受","1", "成功","2","失败","3","处理中"
说明	respDesc	String	M	交易具体说明
状态码	respCode	String	M	交易具体的状态码

5.5.4 查询总行

1 功能描述

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

2 请求地址

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

Method： POST

{
  "pageNo": 1,
  "pageSize": 2
}

3 请求字段

名称	Json标签	类型	属性	取值说明
页数	pageNo	Int	O	分页页数，默认1
页显示数	pageSize	Int	O	页显示数，默认10

{
  "pageNo": 1,
  "pageSize": 2,
  "results": [
    {
      "bankId": 1,
      "bankLinkNo": "102100099996",
      "bankName": "中国工商银行总行清算中心"
    },
    {
      "bankId": 2,
      "bankLinkNo": "103100000026",
      "bankName": "中国农业银行资金清算中心"
    }
  ],
  "totalPage": 2,
  "totalRecord": 20
}

4 响应字段

名称	Json标签	类型	属性	取值说明
当前页数	pageNo	Int	M	--
当前页显示数	pageSize	Int	M	--
总记录数	totalRecord	Int	M	--
总行信息集合	results	`List<QueryBankResp>`	M	--

QueryBankResp 字段：

名称	Json标签	类型	属性	取值说明
银行名称	bankName	String(64)	M	--
银行Id	bankId	int	M	--
银行名称英文	bankNameEn	String(64)	M	--

5.5.5 查询总行下分行支持省份

1 功能描述

交易代码	TP6002
功能名称	查询省份信息
功能描述	查询总行下支持分行所在省份
调用方式	实时接口
调用流程	--
应用场景	--

2 请求地址

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

Method： POST

{
  "bankId":"1"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
总行Id	bankId	Int	M	必填总行的银行编码

{
  "bankId": 1,
  "provinceList": [
    {
      "provinceCode": "11",
      "provinceName": "北京市",
      "provinceNameEn": "Beijing"
    },
    {
      "provinceCode": "12",
      "provinceName": "天津市",
      "provinceNameEn": "Tianjin"
    }
  ]
}

4 响应字段

名称	Json标签	类型	属性	取值说明
总行Id	bankId	Int	M	总行的银行编码
省份信息集合	provinceList	`List<ProvinceResp>`	M	--

ProvinceResp 字段：

名称	Json标签	类型	属性	取值说明
省份编码	provinceCode	String(64)	M	--
省份名称	provinceName	String(32)	M	--
省份名称英文	provinceNameEn	String(64)	M	--

5.5.6 查询总行下分行支持城市

1 功能描述

交易代码	TP6003
功能名称	查询城市信息
功能描述	查询总行下支持分行所在城市
调用方式	实时接口
调用流程	--
应用场景	--

2 请求地址

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

Method： POST

{
    "bankId": "1",
    "provinceCode": "11"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
总行Id	bankId	Int	M	必填总行的银行编码
省份编码	provinceCode	String(64)	M	必填省份编码

{
  "bankId": 1,
  "cityList": [
    {
      "cityCode": "1101",
      "cityName": "北京市",
      "cityNameEn": "City area"
    }
  ],
  "provinceCode": "11"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
总行Id	bankId	Int	M	--
省份编码	provinceCode	String(64)	M	--
城市信息集合	cityList	`List<CityResp>`	M	--

CityResp 字段：

名称	Json标签	类型	属性	取值说明
城市编码	cityCode	String(64)	M	--
城市名称	cityName	String(32)	M	--
城市名称英文	cityNameEn	String(32)	M	--

5.5.7 查询总行下某城市所有分行

1 功能描述

交易代码	TP6004
功能名称	查询分行信息
功能描述	查询总行下某城市所有分行
调用方式	实时接口
调用流程	--
应用场景	--

2 请求地址

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

Method： POST

{
  "pageNo": 1,
  "pageSize": 2,
  "request": {
    "bankId": 1,
    "cityCode": "1101"
  }
}

3 请求字段

名称	Json标签	类型	属性	取值说明
页数	pageNo	int	O	默认1
页显示数	pageSize	int	O	默认 10
分行查询请求	request	`QueryBranchBankRequest`	M	不能为空

QueryBranchBankRequest 的字段

名称	Json标签	类型	属性	取值说明
总行Id	bankId	Int	M	不能为空
城市编码	cityCode	String(64)	M	不能为空

{
  "pageNo": 1,
  "pageSize": 2,
  "results": [
    {
      "bankCityCode": "1101",
      "bankCityName": "北京市",
      "bankCityNameEn": "City area",
      "bankLinkNo": "102100005001",
      "bankName": "中国工商银行股份有限公司牡丹卡中心",
      "bankNameEn": "Industrial and Commercial Bank of China Peony Card Center",
      "bankProvinceCode": "11",
      "bankProvinceName": "北京市",
      "bankProvinceNameEn": "Beijing"
    },
    {
      "bankCityCode": "1101",
      "bankCityName": "北京市",
      "bankCityNameEn": "City area",
      "bankLinkNo": "102100010022",
      "bankName": "中国工商银行股份有限公司票据营业部北京分部",
      "bankNameEn": "Industrial and Commercial Bank of China Beijing Branch",
      "bankProvinceCode": "11",
      "bankProvinceName": "北京市",
      "bankProvinceNameEn": "Beijing"
    }
  ],
  "totalPage": 33,
  "totalRecord": 324
}

4 响应字段

名称	Json标签	类型	属性	取值说明
当前页码	pageNo	Int	M	--
页显示数	pageSize	Int	M	--
总数	totalRecord	In	M	--
分支行信息集合	results	`List<QueryBranchBankResp>`	M	--

QueryBranchBankResp 字段：

名称	Json标签	类型	属性	取值说明
联行号	bankLinkNo	String(64)	M	--
银行名称	bankName	String(32)	M	--
银行名称英文	bankNameEn	String(32)	M	--
省份编码	bankProvinceCode	String(32)	M	--
省份名称	bankProvinceName	String(32)	M	--
省份名称英文	bankProvinceNameEn	String(32)	M	--
城市编码	bankCityCode	String(32)	M	--
城市名称	bankCityName	String(32)	M	--
城市名称英文	bankCityNameEn	String(32)	M	--

5.5.8 人民币付款交易确认

1 功能描述


交易代码	TP1019
功能名称	人民币付款交易确认
功能描述	确认人民币付款交易，正式提交。
调用方式	实时接口
调用流程	调用5.5.1 人民币付款接口提交交易后，调用此接口确认交易。
应用场景	发起人民币付款，向境内收款人发起付款后，确认人民币付款交易，正式提交。

2 请求地址

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

Method： POST

{
  "quoteId": 1143128725976500000
}

3 请求字段

名称	Json标签	类型	属性	取值说明
报价ID	quoteId	Long	M	报价ID

{
  "amount": 794,
  "bizFlowNo": "31603082110252600000",
  "debitAmount": 100,
  "debitCurrency": "EUR",
  "expireTime": 1692584735000,
  "merOrderNo": "LNQ202308230001",
  "quoteId": 1143128725976500000,
  "rate": 7.9402,
  "status": "3"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
交易流水号	bizFlowNo	String	M	对应人民币付款交易的唯一流水号
商户订单号	merOrderNo	String	M	商户订单号
报价ID	quoteId	long	M	报价ID
扣款币种	debitCurrency	string	M	扣款币种，3位标准货币代码
扣款金额	debitAmount	Decimal	M	扣款金额
到账金额	amount	Decimal	M	到账金额
汇率	rate	String	M	汇率
状态	status	String	M	订单状态 "0":"接受", "1":"成功", "2":"失败", "3":"处理中"
手续费币种	feeCurrency	String	O	所收取的手续费币种
手续费币种	feeAmount	Decimal	O	所收取的手续费金额
实际付款金额	actualPayAmount	Decimal	O	实际付款金额

5.5.9 新增结汇收款人

1 功能描述


交易代码	TP1021
功能名称	新增结汇收款人
功能描述	新增结汇收款人，为结汇付款做准备。
调用方式	实时接口
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "country": "CN",
  "bankAcctNo": "6213326400000000000",
  "payeeType": "2001",
  "mobile": "13850000000",
  "branchName": "中国银行",
  "subjectType": "00",
  "certNo": "350321195601010006",
  "payeeName": "Sponge baby",
  "currency": "CNY",
  "businessType": "00"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
主体类型	subjectType	String(2)	M	主体类型：00-个人，01-企业
收款方姓名	payeeName	String(64)	M	收款方姓名
证件号	certNo	String(32)	M	证件号
手机号	mobile	String(11)	M	手机号
国家/地区	country	String(2)	M	国家/地区
币种	currency	String(3)	M	币种
银行联行号	bankCode	String(32)	C	银行联行号对公必传
银行账号	bankAcctNo	String(32)	M	银行账号
支行名称	branchName	String(128)	M	支行名称
业务类型	businessType	String(32)	M	业务类型 00-货贸（包含电商） 01-服贸多条以,隔开
收款人分类	payeeType	String(4)	M	收款人分类参数详见字段说明
补充材料	supplementaryMaterialsPath	String	C	补充材料地址参数详见字段说明(收款人类型为：供应商、广告商、物流商、代理商、其他服务商、服务商、员工、企业供应商的法人/董事/股东需上传)
营业执照	businessLicensePath	String	C	营业执照地址业务类型为货贸如果收款方是个人，且非公司本身的重要控制人，务必提供个人收款方代表的供应商公司主体的营业执照，如果收款方是公司，可暂不提供
身份证正面	frontCardPath	String	O	身份证正面地址业务类型为货贸且主体类型为个人选传
身份证反面	backCardPath	String	O	身份证反面地址业务类型为货贸且主体类型为个人选传
法人身份证正面	legalFrontCardPath	String	O	法人身份证正面地址业务类型为货贸且主体类型为企业选传
法人身份证反面	legalBackCardPath	String	O	法人身份证反面地址业务类型为货贸且主体类型为企业选传
法人身份证号	legalCertNo	String	C	法人身份证号业务类型为货贸且主体类型为企业必传

{
  "code": "S00000",
  "msg": "请求成功",
  "data": {
    "code": "SUCC",
    "message": null,
    "bizFlow": "ctWYP7ZybGB8nu7ClPEBOY21iKldamdzCxFk",
    "status": "03"
  },
  "succ": true
}

4 响应字段

名称	Json标签	类型	属性	取值说明
code码	code	String(16)	M	code返回码，SUCC--成功，FAIL--失败
收款人信息唯一编号	bizFlow	String(32)	M	收款人信息唯一编号
收款人状态	status	String(2)	M	收款人状态 00-审核中 01-成功 02-失败 03-待补充材料

5.5.10 修改结汇收款人

1 功能描述


交易代码	TP1022
功能名称	修改结汇收款人
功能描述	修改结汇收款人，为结汇付款做准备。
调用方式	实时接口
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "bizFlow": "ctWYP7ZybGB8nu7ClPEBOY21iKldamdzCxFk",
  "country": "CN",
  "bankAcctNo": "6213326400000000000",
  "payeeType": "2001",
  "mobile": "13850000000",
  "branchName": "中国银行",
  "subjectType": "00",
  "certNo": "350321195601010006",
  "payeeName": "Sponge baby",
  "currency": "CNY",
  "supplementaryMaterialsPath": "uploadFile/hzfr.jpg",
  "businessType": "00"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
收款人信息唯一编号	bizFlow	String(64)	M	收款人信息唯一编号，由查询接口获取
主体类型	subjectType	String(2)	M	主体类型：00-个人，01-企业
收款方姓名	payeeName	String(64)	M	收款方姓名
证件号	certNo	String(32)	M	证件号
手机号	mobile	String(11)	M	手机号
国家/地区	country	String(2)	M	国家/地区
币种	currency	String(3)	M	币种
银行联行号	bankCode	String(32)	C	银行联行号对公必传
银行账号	bankAcctNo	String(32)	M	银行账号
支行名称	branchName	String(128)	M	支行名称
业务类型	businessType	String(32)	M	业务类型 00-货贸（包含电商） 01-服贸多条以,隔开
收款人分类	payeeType	String(4)	M	收款人分类参数详见字段说明
补充材料	supplementaryMaterialsPath	String	C	补充材料地址参数详见字段说明(收款人类型为：供应商、广告商、物流商、代理商、其他服务商、服务商、员工、企业供应商的法人/董事/股东需上传)
营业执照	businessLicensePath	String	C	营业执照地址业务类型为货贸如果收款方是个人，且非公司本身的重要控制人，务必提供个人收款方代表的供应商公司主体的营业执照，如果收款方是公司，可暂不提供
身份证正面	frontCardPath	String	O	身份证正面地址业务类型为货贸且主体类型为个人选传
身份证反面	backCardPath	String	O	身份证反面地址业务类型为货贸且主体类型为个人选传
法人身份证正面	legalFrontCardPath	String	O	法人身份证正面地址业务类型为货贸且主体类型为企业选传
法人身份证反面	legalBackCardPath	String	O	法人身份证反面地址业务类型为货贸且主体类型为企业选传
法人身份证号	legalCertNo	String	C	法人身份证号业务类型为货贸且主体类型为企业必传

{
  "code": "S00000",
  "msg": "请求成功",
  "data": {
    "code": "SUCC",
    "message": null,
    "bizFlow": null,
    "status": null
  },
  "succ": true
}

4 响应字段

名称	Json标签	类型	属性	取值说明
code码	code	String(16)	M	code返回码，SUCC--成功，FAIL--失败

5.5.11 删除结汇收款人

1 功能描述


交易代码	TP1023
功能名称	删除结汇收款人
功能描述	删除结汇收款人，为结汇付款做准备。
调用方式	实时接口
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "bizFlow": "ctWYP7ZybGB8nu7ClPEBOY21iKldamdzCxFk"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
收款人信息唯一编号	bizFlow	String(64)	M	收款人信息唯一编号，由查询接口获取

{
  "code": "S00000",
  "msg": "请求成功",
  "data": {
    "code": "SUCC"
  },
  "succ": true
}

4 响应字段

名称	Json标签	类型	属性	取值说明
code码	code	String(16)	M	code返回码，SUCC--成功，FAIL--失败

5.5.12 查询结汇收款人

1 功能描述


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

2 请求地址

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

Method： POST

{
  "bankAcctNo": "6213326400000319910"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
收款方姓名	payeeName	String(64)	O	收款方姓名，不支持模糊查询
手机号	mobile	String(11)	O	手机号，不支持模糊查询
银行账号	bankAcctNo	String(32)	O	银行账号，不支持模糊查询
页数	pageNo	Int	O	分页页数，默认1
页显示数	pageSize	Int	O	分页页显示数，默认10，最大100

{
  "pageNum": 1,
  "pageSize": 10,
  "total": 1,
  "pages": 1,
  "list": [
    {
      "payeeName": "Sponge baby",
      "bankAcctNo": "6213***0000",
      "businessType": "00",
      "payeeType": "2001",
      "country": "CN",
      "branchName": "中国银行",
      "subjectType": "00",
      "currency": "CNY",
      "certNo": "350321*********006",
      "mobile": "138****0000",
      "status": "01",
      "bizFlow": "ctWYP7ZybGB8nu7ClPEBOY21iKldamdzCxFk"
    }
  ]
}

4 响应字段

名称	Json标签	类型	属性	取值说明
当前页码	pageNum	Int	M	当前页码
页显示数	pageSize	Int	M	页显示数
总数	total	Int	M	总数
收款人信息集合	list	`List<PayeeRes>`	M	收款人信息集合

PayeeRes 的字段

名称	Json标签	类型	属性	取值说明
收款人信息唯一编号	bizFlow	String(64)	M	收款人信息唯一编号，由查询接口获取
主体类型	subjectType	String(2)	M	主体类型：00-个人，01-企业
收款方姓名	payeeName	String(64)	M	收款方姓名，脱敏
证件号	certNo	String(32)	M	证件号，脱敏
手机号	mobile	String(11)	M	手机号，脱敏
国家/地区	country	String(2)	M	国家/地区
币种	currency	String(3)	M	币种
银行账号	bankAcctNo	String(32)	M	银行账号
支行名称	branchName	String(128)	M	支行名称
业务类型	businessType	String(32)	O	业务类型 00-货贸（包含电商） 01-服贸多条以,隔开
收款人分类	payeeType	String(4)	O	收款人分类参数详见字段说明
状态	status	String(2)	O	状态 00-审核中 01-成功 02-失败 03-待补充材料

5.6 国际汇款

5.6.1 查询国际付款字段

1 功能描述

交易代码	TP3005
功能名称	查询国际付款字段
功能描述	查询向不同国家付款所需的字段
调用方式	实时接口
调用流程	--
应用场景	国际付款前查询向不同国家付款所需的字段

2 请求地址

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

Method： POST

{
  "accountType": "1",
  "arriveCurrency": "HKD",
  "countryCode": "HK",
  "debitCurrency": "USD",
  "payType": "local"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
收款国家	countryCode	string	M	iso 3166-1标准2字代码
收款币种	arriveCurrency	string	M	收款方币种，3位标准货币代码
扣款币种	debitCurrency	string	M	扣款币种，3位标准货币代码
付款方式	payType	string	M	可选值：local 或者 swift
收款账户类型	accountType	string	M	收款账户类型:1-银行账户，06-钱包

{
  "bankList": [
    "Tai Yau Bank Limited",
    "THE CHUGOKU BANK, LTD.",
    "NatWest Markets Plc Hong Kong Branch",
    "JPMorgan Chase Bank, N.A.",
    "SOCIETE GENERALE HONGKONG BRANCH",
    "EAST WEST BANK",
    "China Guangfa Bank Co., Ltd.",
    "NATIXIS HONG KONG BRANCH",
    "Yintran Group Holdings Limited",
    "BANK OF TAIWAN",
    "Taiwan Shin Kong Commercial Bank Co., LTD.",
    "044-OCBC Wing Hang Bank Limited",
    "Shinhan Bank Hong Kong Branch",
    "Banco Bilbao Vizcaya Argentaria S.A., Hong Kong Branch",
    "Far Eastern International Bank Co Ltd.",
    "Credit Agricole Corporate and Investment Bank",
    "KBC Bank N.V. Hong Kong Branch",
    "YUANTA COMMERCIAL BANK CO.,LTD",
    "Fubon Bank (Hong Kong) Limited",
    "Dah Sing Bank, Limited",
    "Mega International Commercial Bank Co Ltd",
    "052-DBS Bank (Hong Kong) Ltd.",
    "Hong Leong Bank Berhad Hong Kong Branch",
    "E.Sun Commercial Bank, Ltd.",
    "064-Bank of China (Hong Kong) Limited",
    "O-Bank Co., Ltd",
    "BANK OF INDIA",
    "Deutsche Bank AG Hong Kong Branch",
    "Shanghai Commercial Bank Limited",
    "Woori Bank Hong Kong Branch",
    "Bank SinoPac (Hong Kong Branch)",
    "China Minsheng Banking Corp., Ltd.",
    "Mashreq Bank Public Shareholding Company",
    "STANDARD CHARTERED BANK (HONG KONG) LIMITED",
    "The Shizuoka Bank, Ltd.",
    "The Bank of New York Mellon, Hong Kong Branch",
    "DZ BANK AG DEUTSCHE ZENTRALGENOSSENSCHAFTSBANK, FRANKFURT AM MAIN, HONG KONG BRANCH",
    "HDFC BANK LIMITED",
    "Skandinaviska Enskilda Banken AB",
    "CA Indosuez (Switzerland) SA",
    "ABN AMRO BANK N.V.",
    "BDO UNIBANK, INC.",
    "First Abu Dhabi Bank PJSC",
    "Bank of Dongguan Co., Ltd.",
    "Qatar National Bank (Q.P.S.C.)",
    "Octopus Cards Limited",
    "Morgan Stanley Bank Asia Limited",
    "CHANG HWA COMMERCIAL BANK LIMITED",
    "ZA Bank Limited",
    "Taiwan Business Bank, Ltd.",
    "Bank of Communications (Hong Kong) Ltd.",
    "PHILIPPINE NATIONAL BANK",
    "UBS AG Hong Kong",
    "Kookmin Bank",
    "035-OCBC Wing Hang Bank Limited",
    "Sumitomo Mitsui Banking Corporation",
    "Cathay United Bank Company, Limited, Hong Kong Branch",
    "Taishin International Bank Co Ltd",
    "014-Bank of China (Hong Kong) Limited",
    "032-DBS Bank (Hong Kong) Ltd.",
    "STATE BANK OF INDIA",
    "019-Bank of China (Hong Kong) Limited",
    "Shanghai Pudong Development Bank Co., Ltd.",
    "Bank of America N.A.",
    "UNICREDIT BANK AG HONG KONG BRANCH",
    "Credit Industriel et Commercial, Hong Kong Branch",
    "Barclays Bank PLC",
    "LGT Bank AG., HK Branch",
    "INDUSTRIAL AND COMMERCIAL BANK OF CHINA LIMITED",
    "026-Bank of China (Hong Kong) Limited",
    "Toronto Dominion Bank",
    "CHINA BOHAI BANK CO., LTD.",
    "Welab Bank Limited",
    "The Bank of Nova Scotia",
    "Mizuho Bank, Ltd.",
    "030-Bank of China (Hong Kong) Limited",
    "Melli Bank Plc",
    "PUNJAB NATIONAL BANK",
    "China Development Bank Hong Kong Branch",
    "Agricultural Bank of China Limited, Hong Kong Branch",
    "MITSUBISHI UFJ TRUST AND BANKING CORPORATION",
    "OVERSEA - CHINESE BANKING CORPORATION LIMITED",
    "Malayan Banking Berhad Hong Kong Branch",
    "Taipei Fubon Commercial Bank",
    "029-INDUSTRIAL AND COMMERCIAL BANK OF CHINA (ASIA) LIMITED",
    "Mox Bank Limited",
    "Erste Group Bank AG",
    "UniCard Solution Limited",
    "ING Bank N.V., Hong Kong",
    "FIRST COMMERCIAL BANK LTD HONG KONG BRANCH",
    "Commerzbank AG, Hong Kong Branch",
    "WeChat Pay Hong Kong Limited",
    "BNP PARIBAS SECURITIES SERVICES",
    "Fusion Bank Limited",
    "Ping An Bank Co., Ltd.",
    "Credit Suisse AG Hong Kong Branch",
    "Commonwealth Bank of Australia",
    "TNG (Asia) Limited",
    "Australia and New Zealand Banking Corporation Limited",
    "State Street Bank & Trust Company, Hong Kong",
    "072-INDUSTRIAL AND COMMERCIAL BANK OF CHINA (ASIA) LIMITED",
    "BANK OF MONTREAL",
    "The Shanghai Commercial & Savings Bank Ltd.Hong Kong Branch.",
    "BANK J. SAFRA SARASIN LTD, HONG KONG BRANCH",
    "Hua Xia Bank Co., Limited",
    "COOPERATIEVE RABOBANK U.A.",
    "012-Bank of China (Hong Kong) Limited",
    "Banque Pictet & Cie SA",
    "Hang Seng Bank Ltd.",
    "Public Bank (Hong Kong) Limited",
    "The Bank of East Asia, Limited",
    "051-CHINA CITIC BANK INTERNATIONAL LIMITED",
    "China Merchants Bank Co. Ltd. Hong Kong Branch",
    "UNION BANK OF INDIA",
    "Sumitomo Mitsui Trust Bank, Limited, Hong Kong Branch",
    "HKT Payment Limited",
    "016-DBS Bank (Hong Kong) Ltd.",
    "Union Bancaire Privee, UBP SA",
    "CANADIAN IMPERIAL BANK OF COMMERCE",
    "ICICI BANK LIMITED",
    "United Overseas Bank Limited",
    "Chong Hing Bank Limited",
    "DBS Bank Ltd, HK Branch",
    "033-Bank of China (Hong Kong) Limited",
    "Bank of Singapore Limited",
    "China Construction Bank (Asia) Corporation Limited",
    "THE SHIGA BANK, LTD.",
    "CTBC BANK CO., LTD",
    "CHINA ZHESHANG BANK CO., LTD.",
    "INDUSTRIAL BANK OF KOREA",
    "The Chiba Bank Ltd",
    "EPAYLINKS TECHNOLOGY CO., LIMITED",
    "CMB Wing Lung Bank Limited",
    "EFG Bank AG Hong Kong Branch",
    "PT. BANK NEGARA INDONESIA (PERSERO) TBK.",
    "China Everbright Bank",
    "Intesa Sanpaolo S.p.A., Hong Kong",
    "KEB HANA BANK",
    "Nanyang Commercial Bank, Limited",
    "Airstar Bank Limited",
    "Taiwan Cooperative Bank",
    "Ant Bank (Hong Kong) Limited",
    "INDIAN OVERSEAS BANK",
    "China Construction Bank Corporation, Hong Kong Branch",
    "Alipay Financial Services (HK) Limited",
    "HUA NAN COMMERCIAL BANK LTD. (HK BRANCH)",
    "Bank of Communications Co., Ltd. Hong Kong Branch",
    "PayMe",
    "BANGKOK BANK PUBLIC COMPANY LIMITED",
    "BANK JULIUS BAER AND CO LTD HONG KONG",
    "BANCO SANTANDER S.A.",
    "070-Bank of China (Hong Kong) Limited",
    "The Hachijuni Bank Ltd",
    "UCO BANK HONG KONG",
    "Chiyu Banking Corporation Limited",
    "CIMB BANK BERHAD",
    "Wells Fargo Bank, N.A. Hong Kong Branch",
    "Autotoll Limited",
    "BNP PARIBAS HONG KONG BRANCH",
    "TAI SANG BANK LTD.",
    "Citibank (Hong Kong) Limited",
    "Royal Bank of Canada, Hong Kong Branch",
    "CATHAY BANK",
    "018-CHINA CITIC BANK INTERNATIONAL LIMITED",
    "LAND BANK OF TAIWAN CO.,LTD.",
    "National Bank of Pakistan",
    "33 Financial Services Limited",
    "Citibank N.A. Hong Kong",
    "The Hongkong and Shanghai Banking Corporation Limited",
    "Industrial Bank Co., Ltd., Hong Kong Branch",
    "National Australia Bank Limited",
    "036-Bank of China (Hong Kong) Limited",
    "Ping An OneConnect Bank (Hong Kong) Limited",
    "NongHyup Bank",
    "Westpac Banking Corporation",
    "031-Bank of China (Hong Kong) Limited",
    "Livi Bank Limited",
    "MUFG Bank, Ltd."
  ],
  "condition": {
    "bankAcctType": {
      "01": [
        "payeeCompanyName"
      ]
    }
  },
  "payee": {
    "optional": [
      "payeeCompanyName",
      "payeeAddress"
    ],
    "required": [
      "payeeBankAccountNo",
      "bankAcctType",
      "payeeResidentCountry",
      "payeeBankSwift",
      "payeeBankName"
    ]
  },
  "payer": {
    "optional": [
      "payerType"
    ],
    "required": [
      "payerBankName",
      "payerRegisteredCountry",
      "endSenderName"
    ]
  },
  "selectOption": {
    "bankAcctType": [
      {
        "code": "To B",
        "value": "01"
      }
    ],
    "payerType": [
      {
        "code": "B",
        "value": "01"
      }
    ]
  }
}

4 响应字段

名称	Json标签	类型	属性	取值说明
付款方	payer	ParamField	M	付款方所需字段要求
收款方	payee	ParamField	M	收款方所需字段要求
枚举值字段	selectOption	Object	O	收付款方某些字段的枚举值，code为对应值描述，value为对应的应传值
选填条件	condition	Object	O	前置选填条件
支持银行列表	bankList	`List<String>`	O	支持的收款银行名称列表如果不为空则该地区币种收款银行只能从列表中筛选

ParamField 的字段

名称	Json标签	类型	属性	取值说明
必填字段	required	`List<String>`	M	必填字段
选填字段	optional	`List<String>`	M	选填字段

5.6.2 国际汇款接口

1 功能描述


交易代码	TP1004
功能名称	国际汇款接口
功能描述	发起国际汇款，向境外收款人发起汇款。
调用方式	实时接口
调用流程	调用5.6.1 查询国际付款字段获取收款方所需字段后，依据相应字段，向收款人发起汇款。
应用场景	发起国际汇款，向境外收款人发起汇款

2 请求地址

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

Method： POST

{
  "accountType": "1",
  "arriveAmount": "150",
  "arriveCurrency": "HKD",
  "countryCode": "HK",
  "debitCurrency": "USD",
  "merOrderNo": "LNQ1692868278983",
  "payType": "local",
  "payee": {
    "bankAcctType": "01",
    "payeeBankAccountNo": "0018564",
    "payeeBankName": "CIMB BANK BERHAD",
    "payeeBankSwift": "10086000",
    "payeeCompanyName": "company",
    "payeeResidentCountry": "HK"
  },
  "payer": {
    "endSenderName": "company",
    "payerBankName": "DBS",
    "payerRegisteredCountry": "US"
  },
  "purpose": "99",
  "purposeRemark": "下发一笔"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
商户订单号	merOrderNo	string	M	商户自定义订单号，需唯一
收款国家	countryCode	string	M	iso 3166-1标准2字代码
收款币种	arriveCurrency	string	M	收款方币种，3位标准货币代码
扣款币种	debitCurrency	string	M	扣款币种，3位标准货币代码
付款方式	payType	string	M	可选值：local 或者 swift
收款账户类型	accountType	string	M	收款账户类型:1-银行账户，06-钱包
扣款金额	debitAmount	string	C	扣款金额，即扣款币种对应金额
收款金额	arriveAmount	string	C	收款金额（扣款金额和收款金额2选1填写，若同时填写，以收款金额为准）
汇款目的	purpose	string	M	详见6.1.4汇款目的列表
付款方字段	payer	object	M	按照相应国家tp3005返回的数据进行填写
收款方字段	payee	Object	M	按照相应国家tp3005返回的数据进行填写
关联fx流水号	fxBizFlow	String	O	关联fx流水号，若填写此字段，则本接口不校验余额，但扣款金额不能大于对应fx订单的金额
汇款附言	tradeComments	String	O	汇款附言
汇款目的备注	purposeRemark	String	O	当purpose为99时，汇款目的以此为准
是否为pobo同名付款	poboFlag	String	O	是否为pobo同名付款 0,1 为1时表示此笔交易为pobo同名付款，为0时表示非pobo同名付款，不填默认为0 ，仅限于开通POBO功能的SWIFT使用，其余不可传

{
  "arriveAmount": "150",
  "arriveCurrency": "HKD",
  "debitAmount": "19.33",
  "debitCurrency": "USD",
  "expireTime": 1694164280000,
  "merOrderNo": "LNQ1692868278983",
  "quoteId": 1144318423257358336,
  "rate": "7.7599586136"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
扣款币种	debitCurrency	String	M	扣款币种
收款币种	arriveCurrency	String	M	收款币种
汇率	rate	String	M	汇率
扣款金额	debitAmount	String	M	扣款金额
收款金额	arriveAmount	String	M	收款金额
报价ID	quoteId	long	M	报价ID
报价有效期	expireTime	long	M	unix时间戳，此次询价的有效时间。
商户订单号	merOrderNo	String	M	商户传入的订单号
关联fx流水号	fxBizFlow	String	O	关联fx流水号

5.6.3 国际汇款交易确认

1 功能描述


交易代码	TP1005
功能名称	国际汇款交易确认
功能描述	确认国际汇款交易，正式提交。
调用方式	实时接口
调用流程	调用5.6.2 国际汇款接口提交交易后，调用此接口确认交易。
应用场景	发起国际汇款，向境外收款人发起汇款后，确认国际汇款交易，正式提交。

2 请求地址

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

Method： POST

{
  "callbackUrl": "https://www.baidu.com",
  "quoteId": "1144318423257358336"
}

3 请求字段

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

{
  "accountType": "1",
  "arriveAmount": "150.00",
  "arriveCurrency": "HKD",
  "bizFlow": "41483082417125200025",
  "countryCode": "HK",
  "debitAmount": "19.33",
  "debitCurrency": "USD",
  "merOrderNo": "LNQ1692868370983",
  "payType": "local",
  "quoteId": 1144318423257358300,
  "rate": "7.7599586136",
  "status": "PROCESS"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
报价ID	quoteId	long	M	报价ID
收款国家	countryCode	string	M	iso 3166-1标准2字代码
收款币种	arriveCurrency	string	M	收款方币种，3位标准货币代码
扣款币种	debitCurrency	string	M	扣款币种，3位标准货币代码
付款方式	payType	string	M	可选值：local 或者 swift
收款账户类型	accountType	string	M	暂只支持输入 1（银行账户）
付款金额	arriveAmount	string	M	收款金额
扣款金额	debitAmount	String	M	扣款金额
汇率	rate	String	M	汇率
状态	status	String	M	订单状态
结果码	code	String	M	交易结果码
结果描述	message	String	M	交易结果描述
交易流水号	bizFlow	String	M	对应国际汇款交易的唯一流水号
商户订单号	merOrderNo	String	M	商户订单号
关联fx流水号	fxBizFlow	String	O	关联fx流水号

5.6.4 国际汇款历史交易查询

1 功能描述

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

2 请求地址

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

Method： POST

{
  "quoteId":"1144318423257358336"
}

3 请求字段

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

{
  "list": [
    {
      "accountType": "1",
      "arriveAmount": 150,
      "arriveCurrency": "HKD",
      "bankAcctType": "01",
      "bizFlow": "41483082417125200025",
      "callbackUrl": "https://api",
      "clientLanguage": "CN",
      "countryCode": "HK",
      "createTime": 1692868372512,
      "debitAmount": 19.33,
      "debitCurrency": "USD",
      "endSenderName": "company",
      "expireTime": 1694164372000,
      "feeAmt": 2.5,
      "feeCurrency": "USD",
      "lockDirection": "BUY",
      "merOrderNo": "LNQ1692868370983",
      "merchantNo": "004401100035",
      "payType": "local",
      "payeeBankAccountNo": "0018564",
      "payeeBankName": "CIMB BANK BERHAD",
      "payeeBankSwift": "10086000",
      "payeeCompanyName": "company",
      "payeeResidentCountry": "HK",
      "payerBankName": "DBS",
      "payerRegisteredCountry": "US",
      "payerType": "01",
      "purpose": "下发一笔",
      "quoteId": 1144318423257358300,
      "rate": 7.7599586136,
      "riId": 12765794,
      "status": "SUCC",
      "updateTime": 1692868402111
    }
  ]
}

4 响应字段

返回对象是List<RemittanceHistory>

RemittanceHistory 的字段

名称	Json标签	类型	属性	取值说明
报价ID	quoteId	long	M	报价ID
收款国家	countryCode	string	M	iso 3166-1标准2字代码
收款币种	arriveCurrency	string	M	收款方币种，3位标准货币代码
扣款币种	debitCurrency	string	M	扣款币种，3位标准货币代码
付款方式	payType	string	M	可选值：local 或者 swift
收款账户类型	accountType	string	M	暂只支持输入 1（银行账户）
付款金额	arriveAmount	string	M	收款金额
扣款金额	debitAmount	String	M	扣款金额
汇率	rate	String	M	汇率
状态	status	string	M	状态码
结果码	resCode	String	M	交易结果码
结果描述	resMessage	String	M	交易结果描述
交易流水号	bizFlow	String	M	对应国际汇款交易的唯一流水号
商户订单号	merOrderNo	String	M	商户订单号
付款和收款字段	xxxxxx	String	M	相应国家字段不同，根据tp3005返回的数据
关联fx流水号	fxBizFlow	String	O	关联fx流水号
手续费金额	feeAmt	Decimal	O	所收取的手续费金额
手续费币种	feeCurrency	String	O	所收取的手续费币种

5.6.5 国际汇款交易结果通知

1 功能描述

交易代码	TP2003
功能名称	国际汇款交易结果通知
功能描述	国际汇款的交易结果异步通知
调用方式	通知接口
调用流程	--
应用场景	5.6.3 国际汇款交易确认发起成功且交易处理完毕后，将根据5.1.5 国际汇款交易确认参数内的回调Url进行回调通知最终结果。

2 请求地址

Url： 5.6.3 国际汇款交易确认中的 callbackUrl

Method： POST

{
  "accountType": "1",
  "arriveAmount": "150.00",
  "arriveCurrency": "HKD",
  "bizFlow": "41483082417125200025",
  "countryCode": "HK",
  "debitAmount": "19.33",
  "debitCurrency": "USD",
  "feeAmt": 2.5,
  "feeCurrency": "USD",
  "merOrderNo": "LNQ1692868370983",
  "payType": "local",
  "quoteId": 1144318423257358300,
  "rate": "7.7599586136",
  "status": "SUCC"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
报价ID	quoteId	long	M	报价ID
收款国家	countryCode	string	M	iso 3166-1标准2字代码
收款币种	arriveCurrency	string	M	收款方币种，3位标准货币代码
扣款币种	debitCurrency	string	M	扣款币种，3位标准货币代码
付款方式	payType	string	M	可选值：local 或者 swift
收款账户类型	accountType	string	M	暂只支持输入 1（银行账户）
付款金额	arriveAmount	string	M	收款金额
扣款金额	debitAmount	String	M	扣款金额
汇率	rate	String	M	汇率
付款状态	status	string	M	订单状态
结果码	code	String	M	交易结果码
结果描述	message	String	M	交易结果描述
交易流水号	bizFlow	String	M	对应国际汇款交易的唯一流水号
商户订单号	merOrderNo	String	M	商户订单号
关联fx流水号	fxBizFlow	String	O	关联fx流水号
手续费金额	feeAmt	Decimal	O	所收取的手续费金额
手续费币种	feeCurrency	String	O	所收取的手续费币种

5.6.6 异常退款状态通知

1 功能描述

交易代码	TP2014
功能名称	异常退款状态通知
功能描述	异常退款状态结果异步通知
调用方式	通知接口
调用流程	--
应用场景	渠道异步通知终态变更后的退款状态通知(须先调用5.12.1 回调地址设置配置通知地址)

2 请求地址

Url： 【待补充】callbackUrl

Method： POST

{
  "applyNo": "42413032213515200508",
  "arriveAmount": 2.33,
  "arriveCurrency": "USD",
  "batchNo": "41273032213465300482",
  "debitAmount": 2.33,
  "debitCurrency": "USD",
  "feeAmount": 1.02,
  "feeCurrency": "USD",
  "merOrderNo": "528bef8587554dd2b5da9cfb38f70f54",
  "merchantNo": "004401100035",
  "receiveType": "01",
  "refundApplyNo": "42413032213515200508",
  "refundBatchNo": "41273032213465300482",
  "resCode": "OE0005",
  "resMessage": "拒绝-禁止的付款人",
  "status": "FAIL"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
商户号	merchantNo	String(32)	M	商户号
商户订单号	merOrderNo	String(32)	M	商户订单号
业务流水号	batchNo	String(32)	M	国际汇款申请返回的流水号
单笔订单号	applyNo	String(32)	M	单笔订单号
交易类型	receiveType	String(3)	M	交易类型 00:结汇付款 01:国际汇款
收款金额	arriveAmount	decimal(18,2)	M	收款金额
收款币种	arriveCurrency	String(3)	M	收款币种
扣款金额	debitAmount	decimal(18,2)	M	扣款金额
扣款币种	debitCurrency	String(3)	M	扣款币种
手续费金额	feeAmount	decimal(18,2)	O	手续费金额
手续费币种	feeCurrency	String(3)	O	手续费币种
付款状态	status	String(8)	M	订单状态
交易结果码	resCode	String(16)	M	交易结果码
交易结果描述	message	String(255)	O	交易结果描述
退款金额	refundAmount	decimal(18,2)	O	退款金额(暂无)
退款币种	refundCurrency	String(3)	O	退款币种(暂无)
退款手续费金额	refundFeeAmount	decimal(18,2)	O	退款手续费金额(暂无)
退款手续费币种	refundFeeCurrency	String(3)	O	退款手续费币种(暂无)
退款批次号	refundBatchNo	String(32)	M	退款批次号
退款单笔订单号	refundApplyNo	String(32)	M	退款单笔订单号
备注	remark	String(255)	O	备注

5.7 内部转账

5.7.1 商户内部间转账

1 功能描述


交易代码	TP1010
功能名称	商户内部间转账
功能描述	同为在OTT注册的商户，向对方OTT账户进行转账
调用方式	实时接口
调用流程	--
应用场景	同为在OTT注册的商户，向对方OTT账户进行转账

2 请求地址

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

Method： POST

{
  "amount": "200",
  "currency": "CNY",
  "merOrderNo": "LNQ1692927910914",
  "purpose": "1",
  "toAcctName": "LNQ169111697028608",
  "toAcctNo": "004896102184"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
商户订单号	merOrderNo	string(32)	M	商户自定义的唯一订单号
收款方账号	toAcctNo	string(32)	M	收款方账号
收款方账户名	toAcctName	string(255)	M	收款方账户名
转账币种	currency	string(3)	M	转账币种
转账金额	amount	Decimal(18,2)	M	转账金额
汇款目的	purpose	string(3)	M	汇款目的，参见附录6.1.4付款目的
附言	remark	string(255)	O	附言

{
  "bizFlow": "70483082509451100044",
  "feeAmount": "1.28",
  "feeCurrency": "USD",
  "status": "SUCC"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
业务流水号	bizFlow	string(32)	M	OTT侧唯一业务订单号
结果状态	status	string(6)	M	结果状态 SUCC：成功 FAIL：失败
手续费币种	feeCurrency	string(3)	O	手续费币种，若手续费模式为实时收取时，则返回此字段
手续费金额	feeAmount	string(22)	O	手续费金额，若手续费模式为实时收取时，则返回此字段

5.8 充值

5.8.1 充值交易历史查询

1 功能描述

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

2 请求地址

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

Method： POST

{
  "batchNo":"11473082516153900018"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
查询起始时间	beginDate	Long	O	Unix13位时间戳，查询开始时间，闭区间
查询结束时间	endDate	Long	O	Unix13位时间戳，查询开始时间，闭区间
业务订单号	batchNo	String(32)	O	OTT生成的唯一流水号
充值银行	bankCode	String(8)	O	充值银行代码
充值币种	currency	String(3)	O	充值币种
查询最小金额	minAmount	decimal(18,2)	O	查询最小金额
查询最大金额	maxAmount	decimal(18,2)	O	查询最大金额
充值状态	status	String(3)	O	充值状态 01: "待处理"; 02: "充值成功"; 03: "充值拒绝"
第几页	pageNum	Integer	O	查询第几页
每页多少条	pageSize	Integer	O	每页多少条，每页最多支持100条

{
  "list": [
    {
      "account": "终极测试",
      "acctNo": "100058384000",
      "actualAmt": 810.8,
      "amount": 820,
      "bank": "星展银行(客户资金)",
      "batchNo": "11473082516153900018",
      "createTime": 1692951339000,
      "curType": "USD",
      "feeAmt": 9.2,
      "feeCurType": "USD",
      "merchantName": "终极测试",
      "merchantNo": "004401100035",
      "payerName": "终极测试",
      "remark": "",
      "status": "02",
      "updateTime": "2023-08-25 16:15:40"
    }
  ],
  "pageNum": 1,
  "pageSize": 10,
  "pages": 1,
  "total": 1
}

4 响应字段

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

RechargeRecord 的字段

名称	Json标签	类型	属性	取值说明
充值订单	batchNo	string(32)	M	充值订单
充值币种	curType	string(3)	M	充值币种，3位标准货币代码
充值金额	amount	decimal(18,2)	M	充值金额
实际入账金额	actualAmt	decimal(18,2)	M	实际入账金额
充值银行	bank	string(64)	M	充值银行
充值账户	account	string(64)	M	充值账户
充值状态	status	string(2)	M	充值状态 01: "待处理"; 02: "充值成功"; 03: "充值拒绝"
入账时间	updateTime	Date	M	入账时间
手续费金额	feeAmt	decimal(18,2)	O	手续费金额
手续费币种	feeCurType	string(3)	O	手续费币种
充值账号	acctNo	string(32)	O	充值账号
付款方名称	payerName	string(255)	O	付款方名称

5.8.2 充值成功通知

1 功能描述

交易代码	TP2011
功能名称	充值成功通知
功能描述	充值成功通知
调用方式	通知接口
调用流程	--
应用场景	在商户的充值请求审核成功后，OTTPAYHK会向商户发送充值成功通知

2 请求地址

Url： 【待补充】callbackUrl

Method： POST

{
  "account": "终极测试",
  "acctNo": "100058384000",
  "actualAmt": 810.8,
  "amount": 820,
  "bank": "星展银行(客户资金)",
  "batchNo": "11473082516153900018",
  "curType": "USD",
  "feeAmt": 9.2,
  "feeCurType": "USD",
  "merchantName": "终极测试",
  "merchantNo": "004401100035",
  "payerName": "终极测试",
  "rechargeTime": 1692951339,
  "remark": ""
}

3 请求字段

名称	Json标签	类型	属性	取值说明
充值订单号	batchNo	string(32)	M	充值订单号
商户号	merchantNo	string(24)	M	商户号
商户名称	merchantName	string(128)	M	商户名称
充值币种	curType	string(3)	M	充值币种，3位标准货币代码
充值金额	amount	decimal(18,2)	M	充值金额
实际入账金额	actualAmt	decimal(18,2)	M	实际入账金额
入账时间	rechargeTime	Long	M	入账时间
备注	remark	string(255)	O	备注
充值银行	bank	string(32)	O	充值银行
手续费金额	feeAmt	decimal(18,2)	O	手续费金额
手续费币种	feeCurType	string(3)	O	手续费币种
充值账号	acctNo	string(32)	O	充值账号
充值账户	account	string(255)	O	充值账户
付款方名称	payerName	string(255)	O	付款方名称

5.9 提现

5.9.1 提现接口

1 功能描述


交易代码	TP1008
功能名称	提现交易申请
功能描述	用于发起境外提现，需提现账户名与商户注册名称相同
调用方式	实时接口
调用流程	--
应用场景	用于发起境外提现，需提现账户名与商户注册名称相同

2 请求地址

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

Method： POST

{
  "amount": "200",
  "bankAccountNo": "6248348300000000",
  "bankAddress": "New York",
  "bankName": "Citibank",
  "callbackUrl": "https://www.baidu.com",
  "currency": "USD",
  "merOrderNo": "LNQ1692952039986",
  "remark": "取笔钱",
  "swiftCode": "7643843"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
商户订单号	merOrderNo	string(32)	M	商户传入本次交易唯一订单号
币种	currency	string(3)	M	提现币种，3位标准货币代码
金额	amount	decimal(18,2)	M	提现金额
银行账号/IBAN	bankAccountNo	string(64)	M	提现银行账号或IBAN
银行名称	bankName	string(64)	M	提现银行名称
银行地址	bankAddress	string(256)	M	提现银行的地址
swift code	swiftCode	string(32)	M	提现银行的swift code
代理行名称	proxyBankName	string(64)	O	代理行名称
代理行地址	proxyBankAddress	string(256)	O	代理行地址
代理行swift code	proxySwiftCode	string(32)	O	代理行swift code
汇款附言	remark	string(64)	O	汇款附言
回调url	callbackUrl	string(256)	M	回调通知Url

{
  "bizFlow": "51823082516272000024",
  "code": "S00001",
  "merOrderNo": "LNQ1692952039986",
  "message": "S00001",
  "status": "ACCEPT"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
商户订单号	merOrderNo	string(32)	M	商户传入本次交易唯一订单号
业务流水号	bizFlow	string(32)	M	OTT生成的唯一流水号
状态	status	string(8)	M	交易结果状态
结果码	code	string(8)	M	交易结果代码
结果描述	message	string(64)	M	交易结果描述

5.9.2 提现交易历史查询

1 功能描述

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

2 请求地址

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

Method： POST

{
  "bizFlow":"51823082516272000024"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
查询起始时间	startTime	Long	O	Unix13位时间戳，查询开始时间，闭区间
查询结束时间	endTime	Long	O	Unxi13位时间戳，查询结束时间，闭区间
业务订单号	bizFlow	String(32)	O	OTT生成的唯一流水号
商户订单号	merOrderNo	String(32)	O	商户订单号

{
  "list": [
    {
      "amount": 200,
      "bankAccountName": "Final Test",
      "bankAccountNo": "6248348300000000",
      "bankAddress": "New York",
      "bankName": "Citibank",
      "bizFlow": "51823082516272000024",
      "code": "S00000",
      "currency": "USD",
      "merOrderNo": "LNQ1692952039986",
      "message": "Processing",
      "remark": "Success",
      "status": "SUCC",
      "swiftCode": "7643843"
    }
  ]
}

4 响应字段

返回对象是List<WithdrawBean>

WithdrawBean 的字段

名称	Json标签	类型	属性	取值说明
商户订单号	merOrderNo	string(32)	M	商户传入本次交易唯一订单号
币种	currency	string(3)	M	提现币种，3位标准货币代码
金额	amount	decimal(18,2)	M	提现金额
提现账户名称	bankAccountName	string(64)	M	提现账户名称
银行账号/IBAN	bankAccountNo	string(64)	M	提现银行账号或IBAN
银行名称	bankName	string(64)	M	提现银行名称
银行地址	bankAddress	string(256)	M	提现银行的地址
swift code	swiftCode	string(32)	M	提现银行的swift code
代理行名称	proxyBankName	string(64)	O	代理行名称
代理行地址	proxyBankAddress	string(256)	O	代理行地址
代理行swift code	proxySwiftCode	string(32)	O	代理行swift code
汇款附言	remark	string(64)	O	汇款附言
回调地址	callbackUrl	string(256)	M	回调地址
业务流水号	bizFlow	string(32)	M	OTT生成的唯一流水号
交易结果状态	status	string(8)	M	交易结果状态
交易结果码	code	string(8)	M	交易结果码
结果描述	message	string(64)	M	交易结果描述
提现发起时间	createTime	long	M	提现发起时间

5.9.3 提现结果通知

1 功能描述


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

2 请求地址

Url： 提现交易中的 callbackUrl

Method： POST

{
  "amount": 200,
  "bankAccountName": "Final Test",
  "bankAccountNo": "6248348300000000",
  "bankAddress": "New York",
  "bankName": "Citibank",
  "bizFlow": "51823082516272000024",
  "code": "S00000",
  "currency": "USD",
  "merOrderNo": "LNQ1692952039986",
  "message": "Processing",
  "remark": "Success",
  "status": "SUCC",
  "swiftCode": "7643843"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
商户订单号	merOrderNo	string(32)	M	商户传入本次交易唯一订单号
币种	currency	string(3)	M	提现币种，3位标准货币代码
金额	amount	decimal(18,2)	M	提现金额
提现账户名称	bankAccountName	string(64)	M	提现账户名称
银行账号/IBAN	bankAccountNo	string(64)	M	提现银行账号或IBAN
银行名称	bankName	string(64)	M	提现银行名称
银行地址	bankAddress	string(256)	M	提现银行的地址
swift code	swiftCode	string(32)	M	提现银行的swift code
代理行名称	proxyBankName	string(64)	O	代理行名称
代理行地址	proxyBankAddress	string(256)	O	代理行地址
代理行swift code	proxySwiftCode	string(32)	O	代理行swift code
汇款附言	remark	string(64)	O	汇款附言
业务流水号	bizFlow	string(32)	M	OTT生成的唯一流水号
交易结果状态	status	string(8)	M	交易结果状态
交易结果码	code	string(8)	M	交易结果码
结果描述	message	string(64)	M	交易结果描述

5.10 手续费

5.10.1 手续费交易历史查询

1 功能描述

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

2 请求地址

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

Method： POST

{
  "beginDate": "1654012800000",
  "endDate": "1656691199999",
  "pageNum": 1,
  "pageSize": 2
}

3 请求字段

名称	Json标签	类型	属性	取值说明
查询起始时间	beginDate	Long	O	Unix13位时间戳，查询开始时间，闭区间
查询结束时间	endDate	Long	O	Unix13位时间戳，查询开始时间，闭区间
业务订单号	batchNo	String(32)	O	OTT生成的唯一流水号
业务类型	busiType	String(6)	O	业务类型
手续费状态	status	String(3)	O	手续费状态 10: "未收取", 11: "已收取", 12: "已退回"
第几页	pageNum	Integer	O	查询第几页
每页多少条	pageSize	Integer	O	每页多少条，每页最多支持100条

{
  "list": [
    {
      "batchNo": "62782070121531600019",
      "bizType": "000020",
      "feeCurrency": "HKD",
      "feeTradeAmt": 1,
      "feeType": "10",
      "remark": "收款手续费流水",
      "status": "11",
      "tradeAmt": 21,
      "tradeCurrency": "GBP",
      "tradeTime": "2022-07-01 21:53:18"
    },
    {
      "batchNo": "62782070121461400016",
      "bizType": "000020",
      "feeCurrency": "HKD",
      "feeTradeAmt": 1,
      "feeType": "10",
      "remark": "收款手续费流水",
      "status": "11",
      "tradeAmt": 21,
      "tradeCurrency": "GBP",
      "tradeTime": "2022-07-01 21:46:15"
    }
  ],
  "pageNum": 1,
  "pageSize": 2,
  "pages": 131,
  "total": 261
}

4 响应字段

名称	Json标签	类型	属性	取值说明
当前页码	pageNum	Int	M	--
页显示数	pageSize	Int	M	--
总数	total	Int	M	--
手续费信息集合	list	`List<FeeFlowRes>`	M	--

FeeFlowRes 的字段

名称	Json标签	类型	属性	取值说明
订单号	batchNo	string(32)	M	订单号
商户订单号	merSingleBatchNo	string(32)	O	商户传入本次交易唯一订单号
业务类型	bizType	String(6)	M	业务类型
手续费币种	feeCurrency	String(3)	O	手续费币种，3位标准货币代码
手续费币种对应交易金额	feeTradeAmt	decimal(18,2)	M	手续费币种对应交易金额
手续费状态	status	string(2)	M	手续费状态 10: "未收取", 11: "已收取", 12: "已退回"
交易币种	tradeCurrency	string(3)	M	交易币种，3位标准货币代码
交易金额	tradeAmt	decimal(18,2)	M	交易金额
交易时间	tradeTime	Date	M	交易时间
备注	remark	string(1024)	M	备注

5.11 账务

5.11.1 账户余额查询

1 功能描述

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

2 请求地址

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

Method： POST

{

}

3 请求字段

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

[
  "list": [
    {
      "balance": "108130286.44",
      "currency": "USD",
      "status": "on"
    },
    {
      "balance": "146204.15",
      "currency": "EUR",
      "status": "on"
    },
    {
      "balance": "10193838.00",
      "currency": "JPY",
      "status": "on"
    },
    {
      "balance": "9504470.68",
      "currency": "HKD",
      "status": "on"
    },
    {
      "balance": "8892161.38",
      "currency": "CNY",
      "status": "on"
    },
    {
      "balance": "0.00",
      "currency": "IDR",
      "status": "on"
    },
    {
      "balance": "17920.68",
      "currency": "GBP",
      "status": "on"
    },
    {
      "balance": "8494.97",
      "currency": "DKK",
      "status": "on"
    },
    {
      "balance": "0.00",
      "currency": "SGD",
      "status": "on"
    },
    {
      "balance": "120.00",
      "currency": "AUD",
      "status": "on"
    },
    {
      "balance": "0.00",
      "currency": "CHF",
      "status": "on"
    },
    {
      "balance": "0.00",
      "currency": "KRW",
      "status": "on"
    },
    {
      "balance": "0.00",
      "currency": "NGN",
      "status": "on"
    },
    {
      "balance": "0.00",
      "currency": "NOK",
      "status": "on"
    },
    {
      "balance": "0.00",
      "currency": "NZD",
      "status": "on"
    },
    {
      "balance": "0.00",
      "currency": "SEK",
      "status": "on"
    }
  ]
]

4 响应字段

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

CurrencyBalance 字段：

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

5.11.2 账务流水交易查询

1 功能描述

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

2 请求地址

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

Method： POST

{
  "beginDate": "1654012800000",
  "endDate": "1656691199999",
  "pageNum": 1,
  "pageSize": 2
}

3 请求字段

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

{
  "list": [
    {
      "applyNo": "62782070121531600019",
      "batchNo": "62782070121531600019",
      "busiDate": "2022-07-01 21:53:18",
      "busiType": "C11",
      "currency": "HKD",
      "id": 0,
      "outAmount": 1,
      "totalAmount": 60514.33,
      "vailAmount": 50333.6
    },
    {
      "applyNo": "62782070121531600019",
      "batchNo": "62782070121531600019",
      "busiDate": "2022-07-01 21:53:18",
      "busiType": "C13",
      "currency": "GBP",
      "id": 0,
      "inAmount": 21,
      "totalAmount": 29078.31,
      "vailAmount": 10352.31
    }
  ],
  "pageNum": 1,
  "pageSize": 2,
  "pages": 310,
  "total": 620
}

4 响应字段

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

CurFlowRes 的字段

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

5.12 配置

5.12.1 回调地址设置

1 功能描述


交易代码	TP1014
功能名称	对于通知接口，设置回调地址
功能描述	对于通知接口，设置回调地址
调用方式	实时接口
调用流程	--
应用场景	对于无交易传参的callback接口，单独设置回调地址

2 请求地址

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

Method： POST

{
  "tradeCode": "TP2007",
  "callbackUrl": "https://www.baidu.com"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
回调地址	callbackUrl	string(64)	M	回调地址
接口类型	tradeCode	string(6)	M	回调的接口类型

{
  "code": "SUCC"
}

4 响应字段

名称	Json标签	类型	属性	取值说明
结果码	code	string(6)	M	SUCC代表成功

6 附录

6.1 字段说明

6.1.1 paymentType 交易类型

字段值	说明	备注
B2B	企业对企业	--
B2C	企业对个人	--
C2B	个人对企业	--
C2C	个人对个人	--

6.1.2 tradeCodeType 交易编码

字段值	说明	备注
TRADE	一般货物贸易-网络购物	一般货物贸易-网络购物
TRADE_OFFLINE	一般货物贸易-线下	一般货物贸易-线下具有进出口经营权的企业的进出口贸易可选择该类型进行结汇
E_COMMERCE	电商	电商
AIRLINE_TICKET	旅行	境内/境外个人境外旅游途中餐费、交通费用、门票等的合并费用
STUDY_ABROAD	教育相关的学生开支	境内/境外个人境外留学，期限在一年及以内；出境参加培训产生的费用
SOFTWARE	咨询费、技术服务、学术费、专家费	商业、管理咨询和公共关系服务指为企业提供的业务政策、战略规划和总体规划方面的咨询、指导和业务援助服务，以及在企业管理方面提供的服务。具体可以是管理审计、市场管理、人力资源管理、生产管理和项目管理咨询。包括：1、母企业或其他关联企业向分支机构、子公司或联营企业提供的一般管理服务。 2、与管理有关的资格认证。 3、国际团体的会员费及注册费。 4、与管理咨询和公共关系服务有关的公证费等。
LOGISTICS	货物物流费	跨境物流
INFO_CHARGES	信息服务费	软件和数据处理服务，计算机硬件维修和维护
ADVER_SERVICE	广告或公关费用	广告代理机构进行的广告设计、创意和市场营销服务。媒体投放、购买和出售广告空间、产品在国外的推广服务以及电话推销等各类服务。
SALARY	职工薪酬	居民雇员从非居民雇主处获得的工资、薪金和福利，以及居民雇主向非居民雇员支付的工资、薪金和福利
ONLINE_GAME	网络游戏装备费	网络游戏装备
LEGAL_SERVICE	法律服务	与法律有关的资格认证、公证费等。
ACCOUNTING_SERVICE	会计服务	会计、审计、记账和税务咨询服务指记录商业交易、对会计记录和财务报表进行审计、营业税规划咨询服务以及准备税务文件等服务。
INSURANCE_SERVICE	保险服务	保险投保费用支付，包括：意外险、医疗保险等。注：不包含人寿险保费、保险理赔。
INTERNATIONAL_CONFERENCE	国际会议	出境参加国际会议所产生的费用
EXHIBITION_SERVICE	展会服务	包括展览、会展服务，及展会摊位租赁费用。
COMMISSION	佣金	为境外电商平台、网站境内推广佣金、打赏
TRANSLATION_SERVICE	翻译服务	翻译服务
EDUCATION_SERVICE	教育服务	互联网课程教育费
MEDICAL_SERVICE	医疗服务	医疗保险、意外险理赔款
FAMILY_MAINTENANCE	赡家款	赡家款

6.1.3 payMethod 支付方式

字段值	说明	备注
cash_on_delivery	支付方式为货到付款	货到付款
advance	支付方式为预付款	预付款

6.1.4 purpose 付款目的

字段值	汇款目的（en）	汇款目的（zh）
1	Transfer to own account	付款至自己账户
2	Family Maintenance	赡家款
3	Education-related student expenses	教育相关的学生开支
4	Medical Treatment	医疗费
5	Hotel Accomodation	酒店费用
6	Travel	旅行
7	Utility Bills	支付水电煤等基础设施账单
8	Repayment of Loans	归还借款
9	Tax Payment	支付税款
10	Purchase of Residential Property	购买住宅
11	Payment of Property Rental	支付房屋租金
12	Insurance Premium	保险预付
13	Product indemnity insurance	产品保险
14	Insurance Claims Payment	支付保费
15	Mutual Fund Investment	共同基金投资
16	Investment in Shares	股权投资
17	Donations	捐赠
18	Information Service Charges	信息服务费
19	Advertising & Public relations-related expenses	广告或公关费用
20	Royalty fees, trademark fees, patent fees, and copyright fees	忠诚服务费、商标费、专利费以及著作权费用
21	Fees for brokers, front end fee, commitment fee, guarantee fee and custodian fee	交易费、担保费、保理费
22	Fees for advisors, technical assistance, and academic knowledge, including remuneration for specialists	咨询费、技术服务、学术费、专家费
23	Representative office expenses	代表处开支
24	Construction costs/expenses	建筑建设费用
25	Transportation fees for goods	商品转移费
26	For payment of exported goods	出口货物货款支付
27	Delivery fees for goods	商品物流费
28	General Goods Trades - Offine trade	常规线下货物贸易
29	Other services charges	其他服务贸易支出
30	Salary / Commission Payment	工资或佣金支付
31	Fixed Maintenance Expenses	定期维护费用
99	Other fees (Please specify)	其他费用（请详述）

6.1.5 bizType 业务类型

字段值	说明
000008	电商收款手续费
000012	VA月度管理费
000013	贸易收款手续费
000015	平台月度维护费
C00001	跨境人民币入境"
C00002	全球下发
C00003	平台入金手续费
C00004	平台提现手续费

6.1.6 busiType 流水类型

字段值	说明
C00	账务流水
C01	换汇
C02	换汇退回
C05	人民币付款
C06	人民币付款退回
C07	外币付款
C08	外币付款退回
C09	提现
C10	提现退回
C11	手续费
C12	手续费退回
C13	收款
C20	账户间转账
C21	账户间转账手续费
C22	入账费
C23	平台管理费
C24	结汇付款
C25	结汇退回
C26	充值退款
C27	收款退款
C28	退款手续费
C29	收款结算
C30	收款结算退回

6.1.7 tradePurpose 汇款用途代码

字段值	说明
GOODSTRADE	Goods Trade
PLANETICKET	Plane Ticket
HOTELACCOMMODATION	Hotel Accommodation
STUDYABROAD	Study abroad (long)
STUDYABROAD2	Study abroad (short)
TRAVEL	Travel (private)
TRAVEL2	Travel (public)
SOFTWARE	Software Service
COMMUNICATION	Coummunication
TRANSPORT	Logistics (import sea transportation)
TRANSPORT2	Logistics (export sea transportation)
TRANSPORT3	Logistics (export air transportation)
TRANSPORT4	Logistics (import air transportation)
TRANSPORT5	Logistics (export land transportation)
TRANSPORT6	Logistics (import land transportation)
TRANSPORT7	Logistics (postal service)

6.1.8 sourceFunds 资金来源

字段值	说明
0	UBO (最终受益人) 资本投资UBO
1	经营多年的业务收益 / 贷款收入
2	公司向银行贷款
3	UBO 继承遗产 / 家庭信托基金
4	家庭礼物或非股东礼物
5	保险收益 / 到期结算
6	法律案件的赔偿金
7	买卖股票投资收益 / 回报
8	奖金（政府或收据式彩票）
9	赌博或奖金（非收据式彩票）
10	出售公司或公司股票的收益
11	商业或住宅物业的销售
12	出售公司投资收拥有的收益

6.1.9 paymentPurpose 付款目的

字段值	说明
0	建筑和装修（商业或住宅都适用）
1	支付中国或国外供应商
2	珠宝和手表出售或购买的支付
3	定期工资和佣金支付
4	法律、会计、秘书, 顾问, 专家费
5	技术维护/系统开发服务的支付
6	个人或家庭日常开支
7	行政和办公室日常运营开支
8	房地产投资
9	有形资产托管
10	汇款至同名账户
11	版权、商标, 牌照, 许可证的支付
12	差旅住宿费用（公司和个人均适用）
13	水电煤气, 公共事业缴费
14	医疗和住院费用
15	教育费关包括大学学费, 寄宿费, 研讨会
16	写字楼、商业及住宅租赁相关
17	商户结算
18	服务平台月费, 定期维护费用
19	物流, 仓储, 运输费
20	商业（个人）税款相关支付-修改
21	保险索赔、保费、退保和赔偿
22	信贷, 归还借款信贷
23	其他金融投资产品
24	付款家庭成员/直系亲属
25	金钱捐赠和礼物
26	所有其他类型的短期 (一年以下)投资
27	无形资产托管
28	汇款给非关联第三方公司和非亲属

6.1.10 customerIdentity 客户身份

字段值	说明
0	法人代表
1	公司董事
2	持股25%以上的股东
3	以上都不是

6.1.11 natures 货贸业务性质

字段值	说明
4	1.防锈剂, 润滑剂, 石蜡, 盐酸油漆染料
5	2.易燃品: 盐酸, 硫酸, 聚氯乙烯, 异丙醇, 甲醇等
8	1.谷物蔬菜及水果
9	2.乳类
10	3.肉类
11	4.鱼类及海产
12	5.粮食原材料
14	1.书籍与文具
15	2.礼品, 印刷和包装
16	3.体育用品
17	4.玩具及电子游戏机
18	5.玩具制造
20	1.家用电器灯饰影音
21	2.商用机械
23	1.摄影录音器材
24	2.眼镜及光学用品
25	3.电子通讯,手表和零件
26	10.羽毛及皮革制品
27	11.防火和防护安全装备（已作废）
29	13.燃气、石油及煤产品
33	17.矿物及其他原料
37	1.珠宝钟表, 珍珠玉器
38	2.人造及仿制首饰
39	3.钱币古玩, 油画雕刻工艺品
40	1.水族、宠物护理用品
41	2.农药, 种植和园艺用品
42	1.烟草、酒精饮品
43	2.非酒精饮品
44	3.茶叶咖啡及可可
45	1.鞋, 成衣, 袋类
46	2.防护服, 安全面盔和检测工具
47	3.布料及附属用品
48	6.餐饮品供应 Food & Beverages
49	6.音乐和乐器
50	3.警报防盗电锁
51	1.家具,厨厕具
52	2.地毡窗帘镜器五金器具
53	1.轻型工商业用机械
54	2.钻机,钻探机械和组件
55	3.橡胶塑料或合成材料机械和组件
56	4.车辆维修和配件备件
57	5.农业机设备及零件
58	6.建筑机械工具和卫生设备
59	7.建材, 水泥, 木材和材料加工
60	8.废金属, 杂物和废原材料
61	9.电池,引擎,涡轮机
62	1.医疗设备检测工具
63	2.物理治疗设备,药品和保健品
64	1.钢铁铜铝铅镍锡锌合金产制品
65	2.其他五金材料
66	1.通讯电子零件和产品
67	2.无线网络零件和产品
68	1. 家居清洁,个人护理,美妆品
69	1.建材, 水泥, 木材和材料加工
85	1.防火和防护安全装备
86	2.各类蓄电池、锂离子电池

6.1.12 natures 服贸贸业务性质

字段值	说明
2	1.电子商务和系统开发
3	2.商业程序
4	3.游戏程序
5	4.技术检测和维护
6	5.系统安全和咨讯安全
8	1.持牌第三方支付运营商
9	2.持牌银行
10	3.持牌资产管理
11	4.持牌外汇交易平台商及外币兑换店
12	5.融资财务公司
13	6.储值支付工具
14	7.信托服务
15	8.充值支付,预付卡,电子钱包平台
16	9.债务重组及追收
17	4.保险业服务
19	1.地产租赁
20	2.地产买卖
21	3.物业代理
22	4.楼宇管理及物业保养服务
24	1.通讯、电讯服务，如流动虚拟网络营办商、对外电讯服务
25	2.航空器上流动通讯服务
26	3.因特网接入
27	4.国际电话卡、话音邮箱服务及国际增值网络
28	5.其他
30	1.海外院校入学服务
31	2.驾驶学校服务
32	3.海外留学住宿
33	4.海外留学交通服务
35	1.法律
36	2.会计及商业关税
37	3.移民顾问
38	4.职业介绍(人力资源和就业介绍)
39	5.广告及公共关系
40	6.秘书及翻译服务
41	7.专利注册
42	8.旅行社航旅咨询
43	9.机械及商用设备租赁
44	10.保安顾问和系统设置
47	11.人类保健及社会工作活动
50	1.公共行政
51	2.生活相关,摄影,侦探,家庭教师,家佣
52	3.拍卖行
53	4.商会及厂商会等
54	5.贵宾保安服务
55	14.采矿及采石
57	1.仅限海陆空物流运输费
58	2.仓库租赁仓储费
59	3.邮政及速递服务
60	4.护卫及武装运送服务
61	10.持牌借贷公司
62	11.贵金属和大宗商品买卖
63	12.手机支付
64	13.非持牌经营支付交易
65	11.财务管理规划顾问
66	12.设计(产品,时装,其他)
67	1.物业维修, 保养, 设备安装
68	2.废金属杂物和废料
69	3.室内设计装饰及工程
70	1.酒店和住宿
71	2.餐饮,承包膳食,外卖服务
72	1.博物馆和美术馆
73	2.健身,体育运动,舞蹈芭蕾
74	3.青少年和儿童中心
75	4.电视电影,歌剧,管弦乐
76	5.媒体服务
77	6.時装表演,表演团体
78	1.清洁服务包括空调,车辆,建筑物
79	2.供水和污水废物管理
80	3.废料回收
81	16.多层直销
82	17.大型连锁店/百货商店
83	18.能源管理及环境顾问服务

6.1.16 turnover 营业额

字段值	说明
0	0-10万美金
1	10万到100万美金
2	100万到1000万美金
3	1000万到1亿美金
4	1亿以上美金
5	未能提供

6.1.17 transaction 交易量

字段值	说明
0	0-5万美金
1	5万美金-10万美金
2	10万-50万美金
3	50万-100万美金
4	100万-500万美金
5	500万以上美金
6	大约不超过营业额的25%

6.1.18 payeeType 收款人分类

类型	收款人分类枚举值	收款人类型	收款人分类
货贸(含电商)	1001	企业	供应商
货贸(含电商)	1002	企业	广告商
货贸(含电商)	1003	企业	物流商
货贸(含电商)	1004	企业	代理商
货贸(含电商)	1005	企业	其他服务商
货贸(含电商)	1006	企业	关联公司（同法人/股东）
货贸(含电商)	2001	个人	企业的法人/董事/股东/被授权人
货贸(含电商)	2002	个人	服务商
货贸(含电商)	2003	个人	员工
货贸(含电商)	2004	个人	企业供应商的法人/董事/股东

6.1.19 identityType 持有人身份类型

身份类型	枚举值	对应持有人类型	可做操作
法人/董事	01	个人	查询，补充材料
股东	02	个人	查询，补充材料
被授权人	03	个人	查询，补充材料
员工	04	个人	查询，新增，修改
本地化运营销售经理	05	个人	查询，新增，修改
其他	06	个人	查询，新增，修改
公司本身	11	企业	查询
关联公司	12	企业	查询，新增，修改
代运营销售公(母公司/子公司)	13	企业	查询，新增，修改
其他	14	企业	查询，新增，修改

6.1.20 certificateType 证件类型

证件类型	枚举值	对应持有人类型	备注
身份证	01	个人	注册国家/地区为CN必选，注册国家/地区为非CN可选
护照	02	个人	注册国家/地区为非CN可选
统一社会信用代码	03	企业	注册国家/地区为CN必选
企业注册证书	04	企业	注册国家/地区为HK必选
企业注册证明书	05	企业	注册国家/地区为非HK/非CN必选

6.1.21 holderStatusType 持有人状态类型

状态	枚举值	备注
正常	00	审核成功
待审核	10	已提交，等待审核
审核拒绝	20	审核拒绝
禁用	30	审核成功后的持有人被禁用
待补充信息	40	入网成功后自动生成的持有人信息补充信息
补充待审核	50	入网成功后自动生成的持有人信息补充待审核
补充审核拒绝	60	入网成功后自动生成的持有人信息补充审核拒绝

6.1.22 错误返回码

错误返回码

6.1.23 通用状态描述

状态枚举	状态描述
ACCEPT	处理中
SUCC	成功
FAIL	失败
PROCESS	已确认，处理中
QUOTE	待确认

6.1.24 materials 补充材料信息

收款人类型	收款人分类
供应商	与该收款人的采购合同等
广告商	与该收款人的广告推广协议等
物流商	与该收款人的物流服务合同等
代理商	与该收款人的出口代理合同等
其他服务商	与收款人的合作协议或沟通记录、市场采购平台订单等
服务商	与该收款人的咨询协议或代运营协议等
员工	与该收款人之间的劳务协议等
企业供应商的法人/董事/股东	与该收款人之间的企业间合作协议等

6.2 解决方案

换付类客户解决方案

收款平台类客户解决方案

7 mock说明

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

7.1 TP1020

商户入网mock数据时根据入网英文名最后一位判断，0,1,2,3则入网成功，4,5,6则入网拒绝，7,8,9则为审核中。入网成功后，可进行如下交易：VA开户；收款币种为USD的收款交易；付款币种是USD的国际汇款(local/swift) ；人民币付款；美元提现；CNY/USD的换汇交易

7.2 TP1003

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

7.3 TP1005

国际汇款交易确认审核mock数据时根据TP1004接口设置的扣款金额或者收款金额个位数金额设置状态，扣款金额和收款金额2选1填写，若同时填写，以收款金额为准，0,1,2,3则审核成功，4,5,6则审核拒绝，7,8,9则不作操作。

7.4 TP1008

提现申请审核mock数据时根据bankAccountNo最后一位设置状态0,1,2,3则审核成功，4,5,6则审核拒绝，7,8,9则不作操作。

7.5 TP1017

va开户审核mock数据时根据merOrderNo最后一位数字设置状态，0,1,2,3则审核成功，4,5,6则审核拒绝，7,8,9则不作操作。

7.6 TP1013

收款流水和贸易订单关联审核mock数据时根据TP1012申请的amount金额设置状态，个位数0,1,2,3则审核成功，4,5,6则审核拒绝，7,8,9则不作操作。

7.7 TP1001

人民币付款mock数据时根据收款人列表中的payeeAccountNo最后一位来决定交易状态，0,1,2,3则付款成功，4,5,6则付款失败，7,8,9则是处理中

7.8 test1001收款模拟

1 功能描述


交易代码	test1001
功能名称	收款模拟
功能描述	收款模拟，发送收款通知
调用方式	异步通知
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "amount": "300",
  "bankAccountNo": "798361124545",
  "bankIncomeTime": "2023-08-23 00:00:00",
  "currency": "USD",
  "payerName": "20230823001.ltd"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
收款金额	amount	decimal(18,2)	M	收款金额
入账VA账户号	bankAccountNo	String(16)	M	入账的VA账户号，确认VA号已开户完成
收款入账时间	bankIncomeTime	String(32)	M	收款入账时间格式 yyyy-MM-dd HH:mm:ss
收款币种	currency	String(3)	M	收款币种
付款方名称	payerName	String(32)	M	付款方名称

{
  "amount": "300",
  "bankAccountNo": "798361124545",
  "bankIncomeTime": "2023-08-23 00:00:00",
  "currency": "USD",
  "payerName": "20230823001.ltd"
}

4 响应字段
无需关心响应字段，等待收款通知

7.9 test1002充值模拟

1 功能描述


交易代码	test1002
功能名称	充值模拟
功能描述	充值模拟，发送充值通知
调用方式	异步通知
调用流程	---
应用场景	---

2 请求地址

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

Method： POST

{
  "amount": "300",
  "bankIncomeTime": "2023-08-23 00:00:00",
  "currency": "USD"
}

3 请求字段

名称	Json标签	类型	属性	取值说明
充值金额	amount	decimal(18,2)	M	充值金额
充值入账时间	bankIncomeTime	String(32)	M	充值入账时间格式 yyyy-MM-dd HH:mm:ss
充值币种	currency	String(3)	M	充值币种

4 响应字段
无需关心响应字段，等待充值通知