API 文档

# 越南支付API文档

# 1. 如何获取API Key

  用户登录收银台 -> 开发者中心 -> API Key -> 创建API key。API Key 都有单独的配置页，并绑定固定的 IP 地址（“0.0.0.0”表示不做 IP 拦截过滤，任何IP都可以访问），可配置不同的 API Key 满足不同的需求。请不要泄露您的 Access Key 及 Secret Key，以免造成资产损失。Secret Key 生成后将无法再次查看，请注意及时保存，如您忘记了 Secret Key，请在商户后台回收该密钥对并申请新的密钥对。

# 1.1 如何创建API KEY

• 点击开发者中心-API Key

• 1选择是否开启调试模式 ( 开启调试模式后，你有任何错误会有规范的提示信息和日志查看地址 )

• 2选择API Key权限

• 3输入白名单地址 (0.0.0.0 表示任意IP地址可以访问)

注：( 输⼊⽩名单域名时应注意多个IP时用","隔离。)

• 4点击创建，可⽣成API KEY

(⽣成API KEY后可以在下⽅我的API KEY列表进⾏复制、查看、编辑和删除等操作，注意Secret key只在生成的时候出现一次，请妥善保存，如您忘记了Secret Key,请回收该密钥对并申请新的密钥对。)

• 点击编辑可关闭或开启【开始调试】及修改API Key权限和白名单地址，修改完成后点击保存即可

注意：创建或编辑API Key之后请耐心等待90秒API Key生效

# 2. 如何使用API Key

当前API Key是在请求的Header中添加参数列表

参数名 参数说明 类型 是否必须
access_key Api Key 访问密钥 （如：TPhoa7ZQ） String 是
timestamp 毫秒级时间戳（13位 如：1679669488472） String 是
nonce UUID（36位 如：02f7a04f-53cc-47d4-bb3f-fae69dab49ac） 五个部分分别为8个字符、4个字符、4个字符、4个字符、12个字符，中间用“-”号间隔 String 是
sign 参数签名 （如：GXx2wYUD6UVr+zcmeCSFFPzcBLA=） String 是

# 3. 技术侧参数接入流程

# 4. 如何接口签名

# 签名说明

  API 请求在通过 internet 传输的过程中极有可能被篡改，为了确保请求未被更改，除公共接口（基础信息，行情数据等）外的私有接口均必须使用您的 API Key 做签名认证，以校验参数或参数值在传输途中是否发生了更改。

一个合法的请求由以下几部分组成：

  • access_key： API 访问密钥；
  • secret_key： 签名加密所使用的密钥（仅在后台申请 API Key 时可见一次，请复制保存在安全处，不可泄露）；
  • timestamp： 您发出请求的时间 (UTC 时间) 。如：1632811287325（13位）。在查询请求中包含此值有助于防止第三方截取您的请求；
  • nonce： 随机 UUID 字符串。如：053a1b81-48a0-4bb1-96b2-60f6e509d911（36位）；
  • sign： 签名计算得出的值，用于确保签名有效和未被篡改；
  • 所有接口都需要在http请求头 （header） 中传递以上除 secret_key 外的几个公共参数，公共参数包含（access_key ，timestamp，nonce，sign）其他涉及到签名参数以API接口说明为准 。

# 签名步骤

​ 1.定义一个 Map 字典类型对象，将请求中的参数以 key-value 的形式放入其中

​ 2.将 access_key、timestamp、nonce 也放入第一步定义的 Map 中

​ 3.将 Map 里面的属性按照 ASCII 码从小到大做升序排序（字典序）并将 Map 转换输出为“key1=value1&key2=value2” 形式的字符串

​ 4.将上一步转换的字符串用 secret_key 进行 HMAC_SHA1 加密并进行 Base64 转码，得到 sign 参数值。secret_key 是在收银平台创建的 apikey 中的信息

​ 5.将 sign 值和其他所需参数加到请求头 header 中，发送请求目标接口

# 签名调试工具

  • SignUtil: 用户登录收银台 -> 开发者中心 -> API 文档 -> 签名工具 打开签名工具页面 (工具中的access_key请使用有效的access_key 并且请设置允许这个access_key访问的IP白名单为 0.0.0.0,我们强烈推荐使用过的access_key调试完成后废弃)

