In Person Payments
Accept in-person card payments using the wifi card reader
Example Use cases
These APIs are designed to enable a variety of use cases where in-person payments are necessary. Here are a few examples of how this API can be used:
- Self Server Kiosk
- Point of Sale
- Vending Machines
These APIs are only available in countires that support the wifi card reader
Overview
- Your client device (e.g., POS, Kiosk) sends a request to your backend server to initiate the payment process.
- Your backend server calls the Payment Request API with the payment method set as “wifi_card_reader”.
- HitPay initiates the payment process on the card reader that is already connected to the wifi.
- Your customer presents their card to the card reader and completes the payment process.
- HitPay sends a webhook to your backend server with the payment status information.
- Your backend server receives the webhook and updates the order status accordingly.
Setup Your Reader
Before you can use the In-Person Payments using Payment Requests API, you’ll need to order a card reader and complete the setup process. Here’s what you need to do:
Create a Payment Request APIs
Once you have all the details from the client and are ready to collect payments, use this API to create a payment request.
Endpoint
Query Parameters
Mandatory fields are amount and currency
| Parameter | Description | Example |
|---|---|---|
| amount | The amount related to the payment | 2500.00 |
| payment_methods[] | Indicate that the request is for in-person payments using a wifi card reader | wifi_card_reader |
| currency | In-Person payments only support the home currency of your business | SGD |
| wifi_terminal_id | The reader ID can be found in your dashboard under “POS > Terminals” | tmr_123123123 |
| webhook | URL, where the HitPay server will POST a request after payment is completed | https://example.com/webhook |
Handling the webhook
- Create an endpoint (E.g. /payment-confirmation/webhook) in your server that accepts POST requests. This request is application/x-www-form-urlencoded.
- Validate the webhook data using your salt value
- Return HTTP status code 200 to Hitpay
- Mark your order as paid
- Sample webhook payload data
Sample Webhook Payload
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 |
Validating a Webhook
To validate a webhook payload from HitPay, follow these steps:
- Payload Extraction: Extract the key-value pairs from the webhook payload. For example:
-
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 in-person payment integration.
FAQs
Was this page helpful?