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.

You must use the HPayKey with your personal API requests.

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`.
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.

After completed payment with success messenger then the website redirect to return_url and perform a GET request to merchant server via notify_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	Domestic bank card (ATM bank card) token.
token_cyber	String	International card tokenization.
card_type	String	International card types (VISA / MASTERCARD / JCB)

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"&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

Virtual Account (VA) - (end of support)

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

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

Method: POST
Content-Type: application/json

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

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`

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

Method: GET
Types of request params: Query Parameters

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

This error section is stored in a separate file in includes/_errors.md.

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.

Introduction

Authentication

Checkout Payment

Create Link (V1)

HTTP Request

Request Parameters

Return_url and Notify_url (IPN)

Order Inquiry

HTTP Request

Request Parameters

Response Parameters

Checkout Sample Codes

Table 1

Table 2

Advanced Checkout Payment

Installment - Create Link

HTTP Request

Extra Request Parameters

iFrame - Create Link

HTTP Request

Extra Request Parameters

ATM Tokenization - Create Link

HTTP Request

Extra Request Parameters

Revoke ATM tokenization

HTTP Request

Request Parameters

Revoke Callback IPN Request

Virtual Account (VA) - (end of support)

Create Account

HTTP Request

Request Parameters

Response Parameters

Update VA Account Name

HTTP Request

Request Parameters

Response Parameters

API Revoke VA

HTTP Request

Request Parameters

Response Parameters

VA Transaction Inquiry

HTTP Request

Request Parameters

Response Parameters

Callback IPN After Completed Payment

HTTP Request

Request Parameters

FirmBanking (iBFT) Service - (end of support)

iBFT Payment

HTTP Request

Request Parameters

Response Parameters

APPENDIX

Bank Account Inquiry (Fee)

HTTP Request

Request Parameters

Response Parameters

FB_Transaction Inquiry

HTTP Request

Request Parameters

Response Parameters

iBFT Sample Codes

Table 3

Error_Code

Checkout Service Code

Virtual Account Service Code

FirmBanking Service Code

API Supported Versions

New Changes in version 1.0.0

New Changes in version `1.0.0`