In-Person Payments
BETA APIs
In-Person payments using payment request APIs are currently in public BETA
Payment Request APIs can also be used to accept in-person card payments using the wifi card reader. All the APIs are REST and with this API, you can easily enable in-person payments without additional client-side connections.
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
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.
HTTP Request
POST https://api.sandbox.hit-pay.com/v1/payment-requests
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 |
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.hit-pay.com/v1/payment-requests');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append(new http\QueryString(array(
'amount' => '599',
'currency' => 'SGD',
'payment_methods[]' => 'wifi_card_reader',
'webhook' => 'https://test.com/webhook',
'wifi_terminal_id' => 'tmr_123123123')));$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
'X-BUSINESS-API-KEY' => 'meowmeowmeow',
'Content-Type' => 'application/x-www-form-urlencoded',
'X-Requested-With' => 'XMLHttpRequest'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Handle Successful payment - Webhook
Once the payment has been completed a webhook will be sent to your server. A webhook is a POST request sent from HitPay's server to your server about the payment confirmation.
- 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. Refer to this section for more details
- Return HTTP status code 200 to Hitpay
- Mark your order as paid
Sample webhook payload data
payment_id=92965a2d-ece3-4ace-1245-494050c9a3c1&payment_request_id=92965a20-dae5-4d89-a452-5fdfa382dbe1&reference_number=ABC123&phone=&amount=599.00¤cy=SGD&status=completed&hmac=330c34a6a8fb9ddb75833620dedb94bf4d4c2e51399d346cbc2b08c381a1399c
Next Step
Congrats! You have now successfully completed the in-person payment integration.
Refund API: This is an optional API call, you may use this to refund a specific payment.
Payment Request: Reference to the API Details
Updated 2 months ago