# Vietnam payment API documentation
# 1. How to get API Key
The user logs in to the cash register -> Developer Center -> API Key -> Create API key. API Key has a separate configuration page and is bound to a fixed IP address ("0.0.0.0" means no IP interception filtering, any IP can be accessed), and different API Keys can be configured to meet different needs. Please do not disclose your Access Key and Secret Key to avoid asset loss. After the Secret Key is generated, it cannot be viewed again. Please save it in time. If you forget the Secret Key, please recycle the key pair in the backstage of the merchant and apply for a new key pair.
# 1.1 How to create API KEY
• Click Developer Center-API Key
• 1Choose whether to enable the debug mode (After debugging mode is enabled, you will have a standard prompt message and log view address for any errors)
• 2Select API Key permission
• 3Enter the whitelist address (0.0.0.0 means any IP address can be accessed)
Note: (When entering the whitelist domain name, you should pay attention to using "," to isolate multiple IPs.)
• 4 click create to generate API KEY
(After the API KEY is generated, you can copy, view, edit, and delete it in the My API KEY list below. Note that the Secret key only appears once when it is generated. Please save it properly. If you forget the Secret Key, Please recycle the key pair and apply for a new one.)
• Click Edit to close or open [Start Debugging] and modify the API Key permission and whitelist address. After the modification is complete, click Save
Note: Please wait patiently for 90 seconds for the API Key to take effect after creating or editing the API Key
# 2. How to use API Key
The current API Key is to add a parameter list in the header of the request
| Parameter name | Parameter description | Type | Required |
|---|---|---|---|
| access_key | Api Key access key (eg: TPhoa7ZQ) | String | Yes |
| timestamp | Millisecond-level timestamp (13 digits, such as: 1679669488472) | String | Yes |
| nonce | UUID (36 bits such as: 02f7a04f-53cc-47d4-bb3f-fae69dab49ac) The five parts are 8 characters, 4 characters, 4 characters, 4 characters, and 12 characters, with "-" in the middle interval | String | yes |
| sign | Parameter signature (eg: GXx2wYUD6UVr+zcmeCSFFPzcBLA=) | String | Yes |
# 3. Technology side parameter access process
# 4. How to sign the interface
# Signature Description
API requests are very likely to be tampered with during transmission over the internet. In order to ensure that the request has not been changed, all private interfaces except public interfaces (basic information, market data, etc.) must use your API Key is used for signature verification to verify whether parameters or parameter values have changed during transmission.
A legitimate request consists of the following parts:
- access_key: API access key;
- secret_key: The key used for signature encryption (only visible once when applying for an API Key in the background, please copy and save it in a safe place, and do not disclose it);
- timestamp: The time (UTC time) when you made the request. Such as: 1632811287325 (13 digits). Including this value in a query request helps prevent third parties from intercepting your request;
- nonce: random UUID string. Such as: 053a1b81-48a0-4bb1-96b2-60f6e509d911 (36 bits);
- sign: The value calculated by the signature, which is used to ensure that the signature is valid and has not been tampered with;
- All interfaces need to pass the above public parameters except secret_key in the http request header (header). The public parameters include (access_key, timestamp, nonce, sign) and other signature parameters are described in the API interface as allow.
# Signature steps
1. Define a Map dictionary type object, and put the parameters in the request into it in the form of key-value
2. Put access_key, timestamp, and nonce into the Map defined in the first step
3. Sort the attributes in the Map in ascending order (lexicographic order) according to the ASCII code and convert the Map to a string in the form of "key1=value1&key2=value2"
4. Encrypt the character string converted in the previous step with secret_key by HMAC_SHA1 and perform Base64 transcoding to obtain the value of the sign parameter. secret_key is the information in the apikey created on the cashier platform
5. Add the sign value and other required parameters to the request header, and send the request to the target interface
# Signature debugging tools
SignUtil: User login to cash register -> Developer Center -> API Documentation -> Signature Tool The Signature tool page is displayed (The access_key in the tool, please use a valid access_key and please set the IP whitelist that allows this access_key access to 0.0.0.0, we strongly recommend the used Access_key is discarded after debugging)
# 5. Interface list
# 5.1 Test interface connectivity
request method
Get
Request URL
/ping
response data
{"version":"1.0.1","timestamp":1688116827306}
Response parameter description
| Param | Type | Desc |
|---|---|---|
| version | String | If this parameter is returned, all interfaces in this document can be requested normally |
| timestamp | int64 | Unix timestamp |
# 5.2 Create a new collection order
request method
post
Request URL
/api/v3/vn/createCollectingOrder
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Acquisition from merchant background | pFqV75X3 |
| timestamp | Unix timestamp 13 digits milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | Calculated signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"amount":"50000.00",
"channelType":"BANK",
"externalOrderId":"333333333222233322",
"remark":"adkasd",
"notifyUrl":"https://platform.hambit.co/#/home/dashboard",
"returnUrl":"https://platform.hambit.co/#/home/dashboard"
}
Description of request parameters
| Param | Desc | Sample | Require |
|---|---|---|---|
| amount | The payment amount cannot exceed 2 decimal places and the amount cannot be less than 50000 Vietnamese dong (String) | 50000.00 | required |
| channelType | payment type (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 Six ways to choose according to oneself | required |
| externalOrderId | Merchant order number max=64 (String) | 333333333222233322 | required |
| notifyUrl | notification URL (String, URL) | https://platform.hambit.co/#/home/dashboard | optional |
| remark | remark max=255 (String) | adkasd | optional |
| returnUrl | return URL (String, URL) | https://platform.hambit.co/#/home/dashboard | optional |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"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"
}
}
}
Response parameter description
| Param | Type | Desc |
|---|---|---|
| cashierUrl | String | cashier link |
| currency | String | currency code |
| amount | String | Receipt amount |
| externalOrderId | String | Merchant order ID |
| orderId | String | System order ID |
| tradeNote | String | Note |
# 5.3 Create a new transfer order
request method
post
Request URL
/api/v3/vn/createTransferOrder
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Acquisition from merchant background | pFqV75X3 |
| timestamp | Unix timestamp 13 digits milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | Calculated signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"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"
}
Description of request parameters
| Param | Desc | Sample | Require |
|---|---|---|---|
| currencyAmount | The decimal of the payment amount cannot exceed 2 digits (String) | 10.00 | required |
| channelType | payment type (String) | BANK | required |
| externalOrderId | Merchant order number max=64 (String) | 6554516461231233222222222 | required |
| accountName | bank account name (String) | wsxtes | required |
| accountId | Recipient account (String) | 222333331 | required |
| bankName | bank name (String) This field needs to be abbreviated | Techcombank | required |
| remark | remark max=255 (String) | 123 | optional |
| notifyUrl | notification URL (String) | http://192.168.1.135:30001 | optional |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code": "200",
"success": true,
"msg": "成功",
"msgEn": "SUCCESS",
"data": {
"currencyType": "VND",
"externalOrderId": "6554516461231233222222222",
"orderId": "OCURRDRAW202402270637261709015846138DEV001OO0000000200013584",
"orderStatus": "Accepted"
}
}
Response parameter description
| Param | Type | Desc |
|---|---|---|
| currencyType | String | Fiat currency type |
| externalOrderId | String | merchant order id |
| orderId | String | System order ID |
| orderStatus | String | order status |
# 5.4 Query Collection Orders
request method
post
Request URL
/api/v3/vn/query/collectingOrder
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Acquisition from merchant background | pFqV75X3 |
| timestamp | Unix timestamp 13 digits milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | Calculated signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"externalOrderId":"333333333222233322",
"orderId": "OCURRPAID202402270555381709013338091DEV001OO0000000400013559"
}
Description of request parameters
| Param | Desc | Require |
|---|---|---|
| externalOrderId | Merchant order number max=64 (String) | required |
| orderId | system order number (String) | required |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"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"
}
]
}
Response parameter description
| Param | Type | Desc |
|---|---|---|
| orderId | String | order ID |
| cashierId | String | Cashier ID |
| orderType | int64 | order type |
| orderResourceType | int64 | The business type of the order |
| userId | String | user ID |
| orderStatus | int64 | order status 1- pending payment 2- payment successful |
| orderTime | int64 | order initiation time |
| channelOrderId | String | The order ID of the channel associated with the order |
| externalOrderId | String | Merchant order ID |
| orderAmount | String | order amount |
| orderActualAmount | String | actual order amount |
| orderFee | int64 | order fee |
| orderPayTime | int64 | order payment time |
| currencyType | String | currency type |
| payType | int64 | payment type 102:BANK 202:BANK |
| tradeNote | String | Note |
| notifyUrl | String | callback URL |
| markStatus | int64 | mark status |
| errorMsg | String | error message |
| errorMsgEn | String | error message en |
| accountType | String | account type |
| accountName | String | account name |
| accountNo | String | account number |
| orderTypeCode | String | order type code |
| orderResourceTypeCode | String | The business type code of the order |
| orderStatusCode | String | orderStatusc Description |
| payTypaCode | String | payment type code reference payType |
# 5.5 Query transfer orders
request method
post
Request URL
/api/v3/vn/query/transferOrder
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Acquisition from merchant background | pFqV75X3 |
| timestamp | Unix timestamp 13 digits milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | Calculated signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"externalOrderId":"6554516461231233222222222",
"orderId": "OCURRDRAW202402270637261709015846138DEV001OO0000000200013584"
}
Description of request parameters
| Param | Desc | Require |
|---|---|---|
| externalOrderId | Merchant order number max=64 (String) | required |
| orderId | system order number (String) | required |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"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"
}
]
}
Response parameter description
| Param | Type | Desc |
|---|---|---|
| orderId | String | order ID |
| cashierId | String | Cashier ID |
| orderType | int64 | order type |
| orderResourceType | int64 | The business type of the order |
| userId | String | user ID |
| orderStatus | int64 | order status 1-accepted 2-bank processing 4-Failed(bank not accepted) 8-success 16-Failed |
| orderTime | int64 | order initiation time |
| channelOrderId | String | The order ID of the channel associated with the order |
| externalOrderId | String | Merchant order ID |
| orderAmount | String | order amount |
| orderActualAmount | String | actual order amount |
| orderFee | int64 | order fee |
| orderPayTime | int64 | order payment time |
| currencyType | String | currency type |
| payType | int64 | payment type 102:BANK 202:BANK |
| tradeNote | String | Note |
| notifyUrl | String | callback URL |
| markStatus | int64 | mark status |
| errorMsg | String | error message |
| errorMsgEn | String | error message en |
| accountType | String | account type |
| accountName | String | account name |
| accountNo | String | account number |
| orderTypeCode | String | order type code |
| orderResourceTypeCode | String | The business type code of the order |
| orderStatusCode | String | orderStatus description |
| payTypeCode | String | payment type code reference payType |
# 5.6 Query balance
request method
Get
Request URL
/api/v3/vn/query/balance
request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Merchant background acquisition | pFqV75X3 |
| timestamp | Unix timestamp 13 digit milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | computed signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code": "200",
"success": true,
"msg": "成功",
"msgEn": "SUCCESS",
"data": [
{
"accountBalance": "0",
"accountFreezeAmount": "0",
"accountStatusId": 4,
"accountWaitSettledAmount": "0",
"currencyType": "VND",
"accountStatus": "InAndOut"
}
]
}
Response parameter description
| Param | type | Desc |
|---|---|---|
| accountBalance | String | Account Available Balance |
| accountFreezeAmount | String | Account frozen amount |
| accountStatusId | int64 | account status id |
| accountWaitSettledAmount | String | Amount to be transferred from the account |
| currencyType | String | Fiat currency type |
| accountStatus | String | Account Status |
# 5.7 Query Bank
request method
POST
Request URL
/api/v3/vn/query/bank
Request type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
request header
| Param | Desc | Sample |
|---|---|---|
| access_key | Acquisition from merchant background | pFqV75X3 |
| timestamp | Unix timestamp 13 digits milliseconds | 1679724896223 |
| nonce | UUID V4 | 794c26b0-d33c-4394-b2bb-c485eca16d9e |
| sign | Calculated signature | kAXyh+eerqrefyaF8dyFB0M4FVo= |
request parameters
{
"bankName":"TPBank"
}
If you need to query all bank values, pass an empty string, as follows:
{"bankName": ""}
Description of request parameters
| Param | Desc | Require |
|---|---|---|
| bankName | bank name (String) | required |
response type
Header: { 'Content-Type': 'application/json;charset=utf-8'}
response data
{
"code": "200",
"success": true,
"msg": "成功",
"msgEn": "SUCCESS",
"data": [
{
"bankName": "TPBank",
"bankCode": "8001",
"currencyType": "VND"
}
]
}
Response parameter description
| Param | Type | Desc |
|---|---|---|
| bankName | String | bank name |
| bankCode | String | bank code |
| currencyType | String | currency type |
# 5.8 Banks List
| BankName | abbreviation |
|---|---|
| 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. Callback information
# 6.1 How to call back the interface for signature verification
# Signature Verification Instructions
API requests are likely to be tampered with during transmission over the internet. In order to ensure that the callback has not been changed, you can set the callback parameter signature authentication. The setting method is: log in to the cashier -> developer center -> callback address -> add.
# Signature Verification Steps
The overall process is roughly the same as the signature, but the data used for signature verification is different. The signature is to construct the data by itself, and the signature is to obtain the data (header, json)
Take out the sign value in the header;
Define a Map dictionary type object, put the json parameters in the request in the form of key-value
Take out the access_key, timestamp, and nonce in the header and put them into the Map defined in the previous step
Sort the keys in the Map according to the ASCII code from small to large (lexicographic order) and convert the Map into a string in the form of "key1=value1&key2=value2";
Use the secret_key to encrypt the character string converted in the previous step with HMAC_SHA1 and perform Base64 transcoding to obtain the signed signature value and the sign extracted from the header in the first step for string verification. If they match, the signature verification will pass, otherwise, the signature verification will fail. . The secret_key here needs to match the access_key when placing an order.
# 6.2 Payment callback
callback data
{
"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¤cy=MXN",
"payType": 102,
"payTypeName": "BANK",
"tradeNote": "wsx12312"
}
Callback data description
| Param | Type | Desc |
|---|---|---|
| currencyType | String | Fiat currency type |
| errorMsg | String | error message |
| errorMsgEn | String | error message en |
| externalOrderId | String | Merchant order ID |
| markStatus | String | mark status |
| orderActualAmount | float64 | The actual payment amount of the order |
| orderAmount | float64 | order creation amount |
| orderFee | float64 | handling fee |
| orderId | String | order ID |
| orderPayTime | int64 | order payment time |
| orderStatus | String | orderStatusCode description |
| orderStatusCode | int64 | order status code 1- pending payment 2- payment successful |
| orderTime | int64 | order creation time |
| payParam | String | payment type |
| payType | int64 | payment type |
| payTypeName | String | payment type name |
| tradeNote | String | Note |
Merchants can log in to the backstage of the merchant at any time to manually trigger callbacks (manual callbacks are not recommended for non-final orders), and the order status and other related information in the callback information is the real actual status (please pay attention to the order status for manual callbacks, If the status of the manual callback order is not final, the platform will still initiate a notification when the order becomes final, please pay attention to the redundant processing at the business level)
# 6.3 transfer callback
callback data
{
"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
}
Callback data description
| Param | Type | Desc |
|---|---|---|
| currencyType | String | currency type |
| accountCode | String | account code |
| accountName | String | account name |
| orderId | String | order ID |
| accountType | String | account type |
| orderFee | String | Order Fee |
| orderStatus | String | orderStatusCode description |
| externalOrderId | int64 | Merchant order ID |
| payTypeName | float64 | payment type name |
| orderAmount | float64 | order creation amount |
| orderPayTime | int64 | Order payment time |
| orderTime | int64 | order creation time |
| payType | int64 | Payment type |
| userInfoName | String | username |
| accountNo | String | account number |
| orderStatusCode | String | Order Status Code 1-accepted 2-bank processing 4-Failed(bank not accepted) 8-success 16-Failed |
| markStatus | String | User credential type |
Merchants can log in to the backend of the merchant at any time to manually trigger a callback (it is not recommended to initiate a manual callback if the order is not in the final state). The status of the callback order is not final, and the platform will still initiate a notification when the order becomes final, please pay attention to the redundant processing at the business level)
# 6.4 Callback response
Remarks: All callbacks include signature information. It is recommended that merchants do a callback signature verification. After receiving the callback information, the merchant will confirm the final status of the order. Please respond to the website
Regarding the following information (content-type: application/json), if there is no normal response from the server, it will be within 30 minutes, with a total of 2 every three minutes
Notice
{"code":200,"success":true}
# 6.5 Callback Notification URL
*** Log in to the backstage of the merchant to configure the unified callback address (manually specify the callback UR address in the order, which has a higher priority than the uniformly configured callback address. For example, if the notifyUrl parameter is specified in the order, it will be used regardless of whether there is a unified configuration of the callback notification address. notifyUrl address in the order)***
Note that the http response status_code has the highest priority, as long as the response status_code=200 is received, the response data will be ignored
# 7. Public response code
| filed | Type | Default value and comment |
|---|---|---|
| code | String | Success "200" For others, please refer to failure code |
| success | Bool | success true, failure false, and code to keep the meaning of synchronization |
| msg | String | The textual description returned by the first-level code |
| data | Object | Reference interface list chapter |
# 8. Failure code
| Code | Desc |
|---|---|
| 200 | Normal |
| 300 | Parameter exception |
| 301 | IP Unauthorized |
| 307 | Signature error |
| 500 | System Error |