Introduction
Welcome to the HPay API! You can use our API to access HPay API endpoints. This API documentation page was created with HPay. Feel free to integrate with our payment gateway in your business base for API's documentation.
Version: 1.0.0
Authentication
To through an authorization, please consider to correct use secure_code
and secureChain
in your requests for each HPay service:
secure_code = MD5(<HPayKey>)
secureChain = sign(<HPayKey>) in SHA256withRSA 2048
Make sure to replace
<HPayKey>
with your API secure chain.
HPay uses the secure chain to allow access to the API. You can register a new HPay API key secret at Merchant Portal.
Checkout Payment
The document describe the API for the checkout payment service along with domestic ATM, IB, VA and Credit/Debit Cards services to merchants
Create Link (V1)
The endpoint is combining all input parameters to perfom a GET request into the HPay system.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://checkout-sandbox.hpay.com.vn/v1/checkout.php |
Production | GET | https://checkout.hpay.com.vn/v1/checkout.php |
Request Parameters
Parameter | Type | Description |
---|---|---|
merchant_site_code* | String | HPay provide to merchant. |
return_url* | String | The payment will redirect to return_url after payment success. |
receiver* | String | Merchant email. |
transaction_info | String | Transaction infomation. |
order_code* | String | Order code of merchant. |
price* | Integer | Price of order. |
currency* | String | Currency of an order. such as vnd or usd . |
order_description | String | Description of an order. |
sub_order | String | If not empty, the the merchant order showing instead of order_code in checkout pages. |
buyer_info | String | Buyer info, input string "name". |
lang | String | Set default language is vi or en . |
secure_code* | String | The secure chain. HPay provide secure_pass to merchant. |
cancel_url | String | Link to redirect when cancel the payment. |
notify_url | String | Link to callback IPN to merchant server. |
time_limit | String | Time to pay (included of VA service). The format is dd/mm/yyyy,hh:ii. |
installment* | Integer | If use installment set 1 else 0. |
inpage | Integer | If use iframe set 1 else 0. |
token | String | The tokenization value, required if token_type is 2 |
token_type | String | Pay to create ATM token set 1, Pay with existing ATM token set 2 else none . |
payment_method_id | Integer | Required if inpage is 1. Look payment_method_id in table 1. |
method_group | String | To specific grouped payment. Look method_group in table 2 |
Return_url and Notify_url (IPN)
The outcome payment will have two (2) ways of notification: return_url
and notify_url
via GET method.
- After completed payment with success messenger then the website redirect to
return_url
and perform a GET request to merchant server vianotify_url
link.
Note: + Data of the return_url and the notify_url are same
Parameter | Type | Description |
---|---|---|
transaction_info* | String | HPay provide to merchant. |
price* | Integer | Total amount. |
payment_id* | Integer | Payment Id. |
payment_type* | Integer | Payment type. 1 - Paynow and 2 - Paylater. |
error_text* | String | Error contents. |
secure_code* | String | Secure chain for verification. |
token_omipay* | String | Token payment of HPay. |
order_code* | String | The order code of the merchant product. |
bank_code* | String | The bank code such as BIDV, VPB and VCB. |
card_number* | String | The card account number. |
tokenization* | String | The token value after tokenization payment completed. |
Order Inquiry
- Method: POST
- Content-Type: application/x-www-form-urlencoded
curl --header "Content-Type: application/x-www-form-urlencoded" \
--request POST \
--data '{"merchant_id":"12345","order_code":"xyz", "checksum":"1424"}' \
https://checkout-sandbox.hpay.com.vn/api/transaction
The above command returns JSON structured like this:
{
"error_code": "00",
"data": {
"token": "12353",
"transaction_status": "00",
"receiver_email": "abc@gmail.com",
"order_code": "xyz",
"total_amount": "1000",
"bank_code": "123",
"order_description": "Thanhtoan",
"tax_amount": 0,
"discount_amount": 0,
"fee_shipping": 0,
"return_url": "https://abc.com/",
"cancel_url": "https://abc.com/",
"buyer_fullname": "Nguyen Van A",
"buyer_email": "abc@gmail.com",
"buyer_mobile": "0123456789",
"buyer_address": "HN",
"affiliate_code": "0",
"transaction_id": "1234"
},
"checksum": "123"
}
This endpoint retrieves a order_code in the payment transaction.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://checkout-sandbox.hpay.com.vn/api/transaction/GetTransactionDetail |
Production | POST | https://checkout.hpay.com.vn/api/transaction/GetTransactionDetail |
Request Parameters
Parameter | Type | Description |
---|---|---|
merchant_id* | String | HPay provide to merchant. |
order_code | String | Order code of the product. |
transaction_id | int | Id of transaction. |
checksum* | String | Secure chain to verification. |
::: Please note
- Pass in either fields order_code
or transaction_id
, or both order_code
and transaction_id
:::
Response Parameters
Parameter | Type | Description |
---|---|---|
token | String | Token of payment in HPay system. |
transaction_status | String | Transaction status. |
receiver_email | String | Merchant email. |
order_code | String | Order code of the merchant product. |
total_amount | String | Total amount. |
bank_code | String | Code of a bank. |
order_description | String | Order description. |
tax_amount | Integer | Amount of tax in an order. |
discount_amount | Integer | Discounted amount in an order. |
fee_shipping | Integer | Shipping fee in an order. |
return_url | String | Redirect url after completed transaction successful. |
cancel_url | String | Redirect url after failed/ cancel transaction. |
buyer_fullname | String | Name of buyer. |
buyer_email | String | Email of buyer. |
buyer_mobile | String | Mobile of buyer. |
buyer_address | String | Address of buyer. |
affiliate_code | String | Affiliate code for an order. |
transaction_id | String | Id of transaction. |
Checkout Sample Codes
Language | Git link |
---|---|
PHP | https://github.com/htpgroup/omipay_php_lib |
Python | https://github.com/htpgroup/omipay_python_lib |
Table 1
Id | Method | BankName | Description |
---|---|---|---|
3380 | ATM | IndovinaBank | supported |
3382 | ATM | BaoVietbank | supported |
3383 | ATM | UOBBank | supported |
3385 | ATM | WoorilBank | supported |
2181 | ATM | Lien doanh Viet - Nga | supported |
1282 | ATM | BIDV | supported |
2860 | ATM | Public Bank Viet Nam | supported |
2861 | ATM | Kiên Long Bank | supported |
644924 | ATM | VCCB | supported |
683774 | ATM | PVCB | supported |
1003 | ATM | Vietcombank | supported |
1006 | ATM | Techcombank | supported |
1009 | ATM | MB | supported |
1012 | ATM | VIB | supported |
1015 | ATM | Vietinbank | supported |
1018 | ATM | Eximbank | supported |
1021 | ATM | ACB | supported |
1024 | ATM | HDBank | supported |
1027 | ATM | MaritimeBank | supported |
1030 | ATM | Navibank | supported |
1033 | ATM | Viet A | supported |
1036 | ATM | VPBank | supported |
1039 | ATM | Sacombank | supported |
1042 | ATM | GPBank | supported |
1045 | ATM | Agribank | supported |
1048 | ATM | Oceanbank | supported |
1051 | ATM | PGBank | supported |
1054 | ATM | SHB | supported |
1057 | ATM | Seabank | supported |
1060 | ATM | Tiên Phong | supported |
1063 | ATM | Bac A | supported |
1067 | ATM | Phương Đông | supported |
1069 | ATM | Dai A | supported |
1072 | ATM | An Binh | supported |
1075 | ATM | SaiGonBank | supported |
1078 | ATM | Nam A | supported |
2620 | ATM | LienVietPostBank | supported |
2260 | ATM | SCB | supported |
633269 | ATM | CFC | supported |
637154 | ATM | VietBank | supported |
2401 | InternetBanking | ACB | unsupported |
2402 | InternetBanking | Eximbank | unsupported |
2403 | InternetBanking | Vietinbank | unsupported |
1281 | InternetBanking | VIB | supported |
2549 | InternetBanking | Agribank | unsupported |
2550 | InternetBanking | MaritimeBank | unsupported |
2551 | InternetBanking | Sacombank | unsupported |
2600 | InternetBanking | TPB | unsupported |
2601 | InternetBanking | VPB | unsupported |
3203 | InternetBanking | ABB | unsupported |
629384 | InternetBanking | CFC | unsupported |
641039 | InternetBanking | VietBank | unsupported |
668234 | InternetBanking | PGBank | unsupported |
672119 | InternetBanking | OCB | unsupported |
679889 | InternetBanking | PVCB | supported |
734279 | InternetBanking | VietABank | unsupported |
652694 | InternetBanking | SHNB | supported |
660464 | InternetBanking | IVB | unsupported |
691544 | InternetBanking | PBVN | unsupported |
710969 | InternetBanking | LienVietPostBank | unsupported |
718739 | InternetBanking | SHB | unsupported |
738164 | InternetBanking | NaviBank | unsupported |
742049 | InternetBanking | HDBANK | unsupported |
656579 | InternetBanking | WoorilBank | unsupported |
707084 | InternetBanking | SCB | unsupported |
648809 | InternetBanking | VCCB | supported |
714854 | InternetBanking | BaoVietBank | unsupported |
726509 | InternetBanking | OCEANBANK | unsupported |
730394 | InternetBanking | GPBANK | unsupported |
676004 | InternetBanking | SaiGonBank | unsupported |
687659 | InternetBanking | NamABank | unsupported |
699314 | InternetBanking | SEA | unsupported |
703199 | InternetBanking | KienLongBank | unsupported |
722624 | InternetBanking | BacABank | unsupported |
1081 | InternetBanking | Vietcombank | unsupported |
1084 | InternetBanking | Dong A | unsupported |
1087 | InternetBanking | Techcombank | unsupported |
1090 | InternetBanking | BIDV | supported |
664349 | InternetBanking | UOB | unsupported |
695429 | InternetBanking | VRB | unsupported |
745934 | InternetBanking | MBBANK | supported |
396284 | Virtual Account | unsupported | |
1095 | Visa | supported | |
1098 | MasterCard | supported | |
1101 | JCB | supported |
Table 2
No. | Method | Description | Vietnamese content |
---|---|---|---|
1 | WALLET | unsupported | Thanh toán bằng Ví |
2 | BANK_ONLINE | supported | Thanh toán cổng nội địa |
3 | VA | supported | Thanh toán bằng Virtual Account |
4 | CREDIT_CARD | supported | Thanh toán cổng quốc tế |
Advanced Checkout Payment
Installment - Create Link
The document describe the API for the installment
payment service via Credit Cards
to merchants
The endpoint is combining all input parameters of Checkout Payment to perfom a GET request into the HPay system.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://checkout-sandbox.hpay.com.vn/checkout.php |
Production | GET | https://checkout.hpay.com.vn/checkout.php |
Extra Request Parameters
Parameter | Type | Description |
---|---|---|
installment* | Integer | If use installment set 1 else 0. |
::: Please note
- installment
: Use to integrate with trả góp
function of the payment
:::
iFrame - Create Link
The document describe the API for the iframe
payment service along with domestic ATM, IB, VA and Credit/Debit Cards services to merchants.
The endpoint is combining all input parameters of Checkout Payment to perfom a GET request into the HPay system.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://checkout-sandbox.hpay.com.vn/checkout.php |
Production | GET | https://checkout.hpay.com.vn/checkout.php |
Extra Request Parameters
Parameter | Type | Description |
---|---|---|
inpage | Integer | If use iframe set 1 else 0. |
::: Please note
- inpage
: Use to render iframe
in the browser for the payment
:::
ATM Tokenization - Create Link
The document describe the API for the tokenization
payment service along with domestic ATM service to merchants.
The endpoint is combining all input parameters of Checkout Payment to perfom a GET request into the HPay system.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://checkout-sandbox.hpay.com.vn/checkout.php |
Production | GET | https://checkout.hpay.com.vn/checkout.php |
Extra Request Parameters
Parameter | Type | Description |
---|---|---|
token | String | The tokenization value, required if token_type is 2 |
token_type | String | Pay to create ATM token set 1, Pay with existing ATM token set 2 else none . |
Revoke ATM tokenization
The document describe the API for the tokenization
revoke service along with domestic ATM service to merchants.
HTTP Request
https://checkout.hpay.com.vn/revoke_token.php?merchant_site_code=123&receive_email="example@gmail.com"&bank_code="ABB"&bank_token="9704005990670018"&return_url="yourwebsite.com/callback"&secure_code="3ab87d52bee1bcde4150c5aa353644f9"¬ify_url="yourwebsite.com/callback"
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://checkout-sandbox.hpay.com.vn/revoke_token.php |
Production | GET | https://checkout.hpay.com.vn/revoke_token.php |
Request Parameters
Parameter | Type | Description |
---|---|---|
merchant_id* | String | HPay provide to merchant. |
receive_email* | String | Merchant email. |
bank_code* | String | The bank code in return_url/ callback IPN of checkout payment with ATM |
bank_token* | String | The bank token in return_url/ callback IPN of checkout payment with ATM |
return_url* | String | The return link after complete request |
secure_code* | String | Secure code to protect request |
notify_url | String | Callback IPN after revoke complete |
Revoke Callback IPN Request
https://yourwebsite.com/callback_revoke_token?merchant_id=123&receive ="example@gmail.com"&bank_code="ABB"&bank_token="9704005990670018’"&secure_code="3ab87d52bee1bcde4150c5aa353644f9"&error_text=$errText&status=00&revoke_token_status=true
Parameter | Type | Description |
---|---|---|
merchant_id | String | HPay provided to merchant. |
receiver | String | Merchant email. |
bank_token | String | The bank token in return_url/ callback IPN of checkout payment with ATM |
secure_code | String | Secure code to protect request |
error_text | String | The error msg. use urldecode() to decode msg |
status | String | If 00 is success and remain is failed |
revoke_token_status | String | true is removed and false is failed |
Account API
Account balance Inquiry
The document describe the API for the account service of merchants in the HPay payment system.
curl --header "Content-Type: application/json" \
--request POST \
--data '{"requestId":"12345","merchantId":"1234", "requestTime":"2022-09-22", "signature": <signBase64>}' \
https://account-sandbox.hpay.com.vn/api/user/GetBalance
The above command returns
SUCCESS
JSON structured like this:
{
"data": {
"balance": "101,747,939",
"signature":<signBase64> ,
"respone_time": 1664182633
},
"requestId": "7C370C60A3C04DDC9B5F24368D31F343",
"error_code": 0,
"client_ip": "10.0.9.1"
}
The above command returns
ERROR
JSON structured like this:
{
"requestId": "176EECA9AE72120EB50F9E03FCF4F189",
"error_code": 215303,
"client_ip": "123.24.142.154",
"message": "Website tích hợp thanh toán không tồn tại"
}
This endpoint retrieves a account balance inquiry.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://account-sandbox.hpay.com.vn/api/user/GetBalance |
Production | POST | https://account.hpay.com.vn/api/user/GetBalance |
Request Parameters
Parameter | Type | Description |
---|---|---|
requestId* | String | Request Id of merchant. |
merchantId* | String | HPay provide to merchant. |
requestTime* | String | Time to request. |
signature* | String | Secure chain with base64 to verification. |
Response Parameters
Parameter | Type | Description |
---|---|---|
error_code | Integer | Error code number. 0: success. |
requestId | String | Merchant request id. |
respone_time | String | Timestamp of response. |
client_ip | String | client IP. |
message | String | Error message if have error. |
balance | String | Account balance value. |
signature | Long | Secure chain with base64 to verification where successful. |
Virtual Account (VA)
The document describe the API for the virtual account service to merchants
Create Account
- Method: POST
- Content-Type: application/x-www-form-urlencoded
curl --header "Content-Type: application/x-www-form-urlencoded" \
--request POST \
--data '{"merchantId":"xyz","accountVaType":"xyz",
"accountVaName":"xyz","amount":"xyz", "timeLimit":"xyz",
"condition":"xyz","secure_code":"xyz"}' \
https://account-sandbox.hpay.com.vn/api/va/create
The request command returns JSON structured:
{
"error_code": "0",
"data": {
"merchant_id": "123456",
"merchant_email": "abc@gmail.com",
"va_account": "1000000000178",
"va_name": "NGUYEN VAN A",
"va_type": "1",
"va_condition": "1",
"va_bank": "BIDV",
"va_status": "3",
"va_amount": "100000",
"remark": "thu DH 001",
"va_timelimit": "1669262917",
"qrCommonURL": "https://img.vietqr.io/image/BIDV-1234569900000102382-qJs3YTm.jpg?amount=1000&addInfo=Thanh toan tai khoan VA&accountName=CK",
"qrDataURL": "https://img.vietqr.io/image/BIDV-12345649900000102382-BS6Pk3k.jpg?amount=1000&addInfo=Thanh toan tai khoan VA&accountName=CK",
"qrImage": "https://openapi-sandbox.htpgroup.com.vn/service/vietqr/v1/generate?accountNo=123456990000001&accountName=CK&bankCode=BIDV&amount=1000&addInfo=Thanh+toan+tai+khoan+VA"
},
"checksum": "22810dca6a677396585b7af8a528b839"
}
This endpoint create VA account via API method.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://account-sandbox.hpay.com.vn/api/va/create |
Production | POST | https://account.hpay.com.vn/api/va/create |
Request Parameters
Parameter | Type | Description |
---|---|---|
merchantId* | String | This is merchant id. |
accountVaType* | String | VA type, 1 - one-time, 2 - multiple times. |
accountVaName* | String | The name of customer. |
amount* | String | A value of transaction. |
remark | String | Content of payment |
timeLimit | Timestamp | Limited time for VA account (timestamps in seconds). Default the limeted time valid in 24h. |
condition* | String | Value is 1 or 2. If condition is 1 the VA have fixed amount and if condition is 2 the VA have flexible amount. |
secure_code* | String | A secure chain to verify. |
Response Parameters
Parameter | Type | Description |
---|---|---|
error_code | String | The error code service. Look error_code in Virtual Account Service Code. |
merchant_id | String | The merchant ID. |
merchant_email | String | The merchant email. |
va_account | String | The vA account. |
va_name | String | The name of VA account. |
va_type | String | The VA type. |
va_bank | String | The VA bank name. |
va_condition | String | The VA type, value is 0 or 1. |
va_status | String | This VA account status. 1: unpaid, 2: paid, 3,4: expired |
va_amount | String | The VA amount to pay. |
remark | String | Content of payment. |
va_timelimit | String | Limited time of VA account/ Order |
qrDataURL | String | The VA QR link of generated vietQR with HPay logo. |
qrCommonURL | String | The VA QR link of generated vietQR. |
qrImage | String | The VA QR link of generated HPAY. |
checksum | String | The secure chain to verify the HPay data. |
Update VA Account Name
- Method: POST
- Content-Type: application/json
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://account-sandbox.hpay.com.vn/api/va/updateVaName |
Production | POST | https://account.hpay.com.vn/api/va/updateVaName |
Request Parameters
Parameter | Type | Description |
---|---|---|
merchant_id* | String | This is merchant id. |
va_account* | String | The VA account. |
va_name* | String | The name of VA account. |
remark | String | Content of payment. |
secure_code* | String | A secure chain to verify. |
Response Parameters
Parameter | Type | Description |
---|---|---|
error_code | String | The error code service. Look error_code in Virtual Account Service Code. |
message | String | The message response. |
merchant_id | String | This is merchant id. |
va_account | String | The vA account. |
va_name | String | The name of VA account has changed. |
remark | String | Content of payment. |
REQUEST
{
"merchant_id": "63575",
"va_account": "9631241000000713987",
"va_name": "NGUYEN VAN API TESSTADDA",
"remark": ""
"secure_code": "849247cb8b41eb1d80f338c25b1f505b"
}
RESPONSE
{
"error_code": "00",
"message": "Update account virtual account name successful",
"data": {
"merchant_id": "63575",
"va_account": "9631241000000713987",
"va_name": "NGUYEN VAN API TESSTADDA"
}
}
API Revoke VA
- Method: POST
- Content-Type: application/x-www-form-urlencoded
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://account-sandbox.hpay.com.vn/api/va/revoke |
Production | POST | https://account.hpay.com.vn/api/va/revoke |
Request Parameters
Parameter | Type | Description |
---|---|---|
merchant_id* | String | This is merchant id. |
account_va* | String | The VA account. |
flag* | String | Value is 0 or 1. flag: 1-open, 0-close |
time_limit | Long | Timestamp to transfer. (optional) |
secure_code* | String | A secure chain to verify. |
Response Parameters
Parameter | Type | Description |
---|---|---|
error_code | String | The error code service. Look error_code in Virtual Account Service Code. |
merchant_id | String | This is merchant id. |
account_va | String | The VA account. |
va_status | String | Value is 1: unpaid, 2: paid, 3,4: expired |
checksum | String | A secure chain to verify. |
EX: Response
- Case1: success
{
"error_code": "00",
"data": {
"merchant_id": "65457",
"account_va": "OMI9001122",
"va_status": "3"
},
"checksum": "462f36a313f6999736633e7f08d07055"
}
- Case2: has error
{
"error_code": "041",
"data": [],
"checksum": ""
}
VA_ Transaction Inquiry
- Method: POST
- Content-Type: application/json
Note: The API queries transactions associated with a Virtual Account (VA) from date (T-1) to T.
The request:
{
"merchant_id": "66295",
"va_account": "9631249900000102836",
"secure_code": "e681f2b2f967deb88a619e941c5db3f7"
}
The response:
{
"error_code": "00",
"message": "success",
"data": [
{
"transaction_id": 96119097,
"full_account_number": "9631249900000102836",
"amount": 100000,
"time_paid": 1728702771,
"cashin": 28299429,
"remark": "bm8gY29udGVudA==",
"va_bank_name": "BIDV",
},
{
"transaction_id": 96119100,
"full_account_number": "9631249900000102836",
"amount": 100000,
"time_paid": 1728702771,
"cashin": 28299430,
"remark": "bm8gY29udGVudA==",
"va_bank_name": "BIDV",
}
],
"secure_code": "bca27cabbc5055a45cf30da3457ea021"
}
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://openapi-sandbox.htpgroup.com.vn/account/v1/va/inquiry |
Production | POST | https://openapi.htpgroup.com.vn/account/v1/va/inquiry |
Request Parameters
Parameter | Type | Description |
---|---|---|
merchant_id* | String | This is merchant id. |
va_account* | String | The VA account number. |
secure_code* | String | A secure chain to verify. |
Response Parameters
Parameter | Type | Description |
---|---|---|
error_code | String | The error code. |
message | String | The messsage. |
data | Array | The transaction list |
> transaction_id |
Number | The transaction id |
> full_account_number |
String | The VA account number |
> amount |
String | The amount |
> time_paid |
Unix time | A time of the completed transaction at HPay. https://www.epochconverter.com/ |
> cashin |
String | The cashin id |
> remark |
String | Content of transaction (base64 encode) |
> va_bank_name |
String | The bank of VA |
secure_code* | String | A secure chain to verify. |
Callback IPN After Completed Payment
The notify_url must be provided to the HPay system.
shell
curl --header "Content-Type: application/json" \
--request GET \ <yourdomain>/va/callback?va_account=1001&fullAccountNumber=1001\
&va_bankName=BIDV&remark=bWluaCB0ZXN0IEdEIFZB\
&amount=1000&order_id=345&cashin=123456&time_paid=1731742061&transactionId=9600617&error_code=0\
&secure_code=22810dca6a677396585b7af8a528b839
An endpoint is https
. The endpoint will perform a callback request to the merchants after update payment mechanism. Thus the merchants need to generate a API along with /va/callback
to receive HPay's data request.
HTTP Request
GET <yourdomain>/va/callback?va_account=1000000000032&fullAccountNumber=9631241000000000032& va_bankName=BIDV&remark=bWluaCB0ZXN0IEdEIFZB&amount=30000&order_id=51239782&cashin=28275709&&time_paid=1731742061&transactionId=9600617&error_code=0&secure_code=22810dca6a677396585b7af8a528b839
Request Parameters
Parameter | Type | Description |
---|---|---|
va_account | String | The VA account. |
fullAccountNumber | String | Full of VA account number. |
va_bankName | String | The VA bank name. |
remark | String | Transfer content with encoded base64. |
amount | String | The transaction value. |
order_id | String | The order Id. |
order_code | String | The order_code of payment via HPay checkout payment only. |
cashin | String | The cashin Id from HPay. |
time_paid | Unix time | A time of the completed transaction at HPay. https://www.epochconverter.com/ |
transactionId | String | The transaction Id from HPay. |
error_code | String | The error code. |
secure_code | String | MD5(cashin,order_id,passcode). The secure chain to verify. |
FirmBanking (iBFT) Service
The document describe the API for the firmbanking service to merchants
To integrate with the iBFT service, please generate key files in APPENDIX
iBFT Payment
The endpoint is combining all input parameters to perfom a GET request into the HPay system.
The input of created iBFT request:
{
"requestId": "00001",
"merchantId": "12345",
"merchantEmail": "abc@abc.com",
"bankName":"BIDV",
"bankAccountNumber": "1234567890912312",
"bankAccountName": "NGUYEN VAN A",
"amount": "1000000",
"note": "chuyen tien iBFT",
"timeTranfer": "07/06/2022",
"secureChain": "355f0f51956102a39d05a496546f9fb2xxxxx"
}
The output of created iBFT request:
{
"error_code": "000",
"status": "Giao dịch thành công",
"data": {
"requestId": "00001",
"bankAccountNumber": "1234567890912312",
"omiCashoutId": "231423",
"omiTransactionId": "96061677",
"secureChain": "865266941b737de8b8f88074db27a1f0xxxxxx"
}
}
HTTP Request
Solution 1:
- Method:
POST
- Content-Type:
application/x-www-form-urlencoded
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://account-sandbox.hpay.com.vn/api/ibft |
Production | POST | https://account.hpay.com.vn/api/ibft |
Solution 2:
- Method:
POST
- Content-Type:
application/json
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://account-sandbox.hpay.com.vn/api/ibft/create |
Production | POST | https://account.hpay.com.vn/api/ibft/create |
Request Parameters
Parameter | Type | Description |
---|---|---|
requestId* | String | Merchants generate for each payment ( RequestID is used to query transaction status, please save) |
merchantId* | String | HPay provide merchant. |
merchantEmail* | String | HPay provide merchant. |
bankName* | String | Received bank code. Check in Table 3. |
bankAccountNumber* | String | Received bank account. |
bankAccountName* | String | Received bank name. |
amount* | String | Money need to transfer 247. |
note | String (100) | Unsigned contents of the transfer 247. |
timeTranfer | String | Time to transfer. It's always the current date. (dd/MM/yyy). |
secureChain* | String | The secure chain. Generate key files in APPENDIX. |
Response Parameters
Parameter | Type | Description |
---|---|---|
error_code | String | ERROR_CODE. Please contact to HPay with 99, 050, 064 & 100. |
status | String | Transaction status. |
requestId | String | Request Id of merchant. |
bankAccountNumber | String | Received bank account. |
omiCashoutId | String | HPay reconciliation Id. |
omiTransactionId | String | HPay transaction Id. |
secureChain | String | The secure chain. Generate key files in APPENDIX |
APPENDIX
The merchant need to create key files, contain of : publicKey
and privateKey
via following commands, then provide to HPay cer
file.
# openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout merchantIbftKey.pem -out merchantIbftCert.pem
# openssl rsa -in merchantIbftKey.pem -pubout -out merchantIbftPublic.pem
# openssl x509 -outform der -in merchantIbftCert.pem -out merchantIbftCert.crt
# openssl x509 -inform PEM -in merchantIbftCert.pem -outform DER -out merchantIbftCert.cer
Bank Account Inquiry (Fee)
curl --request GET \
https://account-sandbox.hpay.com.vn/api/ibft/CheckUserBank?merchant_id=1234&bank_name=BIDV&bank_account_number=9704180000042134197&secure_code=123xxx567
The above command returns JSON structured like this:
{
"error_code": "000",
"data": {
"request_id": "20220912052918",
"merchant_id": "1234",
"bank_account_number": "9704180000042134197",
"bank_name": "BIDV",
"bank_account_name": "NGUYEN THI B"
},
"checksum": "c2b845845xxxxxxxxxx370ebe3f31d"
}
This endpoint retrieves a bank account in the iBFT inquiry.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://account-sandbox.hpay.com.vn/api/ibft/CheckUserBank |
Production | GET | https://account.hpay.com.vn/api/ibft/CheckUserBank |
Request Parameters
Parameter | Type | Description |
---|---|---|
merchant_id* | String | HPay provide to merchant. |
bank_name* | String | Receive account bank code. e.g: BIDV |
bank_account_number* | String | Receive account bank number. |
secure_code* | String | The secure chain. |
Response Parameters
Parameter | Type | Description |
---|---|---|
error_code | String | Error code number. |
request_id | String | HPay request id. |
merchant_id | String | Merchant id. |
bank_account_number | String | Receive bank account number. |
bank_name | String | Receive bank account code. e.g: BIDV. |
bank_account_name | String | Receive bank account name. |
checksum | String | Secure chain to verification. |
FB_Transaction Inquiry
curl --request GET \
https://account-sandbox.hpay.com.vn/api/ibft/inquiry?secureChain=8607bdba84e96f0c2ff9926e2a975ffb&merchantId=12345&requestId=1666062845347
OR with transactionId
curl --request GET \
https://account-sandbox.hpay.com.vn/api/ibft/inquiry?requestId=1666062845347&merchantId=12345&transactionId=123456&secureChain=8607bdba84e96f0c2ff9926e2a975ffb
The above command returns JSON structured like this:
For one transactionId matched one your requestId
{
"data": {
"time_tranfer": 1661834533,
"note": "chuyen tien iBFT",
"amount": 1000000,
"transaction_status": 4,
"cashout_status": 3,
"refund_status": 3,
"bankAccount_name": "TEST",
"merchant_id": "12345",
"request_id": "1666062845347",
"bankAccount_number": "12010004002695"
},
"secure_chain": "bac7f6b16079a0ffc3984c35535c78aa",
"error_code": "000"
}
For multiple transactionID matched your requestId
{
"data": [
{
"time_tranfer": "1689842444",
"transaction_id": "123456",
"note": "chuyen tien iBFT luc 1689842444",
"amount": "20000",
"transaction_status": "4",
"cashout_status": "3",
"refund_status": "",
"bankAccount_name": "TEST",
"merchant_id": "12345",
"request_id": "1666062845347",
"bankAccount_number": "12010004003096"
},
{
"time_tranfer": "1689843127",
"transaction_id": "654321",
"note": "chuyen tien iBFT luc 1689843127",
"amount": "20000",
"transaction_status": "4",
"cashout_status": "3",
"refund_status": "",
"bankAccount_name": "TEST",
"merchant_id": "12345",
"request_id": "1666062845347",
"bankAccount_number": "12010004003096"
}
],
"secure_chain": "867ead7b9e85526f36a50d0ef67fce8e",
"error_code": "000"
}
This endpoint retrieves a trasaction in the iBFT transaction.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://account-sandbox.hpay.com.vn/api/ibft/inquiry |
Production | GET | https://account.hpay.com.vn/api/ibft/inquiry |
Request Parameters
Parameter | Type | Description |
---|---|---|
requestId* | String | Request Id of merchant. |
merchantId* | String | HPay provide to merchant. |
transactionId | String | (Option) Value of omiTransactionId in response of iBFT payment API. |
secureChain* | String | Secure chain to verification. |
Response Parameters
Parameter | Type | Description |
---|---|---|
error_code | String | API Request Error Code. a success request is 000 . The error_code != 000 mean merchant's request reach a failed request status. |
request_id | String | Merchant request id. |
merchant_id | String | Merchant id. |
bankAccount_number | String | Receiver bank account number. |
bankAccount_name | String | Receiver bank account name. |
amount | Double | Amount of transfer. |
time_tranfer | Long | Timestamp to transfer. |
note | String | Notes of transfer. |
transactionId | String | Value of omiTransactionId in response of iBFT payment API. |
transaction_status* | Short | Transaction status. 1 & 2: Processing; 3: Failed; 4: Success. |
refund_status | Short | Refund status if Failed transaction. 3 - Success And failed status for remain cases |
cashout_status* | Short | Cashout transfer status. 1 & 2: Processing; 3: Success; 4: Failed. |
secure_chain | String | Secure chain to verification. |
iBFT Sample Codes
Language | Git link |
---|---|
C# | https://github.com/htpgroup/sample-ibft-c-sharp |
Java | https://github.com/htpgroup/sample-ibft-java |
Table 3
Vietnamese Bank | BankName | BIN Code | Status |
---|---|---|---|
Ngân hàng TMCP Ngoại thương Việt Nam (Vietcombank) | VCB | 970436 | Active |
Ngân hàng TMCP Quốc tế (VIB) | VIB | 970441 | Active |
Ngân hàng TMCP Quân đội (MB Bank) | MB | 970422 | Active |
Ngân hàng TMCP Công thương Việt Nam (VietinBank) | ICB | 970415 | Active |
Ngân hàng TMCP phát triển TPHCM (HDBank) | HDB | 970437 | Active |
Ngân hàng TMCP Quốc dân (National Bank) | NVB | 970419 | Active |
Ngân hàng TMCP Hàng Hải Việt Nam (MaritimeBank) | MSB | 970426 | Active |
Ngân hàng TMCP Việt Á (VietABank) | VAB | 970427 | Active |
Ngân hàng TNHH MTV Dầu khí toàn cầu | GPB | 970408 | Active |
Ngân hàng TMCP Đại Dương (Oceanbank) | OJB | 970414 | Active |
Ngân hàng TMCP An Bình (AnBinh Bank) | ABB | 970425 | Active |
Ngân hàng TMCP Đầu tư và phát triển Việt Nam | BIDV | 970418 | Active |
Ngân hàng TMCP Bảo Việt (BaoViet Bank) | BVB | 970438 | Active |
Ngân hàng TMCP Bưu điện Liên Việt (LienVietPostBank) | LVB | 970449 | Active |
Ngân hàng TMCP Tiên Phong (TienPhong Bank) | TPB | 970423 | Active |
Ngân hàng Nông Nghiệp và PTNT Việt Nam (Agribank) | AGB | 970405 | Active |
Ngân hàng TMCP Sài Gòn Hà Nội (Saigon Hanoi Bank) | SHB | 970443 | Active |
Ngân hàng TMCP Sài Gòn (SCB) | SCB | 970429 | Active |
Ngân hàng TMCP Sài Gòn Thương tín (SacomBank) | STB | 970403 | Active |
Ngân hàng Sài Gòn Công Thương (SaiGonBank) | SGB | 970400 | Active |
Ngân hàng TMCP Kiên Long (Kienlong Bank) | KLB | 970452 | Active |
Ngân hàng TMCP Đông Nam Á (SeABank) | SEA | 970440 | Active |
Ngân hàng Liên doanh Việt Nga | VRB | 970421 | Active |
Ngân hàng TNHH MTV PUBLIC Việt Nam | PBVN | 970439 | Active |
Ngân hàng TMCP NAM Á (Nam A Bank) | NAB | 970428 | Active |
Ngân hàng TMCP Đại Chúng Việt Nam (PVcomBank) | PVCB | 970412 | Active |
Ngân hàng TMCP Kỹ thương Việt Nam (TechcomBank) | TCB | 970407 | Active |
Ngân hàng TMCP Xuất nhập nhẩu Việt Nam (Eximbank) | EXB | 970431 | Active |
Ngân hàng TMCP Á châu | ACB | 970416 | Active |
Ngân hàng TMCP Việt Nam Thịnh vượng (VPBank) | VPB | 970432 | Active |
Ngân hàng TMCP Phương Đông (Oricombank) | OCB | 970448 | Active |
Ngân hàng TNHH MTV Xăng dầu Petrolimex (PG Bank) | PGB | 970430 | Active |
Ngân hàng TNHH MTV United Overseas Bank (Việt Nam) | UOB | 970458 | Active |
Ngân hàng TNHH Indovina (Indovina Bank) | IVB | 970434 | Active |
Ngân hàng TNHH Woori bank | WRB | 970457 | Active |
Ngân hàng TNHH MTV Shinhan (Việt Nam) | SHNB | 970424 | Active |
Ngân hàng TMCP Bản Việt (Viet Capital Bank) | VCCB | 970454 | Active |
Ngân hàng TMCP Việt Nam Thương Tín (Vietbank) | VB | 970433 | Active |
Ngân hàng TMCP Bắc Á (Bac A Bank) | BAB | 970409 | Active |
Ngân hàng Công nghiệp Hàn Quốc CN Hà Nội | IBKHN | 970455 | Active |
Ngân hàng Công nghiệp Hàn Quốc CN HCM | IBKHCM | 970456 | Active |
Ngân hàng CITIBANK Việt Nam (Citibank) | CTB | 533948 | Active |
Công ty Tài chính TNHH MTV Mirae Asset Việt Nam | MAFC | 977777 | Active |
Ngân hàng Đại chúng TNHH Kasikornbank CN HCM | KASIKORNBANK | 668888 | Active |
Ngân hàng KEB Hana CN Ha Noi | KEBHANAHN | 970467 | Active |
Ngân hàng KEB Hana CN Ho Chi Minh | KEBHANAHCM | 970466 | Active |
Ngân hàng Kookmin CN Ha Noi | KOOKMINHN | 970462 | Active |
Ngân hàng Kookmin CN Ho Chi Minh | KOOKMINHCM | 970463 | Active |
Ngân hàng TNHH MTV HSBC Viet Nam | HSBC | 458761 | Active |
Ngân hàng TNHH MTV Hong Leong Viet Nam | HONLEONGBANK | 970442 | Active |
Ngân hàng TNHH MTV Standard Chartered Bank Viet Nam | SC | 970410 | Active |
Ngân hàng TNHH MTV Xây dựng Viet Nam | CBB | 970444 | Active |
Ngân hàng Chính sách Xã hội (Vietnam Bank) | VNSPB | 999888 | Active |
Ngân hàng DBS CN Ho Chi Minh (DBS BANK) | DBS | 796500 | Active |
Ngân hàng Nonghyup CN Ha Noi | NONGHYUPBANK | 801011 | Active |
Ngân hàng TMCP Hợp tác xã Viet Nam | COOPBANK | 970446 | Active |
Ngân hàng TNHH MTV CIMB Viet Nam | CIMB | 422589 | Active |
Ngân hàng số CAKE by VPBank | CAKEVPB | 546034 | Active |
Ngân hàng số Liobank NH Phương đông | LIOBANK | 963369 | Active |
Ngân hàng số UMEE by Kienlongbank | UMEEKLB | 963399 | Active |
Ngân hàng số Ubank by VPBank | UBANKVPB | 546035 | Active |
Timo by Ban Viet Bank | TIMOB | 963388 | Active |
VNPT Money | VNPTMONEY | 971011 | Active |
Viettel Money | VIETELMONEY | 971005 | Active |
Ngân hàng TMCP Đông Á (DongA Bank) | DAB | 970406 | Active |
Ngân hàng TMCP Phát triển TPHCM (HDBank) | HDB | 970437 | Active |
Mobile SDK
Checkout Integration SDK
The document describe the SDK for the checkout service integration of merchants in the HPay payment system.
$ flutter pub add flutter_hpay_sdk
import 'package:flutter_hpay_sdk/flutter_hpay_sdk.dart';
The example
SDK
:
import 'package:flutter/material.dart';
import 'package:flutter_hpay_sdk/flutter_hpay_sdk.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatefulWidget {
const MyApp({super.key});
@override
State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
@override
void initState() {
super.initState();
}
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(
title: const Text('HPay Payment Gateway'),
),
body: Column(
children: const [
Expanded(
child: GatewaySdk(
orderCode: 'OM_123456', //do merchant quy dinh, phai la duy nhat
price: '50000',
paymentMethodId: 1095,
notifyUrl:
'http://10.0.9.18:8090/test_checkout/checkout_v1/success.php', //your notify url
merchantId: '64875', //your merchant id
merchantPass: '09217d13ecfa568', //your merchant password
receiverEmail: 'trungnv@htpgroup.com.vn', //email người nhận
env: 0, //1 môi trường production, 0 là môi trường sandbox
)),
],
)),
);
}
}
SDK Supported Version
- flutter_hpay_sdk: ^0.0.3
SDK Request
Parameter | Type | Description |
---|---|---|
env* | Integer | Environment integration. 0: sandbox , 1: production |
orderCode* | String | Merchant generate for each time. |
price* | String | Total amount of goods. |
paymentMethodId* | String | Payment method ID for the integration. Follow link: paymentMethodId |
notifyUrl* | String | Callback IPN during succeful. |
merchantId* | String | HPay provide the ID. |
merchantPass* | String | HPay provide the Passcode. |
receiverEmail* | String | HPay provide the merchant email. |
Mobile Webview
Checkout Integration Webview
This document will guide Mobile App developers of E-commerce Website to integrate HPay Payment Gateway to process Online Payment transactions for customers on Mobile App by using Webview object to open payment URL. Customers will manipulate payments through WebView.
Payment url form:
https://checkout-sandbox.hpay.com.vn/v1/checkout_hosted.php?merchant_site_code=65457&receiver=xuannt%40htpgroup.com.vn&price=20000¤cy=vnd&order_code=OM_1684204332&return_url=hhttps://hpay.com.vn/success.php&transaction_info=tichhopthanhtoan&order_description=Thanh toan don hang OM_1684204332&payment_method_id=1095&secure_code=74e1cb578195adc7b542874a52c5e3e8&lang=en&sub_order=&is_mobile=1&time_limit=¬ify_url=https://hpay.com.vn/callback.php
The example: React-native
import React from 'react';
import { WebView } from 'react-native-webview';
import md5 from 'md5';
import utf8 from 'utf8'
const MERCHANT_ID = "65457"
const MERCHANT_EMAIL = 'demo@hpay.com.vn';
const MERCHANT_PASS = 'e6f555ad5263b9ec0f753282b4297xxc';
const WebViewExample = () => {
// parameter
var random = Math.floor(Math.random() * 100) + 1;
var order_code = 'OM_' + random;
var transaction_info = 'tichhopthanhtoan';
var price = '50000';
var currency = 'vnd';
var order_description = 'Thanh toan hoa don ' + order_code;
var lang = 'vi';
var is_mobile = '1';
var return_url = 'http://demo.hpay.com.vn/success.php';
var notify_url = 'http://demo.hpay.com.vn/callback.php';
var payment_method_id = '1095';
// create secure_code ` secure_code = MD5( merchant_site_code + '|' + receiver + '|' + price + '|' + currency + '|' + order_code + '|' + secure_pass)`
var str_secure_code = MERCHANT_ID + '|' + MERCHANT_EMAIL + '|' + price + '|' + currency + '|' + order_code + '|' + MERCHANT_PASS;
var secure_code = md5(utf8.encode(str_secure_code));
const data = {
"merchant_site_code": MERCHANT_ID,
"return_url": return_url,
"receiver": MERCHANT_EMAIL,
"transaction_info": transaction_info,
"order_code": order_code,
"price": price,
"currency": currency,
"order_description": order_description,
"lang": lang,
"secure_code": secure_code,
"is_mobile": is_mobile,
"notify_url": notify_url,
"payment_method_id": payment_method_id,
"sub_order": '',
"time_limit": '',
};
const query_params = Object.entries(data).map(([k, v]) => `${k}=${v}`);
const base_url = 'https://checkout-sandbox.hpay.com.vn/v1/checkout_hosted.php?';
var url = base_url.concat(query_params.join('&'));
return (
<WebView
source={{ uri: url }}
/>
);
};
export default WebViewExample;
Base Url
- Sandbox: https://checkout-sandbox.hpay.com.vn/v1/checkout_hosted.php
- Production: https://checkout.hpay.com.vn/v1/checkout_hosted.php
Request parameter
Parameter | Type | Description |
---|---|---|
merchant_site_code* | String | HPay provide to merchant. |
return_url* | String | The payment will redirect to return_url after payment success. |
notify_url* | String | Link to callback IPN to merchant server. |
receiver* | String | Merchant email. |
transaction_info | String | Transaction infomation. |
order_code* | String | Order code of merchant. |
price* | Integer | Price of order. |
currency* | String | Currency of an order, such as vnd or usd. |
order_description | String | Description of an order. |
sub_order | String | If not empty, the the merchant order showing instead of order_code in checkout pages. |
lang | String | Set default language is vi or en. |
secure_code* | String | The secure chain. HPay provide secure_pass to merchant. |
is_mobile* | Integer | Required value is 1. |
time_limit | String | Time to pay (included of VA service). The format is dd/mm/yyyy,hh:ii. |
payment_method_id* | Integer | Payment method ID for the integration. Follow link: paymentMethodId |
Payment Hub
The document describe the API for Payment Hub service
Login
- Method: POST
curl --location 'https://opensnow-sandbox.htpgroup.com.vn/oauth/token' \
--form 'client_secret="xxxxxxxxxxxxxxxxxxxx"' \
--form 'client_id="xxxxxxxxxxxxxxxxxxxx"' \
--form 'grant_type="client_credentials"'
Response
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI4X0tvdUZ3cHh0OEpPbUMxNmluRG96eHNnMFkwMFJ3V3lRVEw3TUllamRzIn0.eyJleHAiOjE2ODk1ODkyMTcsImlhdCI6MTY4OTU4ODkxNywianRpIjoiYTdlZDM3OTktZTZjMi00ZWQ5LWJlYTEtNjE1OTczNjQ3NjdiIiwiaXNzIjoiaHR0cHM6Ly9hcGktc2FuZGJveC5odHBncm91cC5jb20udm4vcmVhbG1zL2dyYXZpdGVlIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImViN2JlMTgzLTE0ZjYtNGY0Yi1hNTJjLWU5MTQzNGJhMWIyNCIsInR5cCI6IkJlYXJlciIsImF6cCI6ImU1ZGQ5NWM1LTIzZTItNDZjYy05ZDMwLTA3ZGJmNjRlMDFjZCIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiIsImRlZmF1bHQtcm9sZXMtZ3Jhdml0ZWUiXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6ImVtYWlsIHByb2ZpbGUiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImNsaWVudEhvc3QiOiIxMC4wLjkuMSIsInByZWZlcnJlZF91c2VybmFtZSI6InNlcnZpY2UtYWNjb3VudC1lNWRkOTVjNS0yM2UyLTQ2Y2MtOWQzMC0wN2RiZjY0ZTAxY2QiLCJjbGllbnRBZGRyZXNzIjoiMTAuMC45LjEiLCJjbGllbnRfaWQiOiJlNWRkOTVjNS0yM2UyLTQ2Y2MtOWQzMC0wN2RiZjY0ZTAxY2QifQ.HSKmc_xa5dt_l5UlmAQw3tCfDz7nLSYofQRywRzvO1QT7Dm_lRZDlD6OD_cMbEYcoZ1D_fWr4jWH4M15BUTXphnfNz2DOKh5eTzDuDoXAyJDWb0-CfNK_Xh3TIvDHEoGWqniU6nkcQgkbBFxivGgo_D9Jlmd0KMcVb8USEx6NU0Pj7O8y1nZ6wXmLchnNOIqVfcp9r0m9EoMDB0_mcrAztc0ekB4VQ5GId0Yyugo7kUJWEdpOt_mLXHhXImrI-8bonL6ujFto051SHX5zcP4dC3qekldsAjgkxsccBuc_7tKjvEOYe1Rha52mIS6hyWQ142z_suF57YNYxsCmZhSHw",
"expires_in": 300,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "email profile"
}
This function create token for any request after that, like get bill, pay bill,...
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://opensnow-sandbox.htpgroup.com.vn/oauth/token |
Production | POST | https://opensnow.htpgroup.com.vn/hub/services/oauth2/token |
Request Parameters
Parameter | Type | Description |
---|---|---|
client_secret | String | Info secret key use for login (This info provide by HPay). |
client_id | String | id if merchant client (This info provide by HPay). |
grant_type | String | set default = client_credentials |
Response Parameters
Parameter | Type | Description |
---|---|---|
access_token | String | Token info. |
expires_in | String | Time expiry (Caculate with miliseconds). |
token_type | String | Type of Token. |
Get list of Product in Payment Hub
- Method: GET
curl --location 'https://opensnow-sandbox.htpgroup.com.vn/api/payment-hub/services/list_service'
Response
{
"service": [
{
"groupId": 11,
"code": "TOPUP",
"name": "Nạp tiền điện thoại",
"groupService": [
{
"serviceId": 34,
"name": "Topup Viettel",
"status": 1,
"code": "VIETTEL",
"description": "Active"
}
]
},
{
"groupId": 9,
"code": "INTERNET",
"name": "Internet",
"groupService": [
{
"serviceId": 49,
"name": "SST",
"status": 1,
"code": "INTERNET_SST",
"description": "Active"
},
{
"serviceId": 50,
"name": "SPT",
"status": 1,
"code": "INTERNET_SPT",
"description": "Active"
}
]
},
{
"groupId": 2,
"code": "ELECTRIC",
"name": "Điện",
"groupService": [
{
"serviceId": 12,
"name": "Hóa đơn điện EVN",
"status": 1,
"code": "ELECTRIC_EVN",
"description": "Active"
},
{
"serviceId": 48,
"name": "Điện hà nội",
"status": 1,
"code": "D1234567",
"description": "Active"
}
]
},
{
"groupId": 3,
"code": "WATER",
"name": "Nước",
"groupService": [
{
"serviceId": 13,
"name": "Nước Đồng Nai",
"status": 1,
"code": "WATER_48",
"description": "Active"
}
]
},
{
"groupId": 1,
"code": "POSTPAID",
"name": "Thanh toán hóa đơn trả sau",
"groupService": [
{
"serviceId": 9,
"name": "Hóa đơn trả sau Mobifone",
"status": 1,
"code": "POSTPAID_MOBI",
"description": "Active"
}
]
},
{
"groupId": 4,
"code": "FINANCE",
"name": "Tài chình",
"groupService": [
{
"serviceId": 17,
"name": "Hóa đơn FE Credit",
"status": 1,
"code": "FECREDIT",
"description": "Active"
}
]
},
{
"groupId": 5,
"code": "TELEVISION",
"name": "Truyền hình",
"groupService": [
{
"serviceId": 19,
"name": "MobiTV",
"status": 1,
"code": "MOBITV",
"description": "Active"
}
]
},
{
"groupId": 6,
"code": "INSURANCE",
"name": "Bảo hiểm",
"groupService": [
{
"serviceId": 21,
"name": "Thanh toán phí bảo hiểm Prudential",
"status": 1,
"code": "INSURAN_PRUDENTIAL",
"description": "Active"
}
]
},
{
"groupId": 7,
"code": "IDCARD",
"name": "Mua mã thẻ",
"groupService": [
{
"serviceId": 45,
"name": "Thẻ Viettel",
"status": 1,
"code": "ICARD_VIETTEL",
"description": "Active",
"serviceDetailsId": [
{
"serviceDetailsId": 4,
"name": "Viettel 50k",
"status": 1,
"amount": 50000,
"description": "Active"
}
]
},
{
"serviceId": 46,
"name": "Thẻ Mobifone",
"status": 1,
"code": "ICARD_MOBI",
"description": "Active"
},
{
"serviceId": 51,
"name": "Thẻ Viettel Data",
"status": 1,
"code": "IDCARD_VIETTEL_DATA",
"description": "Active",
"serviceDetailsId": [
{
"serviceDetailsId": 27,
"name": "ST120KDS - 2GB/Ngày",
"status": 1,
"amount": 120000,
"description": "Active"
}
]
}
]
},
{
"groupId": 8,
"code": "TOPUP_DATA",
"name": "Nạp data điện thoại",
"groupService": [
{
"serviceId": 39,
"name": "Topup Viettel Data",
"status": 1,
"code": "DATACODE_VIETTEL",
"description": "Active",
"serviceDetailsId": [
{
"serviceDetailsId": 11,
"name": "500MB3D - 500MB",
"status": 1,
"amount": 10000,
"daysUse": "3",
"description": "Active"
}
]
},
{
"serviceId": 40,
"name": "Topup MobiFone Data",
"status": 1,
"code": "DATACODE_MOBI",
"description": "Active",
"serviceDetailsId": [
{
"serviceDetailsId": 15,
"name": "DC3 - 150 MB",
"status": 1,
"amount": 3000,
"description": "Active"
}
]
},
{
"serviceId": 41,
"name": "Topup VinaPhone Data",
"status": 1,
"code": "DATACODE_VINA",
"description": "Active",
"serviceDetailsId": [
{
"serviceDetailsId": 20,
"name": "VNP20-1.2GB",
"status": 1,
"amount": 20000,
"description": "Active"
}
]
}
]
}
]
}
This API return all infomation about product of Payment Hub
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://opensnow-sandbox.htpgroup.com.vn/api/payment-hub/services/list_service |
Production | GET | https://opensnow.htpgroup.com.vn/hub/services/list_service |
HTTP Request Header
Key | Value |
---|---|
Authorization | "token_type" + " access_token" (token_type and access_token get from response of Login function). |
Response Parameters
Parameter | Type | Description |
---|---|---|
groupId | Integer | Id of group Product |
code | String | Code of group. |
name | String | Name of group. |
groupService | List | Info details of product in group |
groupService.serviceId | Integer | Id of service. |
groupService.name | String | Name of service. |
groupService.status | Integer | Status of service: 0 - Off, 1 - On. |
groupService.code | String | Code of service. |
groupService.description | String | Description about service. |
groupService.serviceDetailsId | List | service details info. |
groupService.serviceDetailsId.serviceDetailsId | Integer | Id of service Details. |
groupService.serviceDetailsId.name | String | Name of service detail. |
groupService.serviceDetailsId.status | Integer | Id of service detail: 0 - Off, 1 - On. |
groupService.serviceDetailsId.code | String | Code of service detaiil. |
groupService.serviceDetailsId.description | String | Description about service detail. |
groupService.serviceDetailsId.amount | Integer | Value of service detail. |
Get list of error code
- Method: GET
curl --location 'https://opensnow-sandbox.htpgroup.com.vn/api/payment-hub/services/list_error'
Response
{
"error": {
"success": [
{
"code": 0,
"description": "Thành công"
}
],
"pending": [
{
"code": 900,
"description": "Đang xử lý"
}
],
"fail": [
{
"code": 112,
"description": "Sai chữ ký"
},
{
"code": 113,
"description": "Chưa cài đặt dịch vụ"
},
{
"code": 200,
"description": "Hệ thống xảy ra lỗi, vui lòng thử lại sau"
}
],
"fail_provider": [
{
"code": 300,
"description": "Hệ thống nhà cung cấp xảy ra lỗi, vui lòng thử lại sau"
}
]
}
}
This API return info of error code in Payment Hub
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | GET | https://opensnow-sandbox.htpgroup.com.vn/api/payment-hub/services/list_error |
Production | GET | https://opensnow.htpgroup.com.vn/hub/services/list_error |
HTTP Request Header
Key | Value |
---|---|
Authorization | "token_type" + " access_token" (token_type and access_token get from response of Login function). |
Response Parameters
Parameter | Type | Description |
---|---|---|
error | Object | The error in Payment Hub system. |
error.success | List | The success code info. |
error.success.code | List | Code success. |
error.success.description | List | Description code. |
error.pending | List | The pending code info. |
error.pending.code | List | Code success. |
error.pending.description | List | Description code. |
error.fail | List | The fail code by Payment Hub info. |
error.fail.code | List | Code success. |
error.fail.description | List | Description code. |
error.fail_provider | String | The fail code from Provider provide to Payment Hub info. |
error.fail_provider.code | List | Code success. |
error.fail_provider.description | List | Description code. |
Get Bill
- Method: POST
- Content-Type: application/json
Request
{
"codeFunction":6001,
"billCode":"PH9023478",
"serviceId":1,
"serviceDetailsId":1,
"username":"SVC",
"requestId":"Test1",
"phone":"0983127592",
"signature":"UNV/rTm+qYjq9Xis0k46LrBqQP2xK69ly75zMPF+ctHz333Hsoe3eorjHJTohv97vPyfv5jsAnzqwpBsifRserWpzlCoipusd8TkCRP1NUSqh91jZeONZ97anly0CBAUOgPUom71GmR8eU0xJE+7fR5yhHNtd2jWdzBZEQWit6Q="
}
Response
{
"code": 0,
"desc": "Thành công",
"requestId": "Test1",
"data": {
"billCode": "PH9023478",
"serviceId": 1,
"serviceDetailsId": 1,
"transactionStatus": 0,
"transactionStatusDesc": "Thành công",
"totalAmount": 100000,
"fee": 1234,
"amountRemaining": 100000,
"billInfos": [
{
"period": "02/2023",
"amount": 100000
}
]
},
"referenceCode": "652742769",
"signature": "FQY69/YaHZLEei/iQ31zvbXVpKTEOjoUZJcuRP1k98K+2o8oUKg6aaQJhCAwMfBaeVwLxOAvawEb7IuhZM0OtP2/uqNObUXA+WoSycdqU2jfmoFs7WJzeYP2npZ3hKg54vm0HSHiAuiQN1pTRHiX25CABZaPGifpdchUbK0dqNk=",
"dataRequest": {
"codeFunction": 6001,
"billCode": "PH9023478",
"serviceId": 1,
"serviceDetailsId": 1,
"username": "SVC",
"partnerOrderId": "Test1",
"phone": "0983127592",
"signature": "UNV/rTm+qYjq9Xis0k46LrBqQP2xK69ly75zMPF+ctHz333Hsoe3eorjHJTohv97vPyfv5jsAnzqwpBsifRserWpzlCoipusd8TkCRP1NUSqh91jZeONZ97anly0CBAUOgPUom71GmR8eU0xJE+7fR5yhHNtd2jWdzBZEQWit6Q="
}
}
#Service let customer choose packages they want to use (like televison)
{
"code": 0,
"desc": "Thành công",
"referenceCode": "978b30c6-2d8a-44b7-8fda-b2be45da31d7",
"internalRequestId": "978b30c6-2d8a-44b7-8fda-b2be45da31d7",
"packages": [
{
"id": "1018262",
"amount": 2640000,
"monthsUse": 12,
"promotions": {
"value": 3,
"description": "đóng trước 12 tháng , tặng cước 3 tháng gói cước Net1plus đến Net5plus"
}
},
{
"id": "1017888",
"amount": 1320000,
"monthsUse": 6,
"promotions": {
"value": 1,
"description": "Đóng trước 6 tháng gói cước Net2plus đến Net5plus ,tặng cước 1 tháng"
}
}
],
"providerRequestId": "202307211421376nBjXTdBl",
"requestTelco": "{\"message\":{\"username\":\"hpay_dev\",\"password\":\"a1ec3b73f427c514ab64ce99c891b73f\",\"billing_code\":\"PD100000\",\"service_code\":\"TV_VTC\",\"partner_trans_id\":\"202307211421376nBjXTdBl\",\"contact_id\":\"0374234530\",\"authkey\":\"LdyvmZhFb0eF8ynfwOCycye5EpPnrJVoMSwLV/iep/IIOXZs6lA8bw8VOCOzpa8wQSmXDcMBsWzvEaykUeTeygO0M5zuRsMO+XFikKxEkpk8lo18iZeNhgz3enb44kXJm14lBWxWZEOS9GaK6DtJaaXwzPvf8QJrOiWx7ACnp3mX0p5wcrzcrSWYGp69N9I94Cy7EWYACA0glKeowE2HJ8y9oi/jkeP/VhZumhEk1tbaH6JAd1siNot+NdDmLNEgMYSkwYWieCBiwVvdY1xxGJpmDcgYomUp8mruBJl4scERbv84HxG6mIBf0BiVXjBj82G9fNJC34mN26aK/jZwLg==\"},\"pr_code\":\"1009\"}",
"responseTelco": "{\"signature\":\"LxSqAKRc6t9oCvhi/OJcdLeQtieG9VWzcbxAqleAEMacYod/DqJfDhbSZFdlSv600rbQNiGf7o8/EymyEj1hMZBiK3JE2HjY1PLNwyXMsb2SayWd6iJwDWL+hmJ/GbPPtiyA6ImtozwuMUqG8GgMP9GkRVFcpwwxym0c/MgsJFM=\",\"status\":\"00\",\"descriptions\":\"Tiếp nhận yêu cầu thành công\",\"data\":{\"reference_code\":\"1689988226234\",\"final_status\":\"00\",\"message\":\"Yeu cau giao dich - Thanh cong\",\"partner_trans_id\":\"202307211421376nBjXTdBl\",\"billing_code\":\"PD100000\",\"service_code\":\"TV_VTC\",\"partial_payment\":false,\"packages\":{\"package_info\":[{\"id_package\":\"1018262\",\"number_of_month\":\"12\",\"amount\":2640000,\"promotion\":{\"value\":3,\"description\":\"đóng trước 12 tháng , tặng cước 3 tháng gói cước Net1plus đến Net5plus\"}},{\"id_package\":\"1017888\",\"number_of_month\":\"6\",\"amount\":1320000,\"promotion\":{\"value\":1,\"description\":\"Đóng trước 6 tháng gói cước Net2plus đến Net5plus ,tặng cước 1 tháng\"}}]}}}"
}
This API use for check info of bill
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://opensnow-sandbox.htpgroup.com.vn/api/payment-hub/services/bill |
Production | POST | https://opensnow.htpgroup.com.vn/hub/services/bill |
HTTP Request Header
Key | Value |
---|---|
Authorization | "token_type" + " access_token" (token_type and access_token get from response of Login function). |
Request Parameters
Parameter | Type | Description |
---|---|---|
codeFunction | Integer | Code Function. (Code function are describe in Noted - Example title) |
billCode | String | Code (Name) of Bill. |
serviceId | Integer | Code of service. |
serviceDetailsId | Integer | Code of service detail (if that service had service detail). |
username | String | Partner Username (Provider by Payment Hub). |
requestId | String | Id for that request, must be unique each request send to Payment Hub. Create with this example: username + yyyyMMddHHmmss + random number. |
phone | String | Phone of owner bill (or who create this request). |
signature | String | Signature Payment Hub will use for verify. Use RSASHA256. |
Response Parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Error code return for request. |
desc | String | Description error code. |
requestId | String | Id for request. |
referenceCode | String | Reference Code. |
signature | String | Signature Payment Hub return. User RSASHA256. |
dataRequest | Object | Request. |
data | Object | Info about bill code. |
data.billCode | String | Bill code. |
data.serviceId | Integer | Id of service. |
data.transactionStatus | Integer | Status of transaction. 0 - Success, 1 - Fail, 2 - Pending |
data.transactionStatusDesc | String | Description transaction status. |
data.amount | Integer | Amount in bill |
data.fee | Integer | Fee need to pay for Payment Hub. |
data.billFee | Integer | Fee need to pay for Provider who own that Product. |
data.totalAmount | Integer | Total amount need to pay (After plus fee). |
data.amountRemaining | Number | Amount remaining (Use for installment finance service). |
data.billInfos | List | Info about payment period. |
data.packages | List | Info about packages user can choose (Use for what service allow users can choose packages they want). |
data.billName | String | Name onwer bill code. |
data.billAddress | String | Address onwer bill code. |
data.cards | List | Card infos (Return when user use buy card service). |
data.billInfos.period | String | Payment period. |
data.billInfos.periodAmount | Integer | Amount in period. |
data.packages.id | String | Id of package. |
data.packages.amount | Number | Package price. |
data.packages.description | String | Package description. |
data.packages.monthsUse | Number | Number months use with that package. |
data.packages.promotions | List | Package promotion (Return when that package have promotion). |
data.packages.promotions.value | Number | Value promotion. |
data.packages.promotions.description | String | Promotion description. |
data.cards.pin | String | Pincode, encrypt with TripleDes (Payment Hub provide |
data.cards.serial | String | Serial card |
data.cards.expiryDate | String | Card expiry |
Pay Bill
- Method: POST
- Content-Type: application/json
Request
{
"codeFunction": 6002,
"billCode": "PH9023478",
"serviceId": 1,
"serviceDetailsId": 1,
"username": "SVC",
"requestId": "Test1",
"quantity": 1,
"referenceCode": "-95299063",
"phone": "0987264526",
"amount": 100000,
"signature":"EEPJwAOWloZu4l/JZS1VEX45URWJUN/actng2aMBcM9JWE/DPE6m7OZ0X5S0PZZaoh/JAWrtIBcoxyCKmCWgXX1l40er9GyKwkJESzTejNfQmRzgSx9v6MOwsOIOX/bqi7Lhqt9OUpcBqb+2W+tVAy9S7z5TNB5Dwl13MetOYcc="
}
Response
{
"code": 0,
"desc": "Thành công",
"requestId": "Test1",
"data": {
"billCode": "PH9023478",
"serviceId": 1,
"serviceDetailsId": 1,
"transactionStatus": 0,
"transactionStatusDesc": "Thành công"
},
"referenceCode": "-95299063",
"signature": "RiDqm8jD6hkRBbMEWFzdYKbbh6qzaVzE0Q/NDlYOt3TCiZUtww60k44hNW9k60zBty+ijEd574bfs8mcThnnZwUm4CAPYu8zt6AV5jt0dGcFmhYrdvTuj6bt0tEB6MbraCVTrfXCSOgKQzAPM5tTVsavjtQzPkQa5XywRCLuSUc=",
"dataRequest": {
"codeFunction": 6002,
"billCode": "PH9023478",
"serviceId": 1,
"serviceDetailsId": 1,
"username": "SVC",
"partnerOrderId": "Test1",
"quantity": 1,
"referenceCode": "-95299063",
"phone": "0987264526",
"amount": 100000,
"signature": "EEPJwAOWloZu4l/JZS1VEX45URWJUN/actng2aMBcM9JWE/DPE6m7OZ0X5S0PZZaoh/JAWrtIBcoxyCKmCWgXX1l40er9GyKwkJESzTejNfQmRzgSx9v6MOwsOIOX/bqi7Lhqt9OUpcBqb+2W+tVAy9S7z5TNB5Dwl13MetOYcc="
}
}
#Buy Card Service
{
"code": 0,
"desc": "Thành công",
"telcoStatus": "0",
"telcoDesc": "success",
"internalRequestId": "44cdf01f-5d82-4d42-af96-34fdb251f9d6",
"cards": [
{
"pin": "88uq2HX5rssryIpp8kxOvx2sDC12gtof",
"serial": "S372RBRX9W8V76",
"expiryDate": "2025/06/17 00:00:00"
}
],
"providerRequestId": "20230721112424YvobRZcrd",
"requestTelco": "{\"operation\":1000,\"username\":\"IMEDIA_DEV15\",\"merchantPass\":\"5506778434444\",\"requestID\":\"20230721112424YvobRZcrd\",\"token\":\"ff8923f2784c58acbbd4a3a277dda3247b15daa5f8e5ed2d\",\"buyItems\":[{\"productId\":\"1\",\"quantity\":1}],\"keyBirthdayTime\":\"2023/05/29 17:20:24.837\",\"signature\":\"Ve/ngR22hnrtDCjtuLCEQrvvEwBTZqI/fQOVvEvRW+Glo0cfl+pAbpcdGxC50hpnkotaHKX2iCgpugY2zZyN3prsnzBALa4Ynfe38JhBQyUjc95k9GIWGnaMpMrFIHGhuJxymyATwRlEWBjtJ2cGL+9SQjIJ323k2DQhZF7X4fm27Ke7nUWyyfLwmYyC6Q1B7Fue1JmvRCYtT6Nwq7peKav5+nWjRwnmeHsmKw3ga0cmxjVtfMRzER4zJgZrDekkrKGzsgYdB38rQ7+lzGaph8KRtuRu9A6p1/Gl+VKASUdP1vwF1E0cjcV2BR68OVUD5yShslKU2bkyjazzfM8mnA==\"}",
"responseTelco": "{\"errorCode\":0,\"errorMessage\":\"success\",\"merchantBalance\":1661873400,\"token\":\"ff8923f2784c58acbbd4a3a277dda3247b15daa5f8e5ed2d\",\"accRealType\":null,\"products\":[{\"productId\":1,\"productValue\":10000,\"categoryName\":null,\"serviceProviderName\":null,\"commission\":0.03,\"softpins\":[{\"softpinId\":0,\"softpinSerial\":\"S372RBRX9W8V76\",\"softpinPinCode\":\"csIRy5NMP71rbWtPHA9isrLOlF6JUxPz\",\"expiryDate\":\"2025/06/17 00:00:00\"}]}],\"requestID\":\"20230721112424YvobRZcrd\",\"sysTransId\":448854,\"signature\":\"734ddbf6d97d5681501d4148747bb20c13669b1244c3a595a1c5aae59d49296f5bb97c439b716eed3a61686e8a653292fdbb23ee49ec52e66adcd27a37e26d9e1506cc28b6e0ff71e5a67a6dabef0c21efdcb43a55e78aafedda90ad0f6cbfad08880b3dd5d868796b88573eb9066ceb63a9b2aab77cc89f0241f9fb2c514d47cca07aa67d8a32932ac7e3145cb3e1e451a082d43f0ea1e7ec863aba318f8829c0894113fef207661a450e9a739e7a2d246b468c65674768185b8c7c79495fcb7545bc11941f4a0e70d9efcca83b3a14c596960c0ee423b6659e5921caa1ab7640696a450e7b2dcbf4637628a32dbd36ab881212d2cc713da278c795986d385d\"}"
}
This API receive request and sen to Provider for bill pay.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://opensnow-sandbox.htpgroup.com.vn/api/payment-hub/services/bill |
Production | POST | https://opensnow.htpgroup.com.vn/hub/services/bill |
HTTP Request Header
Key | Value |
---|---|
Authorization | "token_type" + " access_token" (token_type and access_token get from response of Login function). |
Request Parameters
Parameter | Type | Description |
---|---|---|
codeFunction | Integer | Code Function. (Code function are describe in Noted - Example title) |
billCode | String | Bill code. |
serviceId | Integer | Id of service |
serviceDetailsId | Integer | Id of serivce detail (if service had service detail). |
username | String | Username of merchant. |
requestId | String | Id for that request, must be unique each request send to Payment Hub. Create with this example: username + yyyyMMddHHmmss + random number. |
amount | Integer | Value amount pay. |
quantity | Integer | Quantity. |
phone | String | Phone of owner bill (or who create this request). |
referenceCode | String | Reference Code (Get from GET BILL, if service dont need get bill, partner generate random String). |
signature | String | Signature Payment Hub will use for verify. User RSASHA256. |
Response Parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Request error code |
desc | String | Description error code |
requestId | String | Request id return from Payment Hub |
data | Object | Info detail |
cards | List | Info detail card (For buy card service). |
referenceCode | String | Reference Code |
signature | String | Signature Payment Hub return. User RSASHA256. Create with data: codeFunction |
dataRequest | Object | Request send to Payment Hub |
data.billCode | String | Bill code. |
data.serviceId | Number | Id of service. |
data.transactionStatus | Number | Trạng thái giao dịch: 0 - Success, 1 - Fail, 2 - Pending |
data.transactionStatusDesc | String | Status of transaction Pay. |
data.serviceDetailsId | Integer | Id of service detail. |
data.amount | Integer | Payment value (contains origin amount and billFee). |
data.fee | Integer | Fee with Payment Hub |
data.totalAmount | Integer | Total amount payment. |
cards.pin | String | Pin detail with encrypt (Use TriplDes with secret key Payment Hub provide). |
cards.serial | String | Serial of card. |
cards.expiryDate | String | Expiry of card. |
Check Trans
Request
{
"codeFunction":6003,
"username":"SVC",
"transactionsId":"zzzz1",
"requestId":"123123213",
"signature":"C1C42fMG9650QEbPAM5HDTxhDmiZ6W7jAmFh8v8GzLBgGAT2UweNKJLFF5My7cHpttoz7U3fQ3cKc1aNQf7Qvi/LcR4VSiMFlXfO0AelFBxkvOeIL0MJKeR0ECf+MUJZefYjt8JA2Gx5EU8GjFhCC1nAkaSOB8VPlnKanBz9H/U="
}
Response
{
"code": 0,
"desc": "Thành công",
"requestId": "zzzz1",
"data": {
"transactionStatus": 0,
"transactionStatusDesc": "Thành công"
},
"signature": "GzImS2ufKSo0/UgbgnqicMT2oCcC2rjr2o8itkY4yNHwoDayCxo5u/aI92lYdaUhrGjwHjB0nckzNbgayKuwIMCKkX+h3QrU05TNrhM5b48qVXW8FSCxisXwGvhXJfWcz1gM43v7N+1vros9jm1g0ygJ5p++q8+TNZ6BUFgFznY="
}
This API provide status of requestId in Pay Bill wanna check final status at any times.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://opensnow-sandbox.htpgroup.com.vn/api/payment-hub/services/bill |
Production | POST | https://opensnow.htpgroup.com.vn/hub/services/bill |
HTTP Request Header
Key | Value |
---|---|
Authorization | "token_type" + " access_token" (token_type and access_token get from response of Login function). |
Request Parameters
Parameter | Type | Description |
---|---|---|
codeFunction | Integer | Code Function. (Code function are describe in Noted - Example title) |
requestId | String | Id for that request, must be unique each request send to Payment Hub. Create with this example: username + yyyyMMddHHmmss + random number. |
transactionsId | String | Is requestId in Pay Bill need to check status. |
username | String | Username of merchant. |
signature | String | Signature Payment Hub return. User RSASHA256. |
Response Parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Request error code |
desc | String | Description error code |
requestId | String | Request id return from Payment Hub |
data | Object | Info detail |
signature | String | Signature Payment Hub return. User RSASHA256. |
dataRequest | Object | Request send to Payment Hub |
data.transactionStatus | Number | Trạng thái giao dịch: 0 - Success, 1 - Fail, 2 - Pending |
data.transactionStatusDesc | String | Status of transaction Pay. |
Check Account Info
Request
{
"codeFunction":6004,
"username":"zzzzz",
"requestId":"asda2131"
}
Response
{
"code": 0,
"desc": "Thành công",
"requestId": "asda2131",
"balance": 1000000
}
This API provide info of balance for username want to check.
HTTP Request
Parameter | Method | Description |
---|---|---|
Sandbox | POST | https://opensnow-sandbox.htpgroup.com.vn/api/payment-hub/services/bill |
Production | POST | https://opensnow.htpgroup.com.vn/hub/services/bill |
HTTP Request Header
Key | Value |
---|---|
Authorization | "token_type" + " access_token" (token_type and access_token get from response of Login function). |
Request Parameters
Parameter | Type | Description |
---|---|---|
codeFunction | Integer | Code Function. (Code function are describe in Noted - Example title) |
requestId | String | Id for that request, must be unique each request send to Payment Hub. Create with this example: username + yyyyMMddHHmmss + random number. |
username | String | Username of merchant. |
Response Parameters
Parameter | Type | Description |
---|---|---|
code | Integer | Request error code. |
desc | String | Description error code. |
requestId | String | Request id return from Payment Hub. |
balance | Long | Balance at time call check. |
Noted - Example
Code Function
Code Function | Description |
---|---|
6001 | Get Bill |
6002 | Pay Bill |
6003 | Check Trans |
6004 | Check Account Info |
Example Code
Request and Respone with Payment Hub use signature for protect the integrity of data. Payment Hub and Partner need verify signature before handle data inside (except Login, get list of Product and get list of error code).
Sign - Java:
public String signSHA256(String message, String nameKey) throws IOException, GeneralSecurityException, URISyntaxException {
Signature sign = Signature.getInstance("SHA256withRSA");
// Get PrivateKey
sign.initSign(getPrivateKey(nameKey));
sign.update(message.getBytes(StandardCharsets.UTF_8));
return new String(Base64.encodeBase64(sign.sign()), StandardCharsets.UTF_8);
}
private RSAPrivateKey getPrivateKey(String nameKey) throws IOException, URISyntaxException, GeneralSecurityException {
String path = pathIMedia + File.separatorChar + nameKey;
File file = new File(path);
String privateKeyPEM = "";
BufferedReader br = new BufferedReader(new FileReader(file));
String line;
while ((line = br.readLine()) != null) {
privateKeyPEM += line + "\n";
}
br.close();
return getPrivateKeyFromString(privateKeyPEM);
}
private RSAPrivateKey getPrivateKey(String nameKey) throws IOException, URISyntaxException, GeneralSecurityException {
String path = pathIMedia + File.separatorChar + nameKey;
File file = new File(path);
String privateKeyPEM = "";
BufferedReader br = new BufferedReader(new FileReader(file));
String line;
while ((line = br.readLine()) != null) {
privateKeyPEM += line + "\n";
}
br.close();
return getPrivateKeyFromString(privateKeyPEM);
}
Verify - Java:
public boolean verifySHA256(String message, String signature, String pubCert)
throws SignatureException, NoSuchAlgorithmException, UnsupportedEncodingException, InvalidKeyException,
FileNotFoundException, CertificateException, URISyntaxException {
Signature sign = Signature.getInstance("SHA256withRSA");
String path = publicKey + File.separatorChar + pubCert;
sign.initVerify(getPublicKeyX509(path));
sign.update(message.getBytes(StandardCharsets.UTF_8));
return sign.verify(Base64.decodeBase64(signature.getBytes(StandardCharsets.UTF_8)));
}
private PublicKey getPublicKeyX509(String path) throws FileNotFoundException, CertificateException {
File file = new File(path);
FileInputStream fin = new FileInputStream(file);
CertificateFactory f = CertificateFactory.getInstance("X.509");
X509Certificate certificate = (X509Certificate) f.generateCertificate(fin);
PublicKey pubKey = certificate.getPublicKey();
return pubKey;
}
Encrypt with TripleDes
public String decryptTripleDesWithMD5(String key, String data) throws Exception {
Cipher cipher = Cipher.getInstance("TripleDES");
MessageDigest md5 = MessageDigest.getInstance("MD5");
md5.update(key.getBytes(), 0, key.length());
String keymd5 = (new BigInteger(1, md5.digest())).toString(16).substring(0, 24);
SecretKeySpec keyspec = new SecretKeySpec(keymd5.getBytes(), "TripleDES");
cipher.init(2, keyspec);
byte[] raw = Base64.getDecoder().decode(data);
byte[] stringBytes = cipher.doFinal(raw);
String result = new String(stringBytes);
return result;
}
Guild Gen key
Partner need gen Private-Public key, use private to create a signature and send to Payment Hub.
Public key partner send to HPay so Payment Hub can use that for verify signature Partner send.
Script gen key:
openssl req -newkey rsa:2048 -x509 -keyout private_key_encrypt.pem -days 365 -out public_key.pem
openssl rsa -in private_key_encrypt.pem -out private_key.pem
Demo Site
URL Link: https://account-sandbox.hpay.com.vn/
Username: demo@hpay.com.vn
Password: Demo@123
Mobile: 0909090909
Step 1
Click TÍCH HỢP THANH TOÁN
to begin the integration payment.
Step 2
Put all infomantion to register a merchant and active the merchant connection.
Step 3
Check merchant info of the integration in your merchant list.
Step 4
Collect all infomation for the integration, included of:
- merchant_id : <ID kết nối>
- secure_pass: <Mật khẩu kết nối>
- merchant_email: <Email>
Then, begin to integrate the payment with the HPay via documents at Checkout Payment
Error_Code
The HPay API uses the following error codes:
Checkout Service Code
Error Code | Meaning |
---|---|
00 | Success. |
01 | Invalid HTTP method |
99 | Undefine error. The internal error. |
02 | Your IP belong to blacklist. |
03 | Wrong parameters. |
04 | Invalid API function/ not existing. |
05 | Wrong API version. |
06 | Invalid or not existing the merchant ID. |
07 | Wrong password. |
08 | Not existing merchant account. |
09 | Account has blocked. |
10 | Invalid invoice. |
11 | Invalid amount. |
12 | Invalid currency. |
29 | Token not existed. |
80 | Not generate an order. |
81 | Unpaid order status. |
82 | Order status is paying. |
83 | Order status is failed. |
110 | wrong receiver email. |
111 | Locked receiver account. |
113 | Not configured fee for receiver account. |
114 | The payment is processing. |
115 | The payment canceled. |
118 | Invalid tax_amount. |
119 | Invalid discount_amount. |
120 | Invalid fee_shipping. |
121 | Invalid return_url. |
122 | Invalid cancel_url. |
123 | Invalid items. |
124 | Invalid transaction_info. |
125 | Invalid quantity. |
126 | Invalid order_description. |
127 | Invalid affiliate_code. |
128 | Invalid time_limit. |
129 | Invalid buyer_fullname. |
130 | Invalid buyer_email. |
131 | Invalid buyer_mobile. |
132 | Invalid buyer_address. |
133 | Invalid total_item. |
134 | Invalid payment_method, bank_code. |
135 | Failed connection to banks. |
140 | Order unsupport installment service. |
30010 | Merchant ID is empty. |
30011 | Order code or Transaction ID is required. |
30012 | Secure code is empty. |
30013 | Merchant does not exist or has not been activated. |
30014 | Secure code is invalid. |
30015 | The order does not exist or the order exceeds 7 days. |
Virtual Account Service Code
Error Code | Status | Meaning |
---|---|---|
00 | Success | HTTP request is success. |
01 | Failed | Invalid method. Method request is wrong. |
03 | Failed | Miss parameters. Wrong input or incorrect secure_code. |
06 | Failed | Not exited. The merchant not existing or invalid. |
07 | Failed | Invalid or not existing the va_account. |
08 | Failed | The va_account has expired or inactive. |
99 | Failed | Undefine. The internal error. |
040 | Error | Wrong parameter flag(0/1) |
041 | Error | VA account status does not allow on/off (1 --> allow off, 3 --> allow on) |
043 | Error | Not allowing unlocking in case of VA account 1 time and previously paid |
044 | Error | The account is inactive or locked |
045 | Error | Invalid accountVaName |
046 | Error | The remark content does not include special characters. |
047 | Error | The remark content includes a maximum of 50 letters. |
048 | Error | Invalid remark content. |
049 | Error | Invalid time_limit (maximum time limit 7 days). |
FirmBanking Service Code
Error Code | Meaning |
---|---|
000 | Success. |
01 | Invalid HTTP method. |
20010 | Merchant ID is empty. |
20011 | Bank code is empty. |
20012 | Account bank number code is empty. |
20013 | Secure code is empty. |
20014 | Merchant does not exist or has not been activated. |
20015 | Secure code is invali. |
20016 | The account is inactive or locked. |
20017 | Invalid note content. |
217301 | Transaction failed. Cashout request does not exist. |
008 | There is an issues of IPs, missing parameters or merchant's balance in HPay system. |
99 | Undefine error . The GW internal error, please contact to HPay. |
999 | Undefine error . The internal error, please contact to HPay. |
050 | The transaction is processing. |
064 | The transaction is waiting . Please check your balance and contact to HPay. |
100 | The transaction is waiting . Please check your balance and contact to HPay. |
001 | Verify signature of secureChain be failed |
010 | Not match secureChain |
014 | Not allow to payment |
035 | Not enough to payment |
036 | Not active payment account |
043 | Null data. |
058 | The refund transaction cannot perform due to not existing root tran_id. |
062 | Cannot inquiry the account |
063 | The transaction cannot perform. Please try again later. |
066 | Unavailable account. |
096 | The transaction cannot perform. Please try again later. |
115 | The receive card/ account invalid. please re-put again. |
116 | Cannot look up the bank name |
117 | Incorrect Bank Account Name. Please try again with correct with the bank account name. |
118 | The receive card/ account doesn't have account name |
119 | The receive card/ account invalid. Due to transer account is Saving/ Foreign exchange |
120 | The receive card/ account invalid. |
122 | The bank don't allow to transfer to account number. |
123 | The bank don't allow to transfer to card number. |
124 | The account/ card have invalid characters. |
125 | The receive card/ account invalid. Please try again later. |
126 | Customer don't have transaction inquiries |
127 | Incorrect receiver customer. |
128 | The card/ account invalid. |
129 | The transaction has peformed before. |
... | Updating from HPay's partner |
API Supported Versions
The HPay API have new change in the API of version 1.0.0
:
New Changes in version 1.0.0
Service Name | Service Type | Changes and/ or update |
---|---|---|
Virtual Account | Callback IPN | Update transactionId field. |