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

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

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 (V2)

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_type": "1",
        "va_condition": "1",
        "va_bank": "BIDV",
        "va_status": "3",
        "va_amount": "100000",
        "va_timelimit": "1669262917",
        "qrDataURL": "https://img.vietqr.io/image/bidv-9631241000000789537-bFkXzq.jpg?amount=1120000&addInfo=Thanh toan tai khoan VA&accountName=Nguyen Van Dung",
        "qrCommonURL": "https://img.vietqr.io/image/bidv-9631241000000789537-b8tEhPA.jpg?amount=1120000&addInfo=Thanh toan tai khoan VA&accountName=Nguyen Van Dung"
    },
    "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.
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.
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.
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 without HPay logo.
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.
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.
REQUEST

{
    "merchant_id": "63575",
    "va_account": "9631241000000713987",
    "va_name": "NGUYEN VAN API TESSTADDA",
    "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.
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": ""
}

Callback IPN After Completed Payment

The notify_url must be provided to the HPay system. shell curl --header "Content-Type: application/json" \ --request GET \ htttp://<yourdomain>/va/callback?va_account=1001&fullAccountNumber=1001\ &va_bankName=BIDV&remark=bWluaCB0ZXN0IEdEIFZB\ &amount=1000&order_id=345&cashin=123456&transactionId=9600617&error_code=0\ &secure_code=22810dca6a677396585b7af8a528b839

This endpoint will request a callback to the merchant after completed payment processing. The merchant need to generate new API along with /va/callback to receive HPay's data request.

HTTP Request

GET htttp://<yourdomain>/va/callback?va_account=1000000000032&fullAccountNumber=9631241000000000032& va_bankName=BIDV&remark=bWluaCB0ZXN0IEdEIFZB&amount=30000&order_id=51239782&cashin=28275709& 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.
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

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:

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

Solution 2:

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.

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 VCB 970436 Active
Ngân hàng TMCP Quốc tế VIB 970441 Active
Ngân hàng TMCP Quân đội MB 970422 Active
Ngân hàng TMCP Công thương Việt Nam ICB 970415 Active
Ngân hàng TMCP phát triển TPHCM HDB 970437 Active
Ngân hàng TMCP Quốc dân NVB 970419 Active
Ngân hàng TMCP Hàng Hải Việt Nam MSB 970426 Active
Ngân hàng TMCP Việt Á 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 OJB 970414 Active
Ngân hàng TMCP An Bình 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 BVB 970438 Active
Ngân hàng TMCP Bưu điện Liên Việt LVB 970449 Active
Ngân hàng TMCP Tiên Phong TPB 970423 Active
Ngân hàng Nông Nghiệp và PTNT Việt Nam AGB 970405 Active
Ngân hàng TMCP Sài Gòn Hà Nội SHB 970443 Active
Ngân hàng TMCP Sài Gòn SCB 970429 Active
Ngân hàng TMCP Sài gòn Thương tín STB 970403 Active
Ngân hàng Sài Gòn Công Thương SGB 970400 Active
Ngân hàng TMCP Kiên Long KLB 970452 Active
Ngân hàng TMCP Đông Nam Á 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 Á NAB 970428 Active
Ngân hàng TMCP Đại Chúng Việt Nam PVCB 970412 Active
Ngân hàng TMCP Kỹ thương Việt Nam TCB 970407 Active
Ngân hàng TMCP Xuất nhập nhẩu Việt Nam 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 VPB 970432 Active
Ngân hàng TMCP Phương Đông OCB 970448 Active
Ngân hàng TNHH MTV Xăng dầu Petrolimex PGB 970430 Active
Ngân hàng TNHH MTV United Overseas Bank (Việt Nam) UOB 970458 Active
Ngân hàng TNHH Indovina 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 VCCB 970454 Active
Ngân hàng TMCP Việt Nam Thương Tín VB 970433 Active
Ngân hàng TMCP Bắc Á 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 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 VNSPB 999888 Active
Ngân hàng DBS CN Ho Chi Minh 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 Á 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  môi trường sandbox
              )),
            ],
          )),
    );
  }
}

SDK Supported Version

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&currency=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=&notify_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

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

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

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

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

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

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.

text

Step 2

Put all infomantion to register a merchant and active the merchant connection.

text

Step 3

Check merchant info of the integration in your merchant list.

text

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 Invaild API function/ not existing.
05 Wrong API version.
06 Invaild or not existing the merchant ID.
07 Wrong password.
08 Not existing merchant account.
09 Account has blocked.
10 Invaild invoice.
11 Invaild amount.
12 Invaild 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 Invaild tax_amount.
119 Invaild discount_amount.
120 Invaild fee_shipping.
121 Invaild return_url.
122 Invaild cancel_url.
123 Invaild items.
124 Invaild transaction_info.
125 Invaild quantity.
126 Invaild order_description.
127 Invaild affiliate_code.
128 Invaild time_limit.
129 Invaild buyer_fullname.
130 Invaild buyer_email.
131 Invaild buyer_mobile.
132 Invaild buyer_address.
133 Invaild total_item.
134 Invaild 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 Request is success.
01 Failed Invaild method. Method request is wrong.
03 Failed Miss parameters. Wrong input or incorrect secure_code.
06 Failed Not exited. The merchant not existing or invaild.
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

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