# 5. 接口列表

# 5.1 测试接口连通性

请求方式

Get

请求URL

/ping

响应数据

{"version":"1.0.1","timestamp":1688116827306}

响应参数说明

Param Type Desc
version String 返回该参数则本文档中所有接口都可正常请求
timestamp int64 Unix时间戳

# 5.2 新建代收订单

请求方式

Post

请求URL

/api/v3/vn/createCollectingOrder

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
    "amount":"50000.00",
    "channelType":"BANK",
    "externalOrderId":"333333333222233322",
    "remark":"adkasd",
    "notifyUrl":"https://platform.hambit.co/#/home/dashboard",
    "returnUrl":"https://platform.hambit.co/#/home/dashboard"

}

请求参数说明

Param Desc Sample Require
amount 收款金额，小数点不能超过2位且金额不能低于50000越南盾（String） 50000.00 required
channelType 支付类型（String）oneof=BANK_SCAN_CODE,CARD_TO_CARD,MOMO,ZALO_PAY, VIETTEL_MONEY,BANK BANK_SCAN_CODE,CARD_TO_CARD,MOMO, ZALO_PAY,VIETTEL_MONEY,BANK 六种方式根据实际情况选择一个 required
externalOrderId 商户订单号 max=64 （String） 354997490558818072 required
notifyUrl 通知URL（String，URL） http://192.168.1.135:30001 optional
remark 备注 max=255（String） 123 optional
returnUrl 返回地址（String，URL） http://192.168.1.135:30001 optional

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": {
        "cashierUrl": "https://t-cashier-fiat.hambit.co/OCURRPAID202402270647391709016459845DEV001OO0000000200013586?data=eyJjYXNoaWVyQ3VycmVuY3lBbW91bnQiOjEwMDAwLjAwLCJjYXNoaWVyRXhwaXJlVGltZSI6MTcwOTAxODI2MDI0OSwiY2FzaGllcklkIjoiT0NVUlJQQUlEMjAyNDAyMjcwNjQ3MzkxNzA5MDE2NDU5ODQ1REVWMDAxT08wMDAwMDAwMjAwMDEzNTg2IiwiY2FzaGllclVybCI6Imh0dHBzOi8vdC1jYXNoaWVyLWZpYXQuaGFtYml0LmNvL09DVVJSUEFJRDIwMjQwMjI3MDY0NzM5MTcwOTAxNjQ1OTg0NURFVjAwMU9PMDAwMDAwMDIwMDAxMzU4NiIsImN1cnJlbmN5IjoiVk5EIiwiY3VycmVuY3lPcmRlclZvIjp7ImFtb3VudCI6MTAwMDAuMDAsImNoYW5uZWxJZCI6MTc2MDU1NTY1NDY3MDQ3NTI2NSwiY3VycmVuY3kiOiJWTkQiLCJleHRlcm5hbE9yZGVySWQiOiIzMzMzMzMzMzMyMjIyMzMyMzIyIiwibWVyY2hhbnROYW1lIjoiY2xhcmtfYWdlbnRfaGFtYml0Iiwib3JkZXJJZCI6Ik9DVVJSUEFJRDIwMjQwMjI3MDY0NzQwMTcwOTAxNjQ2MDc3OERFVjAwMU9PMDAwMDAwMDQwMDAxMzU4NyIsIm9yZGVyU3RhdHVzIjoiQXdhaXRpbmcgUGF5bWVudCIsIm9yZGVyU3RhdHVzQ29kZSI6MSwib3JkZXJUaW1lIjoxNzA5MDE2NDYwODAzLCJwYXlQYXJhbSI6Imh0dHBzOi8vYXBpLnY4cGF5LmNvbS92Mi9hdXRvL2RlcG9zaXQvYmFuay9uZXcvNjVkZDg1OGQ5NjI0YjhlYWQ0YTIwZTYyIiwicGF5VHlwZSI6MTAyLCJwYXlUeXBlTmFtZSI6IkJBTksiLCJwYXlVcmwiOiJodHRwczovL2FwaS52OHBheS5jb20vdjIvYXV0by9kZXBvc2l0L2JhbmsvbmV3LzY1ZGQ4NThkOTYyNGI4ZWFkNGEyMGU2MiIsInRyYWRlTm90ZSI6ImFka2FzZCJ9LCJpc0NyZWF0ZU9yZGVyIjp0cnVlLCJtZXJjaGFudElkIjoxNzA3Mjg1ODQwMzI2MTI3NjE3LCJwYXlUeXBlIjoxMDIsInJldHVyblVybCI6Imh0dHBzOi8vcGxhdGZvcm0uaGFtYml0LmNvLyMvaG9tZS9kYXNoYm9hcmQiLCJ2ZXJzaW9uIjoidjEifQ==&pm=W3siY3VycmVuY3lUeXBlIjoiTVhOIiwicGF5VHlwZXMiOlt7ImNvZGUiOjEwMiwidmFsdWUiOiJCQU5LIn0seyJjb2RlIjoxMTAsInZhbHVlIjoiT1hYTyJ9LHsiY29kZSI6MTExLCJ2YWx1ZSI6IkNhc2gifV19LHsiY3VycmVuY3lUeXBlIjoiTkdOIiwicGF5VHlwZXMiOlt7ImNvZGUiOjEwMiwidmFsdWUiOiJCQU5LIn0seyJjb2RlIjoxMDcsInZhbHVlIjoiQ2hhcmdlIn1dfSx7ImN1cnJlbmN5VHlwZSI6IklEUiIsInBheVR5cGVzIjpbeyJjb2RlIjoxMDIsInZhbHVlIjoiQkFOSyJ9LHsiY29kZSI6MTA0LCJ2YWx1ZSI6IlZpcnR1YWwgQWNjb3VudHMifSx7ImNvZGUiOjEwNSwidmFsdWUiOiJRUklTIn0seyJjb2RlIjoxMDYsInZhbHVlIjoiRVdhbGxldCJ9XX0seyJjdXJyZW5jeVR5cGUiOiJLRVMiLCJwYXlUeXBlcyI6W3siY29kZSI6MTA3LCJ2YWx1ZSI6IkNoYXJnZSJ9XX0seyJjdXJyZW5jeVR5cGUiOiJJTlIiLCJwYXlUeXBlcyI6W3siY29kZSI6MTAyLCJ2YWx1ZSI6IkJBTksifV19LHsiY3VycmVuY3lUeXBlIjoiQlJMIiwicGF5VHlwZXMiOlt7ImNvZGUiOjEwMSwidmFsdWUiOiJQSVgifSx7ImNvZGUiOjEwMywidmFsdWUiOiJQSVhfRFlOQU1JQyJ9LHsiY29kZSI6MTA5LCJ2YWx1ZSI6IkJvbGV0byJ9XX0seyJjdXJyZW5jeVR5cGUiOiJWTkQiLCJwYXlUeXBlcyI6W3siY29kZSI6MTAyLCJ2YWx1ZSI6IkJBTksifV19XQ==",
        "currency": "VND",
        "currencyOrderVo": {
            "orderId": "OCURRPAID202402270647401709016460778DEV001OO0000000400013587",
            "externalOrderId": "3333333332222332322",
            "currency": "VND",
            "amount": "10000",
            "tradeNote": "adkasd"
        }
    }
}

