Integrate the payment request APIs in 3 simple steps
At a high level, integrating payments into your system involves a 3-step process:
The first step is to create a payment request in your system.
Once the payment request is ready, present the checkout page to the user.
After the payment is processed, handle webhooks to receive payment notifications.
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.
Since this is a server-to-server communication, if you have a mobile or Web client that communicates with your REST API, you must have a new endpoint E.g. /create-order, or reuse an existing endpoint. This endpoint will be responsible for making the payment request API call to hitpay.
Mandatory fields are amount
and currency
. Remember to include header Content-Type: application/x-www-form-urlencoded
Parameter | Description | Example |
---|---|---|
amount | Amount related to the payment | 2500.00 |
payment_methods[] | Choice of payment methods you want to offer the customer | paynow_online, card, wechat, alipay, grabpay, fave_duit, shopback, atome (Local Payment Methods) (Cross-border Payment Methods) |
currency | Currency related to the payment | SGD |
Buyer’s email | foo@example.com | |
purpose | Purpose of the Payment request | FIFA 16 |
name | Buyer’s name | John Doe |
reference_number | Arbitrary reference number that you can map to your internal reference number. This value cannot be edited by the customer | XXXX123 |
redirect_url | URL where we redirect the user after a payment. Query arguments reference (payment request id) and status are sent along | https://example.com/callback |
webhook | URL where our server does a POST request after a payment is completed | https://example.com/webhook |
allow_repeated_payments | If set to true, multiple payments can be paid on a payment request link. Default value is false | false |
expiry_date | Time after which the payment link will be expired (time in SGT). Applicable for repeated payments. Default is Null | 2021-02-02 01:01:01 |
After the payment request is completed, your server must return the payment_request_id
and URL values to the client. There are 2 ways to present the checkout UI: “Redirect to HitPay checkout” or “Present Drop-In UI.”
Navigate your user to the URL, and HitPay will take care of the rest of the flow. Once the payment is completed, the user will be navigated back to the “redirect_url” that was configured during the payment request step, along with the status.
Navigate your user to the URL, and HitPay will take care of the rest of the flow. Once the payment is completed, the user will be navigated back to the “redirect_url” that was configured during the payment request step, along with the status.
Unlike the redirect checkout page, the drop-in is embedded into your webpage, so your customer will never have to leave your site. To present this, you will need 2 values: “default_link” and “payment_request_id.” The default link value can be found in your Dashboard > Payment Links > Default link, and this value is fixed for all your payments.
Sample code for Drop-In UI can be found here.
Once the payment is completed, the user will be redirected to “redirect_url” defined in step 1.
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
Congrats! You have now successfully completed the payment integration.
Specify paynow_online
as the payment method, set generate_qr
to true
, and manage expiration settings if needed. 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 Native QR Code Payment Request
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.