In Person Payments

​

Use Cases

• Self Server Kiosk
• Point of Sale
• Vending Machines
  These APIs are only available in countries that support the wifi card reader and Ingenico DX4000 terminal.

​

Overview

1. Your client device (e.g., POS, Kiosk) sends a request to your backend server to initiate the payment process.
2. Your backend server calls the Payment Request API with the payment method set as “wifi_card_reader”.
3. HitPay initiates the payment process on the card reader that is already connected to the wifi.
4. Your customer presents their card to the card reader and completes the payment process.
5. HitPay sends a webhook to your backend server with the payment status information.
6. Your backend server receives the webhook and updates the order status accordingly.

​

Setup Your Reader

1. Order a card reader: Guide
2. Register the reader (for WisePOS E): Guide

​

Displaying Payments on the Terminal

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

• 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.

​

Ingenico DX4000 PH Terminal

1. To accept QR payments only, follow instructions above. No log in is needed.
2. To accept both QR and cards payments, log in to your HitPay account, go to Settings > In-person Payment > key in PIN: 8888 (use the same PIN to exit mode)

​

Payment Methods

​

1. Card Payments

​

2. QR Payments

​

Create Payment Requests via APIs

POST https://api.sandbox.hit-pay.com/v1/payment-requests

​

Initiating Card Payments

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

​

Query Parameters

$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

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

​

Supported QR Payment Methods

​

Query Parameters

$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

​

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

​

Validating a Webhook

1. 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

2. Exclude HMAC and Values: Remove the "hmac" key and its corresponding value from the extracted payload. For example:
3. 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

4. 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.
5. Comparison and Validation: Compare the generated signature with the HMAC value present in the original payload, both values must match.

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;
}

​

FAQs