响应参数说明

Param Type Desc
cashierUrl String 收银台链接
currency String 币种编码
amount String 收款金额
externalOrderId String 商户订单号
orderId String 系统订单ID
tradeNote String 备注

# 5.3 新建代付订单

请求方式

Post

请求URL

/api/v3/vn/createTransferOrder

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
    "currencyAmount":"10.00",
    "channelType":"BANK",
    "externalOrderId":"6554516461231233222222222",
    "accountId":"222333331",
    "accountName":"wsxtes",
    "bankName":"Techcombank",
    "remark":"adkasd",
    "notifyUrl":"https://platform.hambit.co/#/home/dashboard",
    "returnUrl":"https://platform.hambit.co/#/home/dashboard"

}

请求参数说明

Param Desc Sample Require
currencyAmount 代付金额 小数不能大于2位（String） 40.20 required
channelType 支付类型 oneof= BANK（String） BANK required
externalOrderId 商户订单号 max=64（String） 687279463984441035 required
accountName 银行账号姓名 （String） bob required
accountId 收款账号（String） 222333331 required
bankName 银行名字（String）该字段传缩写 Techcombank根据实际情况 required
remark 备注 max=255（String） 123 optional
notifyUrl 通知URL（String） http://192.168.1.135:30001 optional

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": {
        "currencyType": "VND",
        "externalOrderId": "6554516461231233222222222",
        "orderId": "OCURRDRAW202402270637261709015846138DEV001OO0000000200013584",
        "orderStatus": "Accepted"
    }
}

