NAV
shell java php

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

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.
cyber_token String International card tokenization.
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)

https://{return_url} or {notify_url}/success?
transaction_info=tichhopthanhtoan&
order_code=OM_1768202539&
price=200000&
payment_id=96138500&
payment_type=1&
error_text=&
secure_code=0cf45d9a9deb4ce20188fd074bb6ef61&
token_omipay=51279022-9cdeb8a3498ee9a6fb7869be513601d2&
bank_code=VISA&
card_number=400000xxxxxx1091&
tokenization=&
token_cyber=482CB2C6EBC19A41E063AF598d0ADCD8&
card_type=VISA

The outcome payment will have two (2) ways of notification: return_url and notify_url via GET method.

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 Domestic bank card (ATM bank card) token.
token_cyber String International card tokenization.
card_type String International card types (VISA / MASTERCARD / JCB)

Order Inquiry

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

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 :::

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 :::

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"&notify_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 (end of support)

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) - (end of support)

The document describe the API for the virtual account service to merchants

Create Account

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_method": "2",
        "va_type": "1",
        "va_condition": "1",
        "va_bank": "BIDV",
        "va_status": "3",
        "va_amount": "100000",
        "remark": "DH 001",
        "va_timelimit": "1669262917",
        "qrCommonURL": "https://openapi.htpgroup.com.vn/xxx1",
        "qrDataURL": "https://openapi.htpgroup.com.vn/xxx2",
        "qrImage": "https://openapi.htpgroup.com.vn/xxx3",
        "qrCode": "00020101021"
    },
    "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_method String The way of VA generation. 1: portal ; 2: api
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.
qrCode String Text QR Code.
checksum String The secure chain to verify the HPay data.

Update VA Account Name

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

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

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/v1/account/inquiry
Production POST https://openapi.htpgroup.com.vn/v1/account/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 - (end of support)

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",
        "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:

Note: For regular Merchants.

Parameter Method Description
Sandbox POST https://account-sandbox.hpay.com.vn/api/ibft/create
Production POST https://account.hpay.com.vn/api/ibft/create


Note: For special Merchants. HPay will notify you if you need to use openAPI.

Parameter Method Description
Sandbox(O) POST https://openapi-sandbox.htpgroup.com.vn/v1/fb/create
Production(O) POST https://openapi.htpgroup.com.vn/v1/fb/create

Solution 2 (Deprecated):

Parameter Method Description
Sandbox POST https://account-sandbox.hpay.com.vn/api/ibft
Production POST https://account.hpay.com.vn/api/ibft

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.
secureChain* String The secure chain. Generate key files in APPENDIX.

Response Parameters

Parameter Type Description
error_code String ERROR_CODE. Please contact HPay to reconcile with 99, 999, 050, 064 & 100.
status String Transaction status.
requestId String a id of merchant request.
bankAccountNumber String Received bank account.
omiCashoutId String HPay cashout id for a reconciliation.
omiTransactionId String HPay transaction id for a reconciliation.
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: 1 - Non‑refundable, 2 - Full refund
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 TNHH một thành viên Số Vikki DAB 970406 Active
Ngân hàng TMCP Phát triển TPHCM (HDBank) HDB 970437 Active

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.
4 Amount less than minimum allowed.
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 bank error. Please contact with HPay to perform a reconciliation.
999 Undefine internal error. Please contact with HPay to perform a reconciliation.
050 The transaction is processing. Please contact with HPay to perform a reconciliation.
064 The transaction is waiting. Please contact with HPay to perform a reconciliation.
100 The transaction is waiting. Please contact with HPay to perform a reconciliation.
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.
104 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.
shell java php