Comprehensive guide on integrating and using Embedded QR Code payments through HitPay API.
Embedded QR Code Payments allow seamless integration of QR payments directly into your platform without redirecting the users away.
At a high level, integrating payments into your system involves a 4-step process:
The first step is to create a payment request in your system
Once the payment request is ready, generate and present the QR code to the user.
The client scans the QR code and initiates the payment through their banking app.
After the payment is processed, handle webhooks to receive payment notifications and manage server-client communication.
Please note that not all payment methods support embedded QR Codes. Here is the list of methods that support QR Codes:
Payment Method | Code |
---|---|
PayNow | paynow_online |
ShopeePay | shopee_pay |
QRIS | doku_qris (Indonesia merchants), ifpay_qris (other merchants) |
WeChatPay | wechat_pay |
VietQR | vietqr_payme |
PromptPay | opn_prompt_pay |
TrueMoney | opn_true_money_qr |
GrabPay | grabpay_direct |
GrabPay PayLater | grabpay_paylater |
UPI | upi_qr |
Gcash | gcash_offline |
QRPH | qrph_netbank |
Touch ‘n Go | touch_n_go |
ShopBack | Coming Soon |
Before integration, it’s essential to understand how Hitpay APIs are authenticated. Hitpay utilizes API keys to grant access to the API. You can locate this key in your dashboard under “API keys.”
Hitpay requires the API key to be included in all API requests to the server. This key should be placed in a header that follows the format shown below:
X-BUSINESS-API-KEY: meowmeowmeow
This is the first step of the payment flow. Once you have all the details from the user and are ready to collect payments, use this API to create a payment request.
POST /v1/payment-requests
Creates a payment request and generates a QR code for the paynow_online
payment method.
Parameter | Type | Description |
---|---|---|
amount | string | Required. The amount to be paid. |
currency | string | Required. The currency of the payment (e.g., “sgd”). |
payment_methods[] | array | Required. Specify paynow_online as the payment method. |
generate_qr | boolean | Required. Set to true to generate the QR code. |
name | string | Optional. The name of the customer. |
string | Optional. The email of the customer. | |
phone | string | Optional. The phone number of the customer. |
purpose | string | Optional. The purpose of the payment. |
reference_number | string | Optional. A reference number for the payment. |
The response will include a qr_code_data object, which contains the data to be converted into a scannable QR code (qr_code).
Example Response for Embedded QR Code Payment Request
Once the payment request is created, generate the QR code using the response data and present it to the user.
Note for Sandbox Testing:
In sandbox, the qr_code
value returned may be a URL (e.g. https://securecheckout.sandbox.hit-pay.com/...
) instead of the raw PayNow QR string. This is intended to help you test the flow using a standard QR code reader or by visiting the link directly in a browser.
In production, the qr_code
will be a raw PayNow payload string that you should convert into a scannable QR code for use with banking apps.
The client scans the presented QR code with their banking app and initiates the payment process.
After the payment is processed, handle webhooks to receive payment notifications and manage server-client communication to update the payment status in your system.
Webhook is a POST request sent from HitPay’s server to your server about the payment confirmation. If you are using hitpay APIs to integrate into your e-commerce checkout you must mark your order as paid ONLY after the webhook is received and validated.
Webhook fields
Following fields are sent with the webhook request:
Parameter | Description | |
---|---|---|
payment_id | Payment ID | |
payment_request_id | Payment request ID | |
phone | Buyer’s phone number | |
amount | Amount related to the payment | |
currency | Currency related to the payment | |
status | Payment status (completed / failed) | |
reference_number | Arbitrary reference number mapped during payment request creation | |
hmac | Message Authentication code of this webhook request |
To validate a webhook payload from HitPay, follow these steps:
Exclude HMAC and Values: Remove the "hmac" key and its corresponding value from the extracted payload. For example:
Concatenation and Sorting: Concatenate the keys and values from the remaining key-value pairs without using "&" and "=", and arrange them in alphabetical order of the keys. For example:
Signature Generation: Use the HMAC-SHA256 algorithm along with the secret salt from your dashboard to generate a signature for the concatenated string. This signature will be unique to this payload.
Comparison and Validation: Compare the generated signature with the HMAC value present in the original payload, both values must match.
By following these steps, you can ensure the authenticity and integrity of the webhook payload received from HitPay. This process guarantees that the payload can be trusted and processed securely.
Sample Code
Webhook Signature Mismatch?
Possible reasons for wrong hmac value generated
Facing Invalid Business API Key Error
Possible reasons for this error:
Product Checklist
Ensure the following before moving to production
Why does my charges `webhook status` show as failed?
If you are using a payment plugin, after every successful payment, a webhook is sent to your store to acknowledge the payment confirmation. Your order is marked as paid through this webhook.
A webhook status showing as "failed" indicates that Hitpay failed to communicate with your server. This can happen for the following reasons:
To avoid this issue, ensure that you whitelist Hitpay's IP addresses:
3.1.13.32
, 52.77.254.34
54.179.156.147
For further details, please review your store's debug logs.