响应参数说明

Param Type Desc
currencyType String 法币类型
externalOrderId String 商户订单id
orderId String 系统订单ID
orderStatus String 订单状态

# 5.4 查询代收订单

请求方式

Post

请求URL

/api/v3/vn/query/collectingOrder

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
    "externalOrderId":"333333333222233322",
    "orderId": "OCURRPAID202402270555381709013338091DEV001OO0000000400013559"
}

请求参数说明

Param Desc Require
externalOrderId 商户订单号 max=64（String） required
orderId 系统订单号（String） required

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": [
        {
            "orderId": "OCURRPAID202402270555381709013338091DEV001OO0000000400013559",
            "cashierId": "OCURRPAID202402270555381709013338041DEV001OO0000000200013558",
            "orderType": 1,
            "orderResourceType": 2,
            "userId": "1707285840326127617",
            "orderStatus": 1,
            "orderTime": 1709013338000,
            "channelOrderId": "1709013338101ojz6l0wh8rddbgakgx1",
            "externalOrderId": "333333333222233322",
            "orderAmount": "10000",
            "orderActualAmount": null,
            "orderFee": null,
            "orderPayTime": null,
            "orderCompleteTime": null,
            "currencyType": "VND",
            "payType": 102,
            "tradeNote": "adkasd",
            "notifyUrl": "https://platform.hambit.co/#/home/dashboard",
            "markStatus": 0,
            "errorMsg": null,
            "errorMsgEn": null,
            "accountType": "",
            "accountName": "",
            "accountNo": "",
            "orderTypeCode": "Pay",
            "orderResourceTypeCode": "Currency",
            "orderStatusCode": "Wait pay",
            "payTypeCode": "BANK"
        }
    ]
}

响应参数说明

Param Type Desc
orderId String 订单ID
cashierId String 收银台ID
orderType int64 订单类型
orderResourceType int64 订单所属业务类型
userId String 用户ID
orderStatus int64 订单状态 1-待支付
2- 支付成功
orderTime int64 订单发起时间
channelOrderId String 订单关联渠道订单ID
externalOrderId String 商户订单号
orderAmount String 订单金额
orderActualAmount String 订单实际金额
orderFee int64 订单手续费
orderPayTime int64 订单支付时间
currencyType String 货币类型
payType int64 支付类型 102:BANK
202:BANK
tradeNote String 备注
notifyUrl String 回调URL
markStatus int64 标记状态
errorMsg String 错误信息
errorMsgEn String 错误信息en
accountType String 账户类型
accountName String 账户名称
accountNo String 账户号
orderTypeCode String 订单类型code
orderResourceTypeCode String 订单所属业务类型code
orderStatusCode String orderStatusc描述
payTypaCode String 支付类型code参考payType

# 5.5 查询代付订单

请求方式

Post

请求URL

/api/v3/vn/query/transferOrder

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
      "externalOrderId":"6554516461231233222222222",
      "orderId": "OCURRDRAW202402270637261709015846138DEV001OO0000000200013584"
}

请求参数说明

