HitPay Product Guide and API docs.

In-person payments using payment request APIs are currently in public BETA

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:

Order a card reader from your hitpay dashboard : Guide
Register the reader: Guide

Displaying Payments on the Terminal

After switching your terminal to Standalone mode:

On the login screen, tap the button on the top left corner.
Select In-Person Payment API from the menu.
The terminal will now display the In-Person Payment API screen, allowing you to accept card and QR payments.

When in this mode:

The display will show the HitPay logo.
If a QR payment method is selected, the relevant QR code will be displayed for the customer to scan.
If a card payment method is selected, the display will show instructions to tap, insert, or swipe the card.

To quit the In-Person Payment API mode, please enter the PIN: 07139.

Payment Methods

The in-person payment API supports two main payment methods:

1. Card Payments

Accept physical card payments (credit/debit cards) using the card reader.

2. QR Payments

Accept QR code payments where customers scan the QR code displayed on the card reader screen.

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

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

Initiating Card Payments

To initiate a card payment, follow these steps:

Create Payment Request: Use the Payment Request API with payment_methods[] set to wifi_card_reader
Card Reader Activation: The card reader will automatically activate and display “Ready for Payment”
Customer Interaction: Ask your customer to insert, tap, or swipe their card on the reader
Payment Processing: The card reader will process the payment and display the result
Webhook Notification: You’ll receive a webhook with the payment status

$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();

Initiating QR Payments

To initiate a QR payment, follow these steps:

Create Payment Request: Use the Payment Request API with payment_methods[] set to any supported QR payment method and generate_qr set to true
QR Code Display: The card reader will automatically display a QR code on its screen
Customer Scanning: Ask your customer to scan the QR code using their mobile payment app (e.g., PayNow, GrabPay, etc.)
Payment Processing: The customer completes the payment through their mobile app
Webhook Notification: You’ll receive a webhook with the payment status

Supported QR Payment Methods

For QR payments, you need to use one of the supported QR payment methods. See the complete list of supported QR payment methods.

Required Parameters for QR Payments

Parameter	Description	Example
amount	The amount related to the payment	2500.00
payment_methods[]	One of the supported QR payment methods (e.g., paynow_online)	paynow_online
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
generate_qr	Set to `true` to generate QR code data	true
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[]' => 'paynow_online',
  'generate_qr' => 'true',
  '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();

Response

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 QR Payment Request

Copy
Ask AI
{
  "id": "9c262fb5-f3cd-4187-8c3e-fbe20730b9c6",
  "amount": "599.00",
  "currency": "sgd",
  "status": "pending",
  "payment_methods": [
    "paynow_online"
  ],
  "wifi_terminal_id": "tmr_123123123",
  "qr_code_data": {
    "qr_code": "00020101021226550009SG.PAYNOW010120210201605883W030100414202405281445315204000053037025406599.005802SG5905Nitin6009Singapore62290125DICNP17168782314914MWULPX63043561",
    "qr_code_expiry": null
  }
}

The card reader will automatically determine whether to show a QR code or activate card reading based on the available payment methods and customer preference.

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

payment_id=92965a2d-ece3-4ace-1245-494050c9a3c1&payment_request_id=92965a20-dae5-4d89-a452-5fdfa382dbe1&reference_number=ABC123&phone=&amount=599.00&currency=SGD&status=completed&hmac=330c34a6a8fb9ddb75833620dedb94bf4d4c2e51399d346cbc2b08c381a1399c

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:

payment_id=92965a2d-ece3-4ace-1245-494050c9a3c1&payment_request_id=92965a20-dae5-4d89-a452-5fdfa382dbe1&reference_number=ABC123&phone=&amount=599.00&currency=SGD&status=completed&hmac=330c34a6a8fb9ddb75833620dedb94bf4d4c2e51399d346cbc2b08c381a1399c

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:

amount1.00currencySGDpayment_id91d94138-b0b5-4ba0-b78c-babc59776876payment_request_id91d94124-0d1c-4fb4-921e-51953793106cphonereference_number201000000Dstatuscompleted

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

function generateSignatureArray($secret, array $args) {   
  $hmacSource = [];        
  foreach ($args as $key => $val) {
    $hmacSource[$key] = "{$key}{$val}";
  }
  ksort($hmacSource);
  $sig            = implode("", array_values($hmacSource));
  $calculatedHmac = hash_hmac('sha256', $sig, $secret); 

  return $calculatedHmac;
}

Congrats! You have now successfully completed the in-person payment integration.

FAQs

Can I test the APIs in a sandbox using a test card or simulator?

Does the in-person payments API support the Wisepad3 reader?

Can I connect a Bluetooth printer to my Wi-Fi terminal?

How does the card reader know whether to show QR code or accept card payment?

Which QR payment methods are supported?

Getting Started

Developers

Point of Sale

Online Store

Tools

Manage Payments

Integrations

Appendix

In Person Payments

Example Use cases

Overview

Setup Your Reader

Displaying Payments on the Terminal

Payment Methods

1. Card Payments

2. QR Payments

Create a Payment Request APIs

Query Parameters

Initiating Card Payments

Initiating QR Payments

Supported QR Payment Methods

Required Parameters for QR Payments

Response

Handling the webhook

Sample Webhook Payload

Validating a Webhook

FAQs

Getting Started

Developers

Point of Sale

Online Store

Tools

Manage Payments

Integrations

Appendix

​Example Use cases

​Overview

​Setup Your Reader

​Displaying Payments on the Terminal

​Payment Methods

​1. Card Payments

​2. QR Payments

​Create a Payment Request APIs

​Query Parameters

​Initiating Card Payments

​Initiating QR Payments

​Supported QR Payment Methods

​Required Parameters for QR Payments

​Response

​Handling the webhook

​Sample Webhook Payload

​Validating a Webhook

​FAQs

Example Use cases

Overview

Setup Your Reader

Displaying Payments on the Terminal

Payment Methods

1. Card Payments

2. QR Payments

Create a Payment Request APIs

Query Parameters

Initiating Card Payments

Initiating QR Payments

Supported QR Payment Methods

Required Parameters for QR Payments

Response

Handling the webhook

Sample Webhook Payload

Validating a Webhook

FAQs