Param Desc Require
externalOrderId 商户订单号 max=64（String） required
orderId 系统订单号 （String） required

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": [
        {
            "accountName": "",
            "accountNo": "222333331",
            "accountType": "",
            "cashierId": "",
            "channelOrderId": "1709015847829jirrao15beq31x24826",
            "currencyType": "VND",
            "errorMsg": "Success",
            "externalOrderId": "6554516461231233222222222",
            "notifyUrl": "https://platform.hambit.co/#/home/dashboard",
            "orderActualAmount": "13.4",
            "orderAmount": "10",
            "orderCompleteTime": 1709015949000,
            "orderEntryAmount": "10",
            "orderFee": "3.4",
            "orderId": "OCURRDRAW202402270637261709015846138DEV001OO0000000200013584",
            "orderPayTime": 1709015949000,
            "orderResourceType": 2,
            "orderStatus": 8,
            "orderTime": 1709015846000,
            "orderType": 2,
            "payType": 202,
            "tradeNote": "adkasd",
            "userId": "1707285840326127617",
            "payTypeCode": "BANK",
            "orderStatusCode": "Success",
            "orderTypeCode": "Transfer"
        }
    ]
}

响应参数说明

Param Type Desc
orderId String 订单ID
cashierId String 收银台ID
orderType int64 订单类型
orderResourceType int64 订单所属业务类型
userId String 用户ID
orderStatus int64 订单状态 1-已受理
2-银行处理中
4-失败(银行未受理)
8-成功
16-失败
orderTime int64 订单发起时间
channelOrderId String 订单关联渠道订单ID
externalOrderId String 商户订单号
orderAmount String 订单金额
orderActualAmount String 订单实际金额
orderFee int64 订单手续费
orderPayTime int64 订单支付时间
currencyType String 货币类型
payType int64 支付类型 102:BANK
202:BANK
tradeNote String 备注
notifyUrl String 回调URL
markStatus int64 标记状态
errorMsg String 错误信息
errorMsgEn String 错误信息en
accountType String 账户类型
accountName String 账户名称
accountNo String 账户号
orderTypeCode String 订单类型code
orderResourceTypeCode String 订单所属业务类型code
orderStatusCode String orderStatus描述
payTypeCode String 支付类型code参考payType

# 5.6 查询余额

请求方式

Get

请求URL

/api/v3/vn/query/balance

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": [
        {
            "accountBalance": "0",
            "accountFreezeAmount": "0",
            "accountStatusId": 4,
            "accountWaitSettledAmount": "0",
            "currencyType": "VND",
            "accountStatus": "InAndOut"
        }
    ]
}

响应参数说明

Param Type Desc
accountBalance String 账户可用余额
accountFreezeAmount String 账户冻结金额
accountStatusId int64 账户状态id
accountWaitSettledAmount String 账户待划转金额
currencyType String 法币类型
accountStatus String 账户状态

# 5.7 查询银行

请求方式

POST

请求URL

/api/v3/vn/query/bank

请求类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

请求头

Param Desc Sample
access_key 商户后台获取 pFqV75X3
timestamp Unix时间戳13位 毫秒 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign 计算出来的签名 kAXyh+eerqrefyaF8dyFB0M4FVo=

请求参数

{
    "bankName":"TPBank"
}

如需查询所有银行value则传空字符串，如下数据：

{"bankName": ""}

请求参数说明

Param Desc Require
bankName 银行名称（String） required

响应类型

Header: { 'Content-Type': 'application/json;charset=utf-8'}

响应数据

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": [
        {
            "bankName": "TPBank",
            "bankCode": "8001",
            "currencyType": "VND"
        }
    ]
}

响应参数说明

Param Type Desc
bankName String 银行名称
bankCode String 银行code
currencyType String 货币类型

# 5.8 银行列表（银行列表仅供参考，请按查询银行接口返回数据提单）

BankName 缩写
Ngân hàng TMCP Tiên Phong (Tien Phong Commercial Joint Stock Bank) TPBank
Ngân hàng TMCP Kỹ thương Việt Nam (Vietnam Technological and Commercial Joint- stock Bank) Techcombank
Ngân hàng TMCP Quốc tế Việt Nam (Vietnam International Commercial Joint Stock Bank) VIB
Ngân hàng TMCP Việt Nam Thịnh Vượng (Vietnam Prosperity Joint-Stock Commercial Bank) VPBank
Ngân hàng TMCP Ngoại Thương Việt Nam (Joint Stock Commercial Bank for Foreign Trade of Vietnam) Vietcombank
Ngân hàng TMCP Công thương Việt Nam (Vietnam Joint Stock Commercial Bank For Industry And Trade) VietinBank
Ngân hàng TMCP Quân đội (Military Commercial Joint Stock Bank) MBBank
Ngân hàng TMCP An Bình (An Binh Commercial Join Stock Bank) ABBANK
Ngân hàng TMCP Á Châu (Asia Commercial Bank) ACB
Ngân hàng TMCP Đầu tư và Phát triển Việt Nam (Bank for Investment and Development of Vietnam) BIDV
Ngân hàng TMCP Phương Đông (Orient Commercial Joint Stock Bank) OCB
Ngân hàng TMCP Hàng Hải (Vietnam Maritime Commercial Joint Stock Bank) MSB
Ngân hàng TMCP Sài Gòn - Hà Nội (Saigon-Hanoi Commercial Joint Stock Bank) SHB
Ngân hàng Nông nghiệp và Phát triển Nông thôn Việt Nam (Vietnam Bank for Agriculture and Rural Development) Agribank
Ngân hàng TMCP Sài Gòn Thương Tín (Saigon Thuong Tin Commercial Joint Stock Bank) Sacombank
Ngân hàng TMCP Phát triển Thành phố Hồ Chí Minh (Ho Chi Minh City Development Joint Stock Commercial Bank) HDBank
Ngân hàng TMCP Bản Việt (Vietcapital Bank) VietCapitalBank
Ngân hàng TMCP Sài Gòn (Sai Gon Joint Stock Commercial Bank) SCB
Ngân hàng TMCP Xuất Nhập khẩu Việt Nam (Vietnam Export Import Commercial Joint - Stock Bank) Eximbank
TMCP Việt Nam Thịnh Vượng - Ngân hàng số CAKE by VPBank (Cake by VPBank - Digital Bank) CAKE
TMCP Việt Nam Thịnh Vượng - Ngân hàng số Ubank by VPBank (Ubank by VPBank - Digital Bank) Ubank
Ngân hàng số Timo by Ban Viet Bank (Timo - Digital Bank) Timo
Viettel Money ViettelMoney
VNPT Money VNPTMoney
Ngân hàng TMCP Sài Gòn Công Thương (Saigon Bank for Industry and Trade) SaigonBank
Ngân hàng TMCP Bắc Á (Bac A Commercial Joint Stock Bank) BacABank
Ngân hàng TMCP Đại Chúng Việt Nam (VIETNAM PUBLIC JOINT STOCK COMMERCIAL BANK) PVcomBank
Ngân hàng Thương mại TNHH MTV Đại Dương (OceanBank) Oceanbank
Ngân hàng TMCP Quốc Dân (National Citizen Commercial Joint Stock Bank) NCB
Ngân hàng TNHH MTV Shinhan Việt Nam (Shinhan Bank) ShinhanBank
Ngân hàng TMCP Việt Á (VietNam Asia Commercial) VietABank
Ngân hàng TMCP Nam Á (Nam A Commercial Joint Stock Bank) NamABank
Ngân hàng TMCP Xăng dầu Petrolimex (Petrolimex Group Commercial Joint Stock Bank) PGBank
Ngân hàng TMCP Việt Nam Thương Tín (VIETNAM THUONG TIN COMMERCIAL JOINT STOCK BANK) VietBank
Ngân hàng TMCP Bảo Việt (BaoViet Bank) BaoVietBank
Ngân hàng TMCP Đông Nam Á (Southeast Asia Commercial Joint Stock Bank) SeABank
Ngân hàng Hợp tác xã Việt Nam (Co-operative Bank of Viet Nam) COOPBANK
Ngân hàng TMCP Bưu Điện Liên Việt (Lien Viet Post Joint Stock Commercial Bank) LienVietPostBank
Ngân hàng TMCP Kiên Long (Kien Long Commercial Joint Stock Bank) KienLongBank
Ngân hàng Đại chúng TNHH Kasikornbank (KASIKORNBANK) KBank
Ngân hàng Liên doanh Việt - Nga (Vietnam – Russia Joint Venture Bank ) VRB
DBS Bank Ltd - Chi nhánh Thành phố Hồ Chí Minh (The Development Bank of Singapore Limited) DBSBank
Ngân hàng TNHH MTV Woori Việt Nam (Woori Bank) Woori
Ngân hàng Kookmin - Chi nhánh Hà Nội (KB Kookmin Bank Hanoi Branch) KookminHN
Ngân hàng Kookmin - Chi nhánh Thành phố Hồ Chí Minh (KB Kookmin Bank Hồ Chí Minh Branch) KookminHCM
Ngân hàng Thương mại TNHH MTV Xây dựng Việt Nam (Vietnam Construction Bank) CBBank
Ngân hàng Nonghyup - Chi nhánh Hà Nội (NongHyup Bank Ha Noi) Nonghyup
Ngân hàng TNHH MTV CIMB Việt Nam (Commerce International Merchant Bankers) CIMB
Ngân hàng TMCP Đông Á (DongA Commercial Joint Stock Bank) DongABank
Ngân hàng Thương mại TNHH MTV Dầu Khí Toàn Cầu (Global Petro Commercial Joint Stock Bank) GPBank
Ngân hàng TNHH MTV Hong Leong Việt Nam (Hong Leong Bank) HongLeong
Ngân hàng United Overseas - Chi nhánh TP. Hồ Chí Minh (United Overseas Bank) UnitedOverseas
Ngân hàng TNHH MTV HSBC (Việt Nam) (The Hongkong and Shanghai Banking Corporation) HSBC
Ngân hàng Công nghiệp Hàn Quốc - Chi nhánh Hà Nội (Industrial Bank Of Korea) IBKHN
Ngân hàng TNHH MTV Public Việt Nam (Public Bank Berhad) PublicBank
Ngân hàng Công nghiệp Hàn Quốc - Chi nhánh TP. Hồ Chí Minh (Industrial Bank Of Korea) IBKHCM
Ngân hàng TNHH Indovina (Indovina Bank Ltd.) IndovinaBank
Ngân hàng TNHH MTV Standard Chartered Bank Việt Nam (Standard Chartered) StandardChartered
Ngân hàng Chính sách xã hội Việt Nam (Vietnam Bank for Social Policies) VBSP
Ngân hàng Phát triển Việt Nam (Vietnam Development Bank) VDB
Ngân Hàng ANZ Việt Nam (Australia and New Zealand Banking Group Limited ) ANZ

# 6. 回调信息

# 6.1 如何回调接口验签

# 验签说明

​ API 请求在通过 internet 传输的过程中极有可能被篡改，为了确保回调未被更改， 您可设置回调参数签名认证。设置方法为：登录收银台 ->开发者中心 -> 回调地址 -> 添加。

# 验签步骤

整体流程和签名大体一致，仅仅是拿来验签的数据取法不一样，签名是自己构造数据，验签是获取数据（header、json）

  1. 取出 header 中的 sign 值；

  2. 定义一个 Map 字典类型对象，将请求中的json参数以 key-value 的形式放入其中

  3. 取出 header 中的 access_key、timestamp、nonce 也放入上一步定义的 Map 中

  4. 将 Map 中的 key 按照 ASCII 码从小到大排序（字典序）并将 Map 转换输出为“key1=value1&key2=value2” 形式的字符串；

  5. 将上一步转换的字符串用 secret_key 进行 HMAC_SHA1 加密并进行 Base64 转码，得到 sign 签名值与第一步 header 中取出的 sign 进行字符串校验，相符则验签通过，反之则验签失败。此处的 secret_key 需与下单时的 access_key 相匹配。

# 6.2 支付回调

回调数据

{
	"currencyType": "VND",
	"errorMsg": "",
	"errorMsgEn": "",
	"externalOrderId": "93960348",
	"markStatus": 0,
	"orderActualAmount": 50.000000,
	"orderAmount": 50.000000,
	"orderFee": 5.000000,
	"orderId": "OCURRPAID202307130850471689238247122DOCKER020000000400000103",
	"orderPayTime": 1689238357000,
	"orderStatus": "Payment success",
	"orderStatusCode": 2,
	"orderTime": 1689238247000,
	"payParam": "https://business.h5.cashfastpay.com/payment/20230713085049310135132143?amount=50&currency=MXN",
	"payType": 102,
	"payTypeName": "BANK",
	"tradeNote": "wsx12312"
}

回调数据说明

Param Type Desc
currencyType String 法币类型
errorMsg String 错误信息
errorMsgEn String 错误信息en
externalOrderId String 商户订单ID
markStatus String 标记状态
orderActualAmount float64 订单实际支付金额
orderAmount float64 订单创建金额
orderFee float64 手续费
orderId String 订单ID
orderPayTime int64 订单支付时间
orderStatus String orderStatusCode描述
orderStatusCode int64 订单状态 code 1-待支付
2- 支付成功
orderTime int64 订单创建时间
payParam String 支付类型
payType int64 支付类型
payTypeName String 支付类型名
tradeNote String 备注

​ 任意时候商户都可登录商户后台进行手动触发回调（不建议订单非终态发起手动回调），回调信息中订单状态等相关信息为真实实际状态（手动 回调请一定注意订单状态，如果手动回调订单的状态不是终态，在订单变为终态的时候平台依然会发起通知，请注意业务层面的冗余处理）

# 6.3 代付回调

回调数据

{
	"currencyType": "VND",
	"accountCode": "40012",
	"accountName": "BBVA MEXICO",
	"orderId": "OCURRDRAW202307171006541689588414537BMS001OO0000000200000694",
	"accountType": "3",
	"orderFee": "3",
	"orderStatus": "In bank processing",
	"externalOrderId": "79159948",
	"payTypeName": "BANK",
	"orderAmount": "40",
	"orderTime": 1689588415000,
	"payType": 202,
	"userInfoName": "Abraham Meza Aragon",
	"accountNo": "4152314092856502",
	"orderStatusCode": 2,
	"markStatus": 0
}

回调数据说明

Param Type Desc
currencyType String 货币类型
accountCode String 账户code
accountName String 账户名
orderId String 订单ID
accountType String 账户类型
orderFee String 订单手续费
orderStatus String orderStatusCode描述
externalOrderId int64 商户订单ID
payTypeName float64 支付类型名称
orderAmount float64 订单创建金额
orderTime int64 订单创建时间
orderPayTime int64 订单代付时间
payType int64 代付类型
userInfoName String 用户名称
accountNo String 账户号
orderStatusCode String 订单状态code 1-已受理
2-银行处理中
4-失败(银行未受理)
8-成功
16-失败
markStatus String 用户证件类型

任意时候商户都可登录商户后台进行手动触发回调（不建议订单非终态发起手动回调），回调信息中订单状态等相关信息为真实实际状态（手动 回调请一定注意订单状态，如果手动回调订单的状态不是终态，在订单变为终态的时候平台依然会发起通知，请注意业务层面的冗余处理）

# 6.4 回调响应

备注：所有的回调都包含签名信息，建议商户做回调验签，商户收到回调信息后，确定订单终态，请响应网

关如下信息（content-type: application/json）如果没有正常响应服务端会在30分钟内，间隔三分钟总计2

次通知

{"code":200,"success":true}

# 6.5 回调通知URL

登录商户后台可以配置统一回调地址（订单中手动指定回调UR地址，优先级高于统一配置的回调地址，例如：订单中指定了notifyUrl参数，不管是否有统一配置回调通知地址，都使用订单中的notifyUrl地址)

注意 http响应status_code优先级最高 只要收到响应status_code=200 响应数据则忽略

# 7. 公共响应代码

filed Type Default value and comment
code String 成功"200" 其他请参考失败code
success Bool 成功 true 失败false 和code保持意义上的同步
msg String 一级code返回的文字性描述
data Object 参考接口列表章节

# 8. 失败code

Code Desc
200 正常
300 参数异常
301 IP无权限
307 签名错误
500 系统错误

​