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

  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

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:

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

​
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

ParameterDescriptionExample
amountThe amount related to the payment2500.00
payment_methods[]Indicate that the request is for in-person payments using a wifi card readerwifi_card_reader
currencyIn-Person payments only support the home currency of your businessSGD
wifi_terminal_idThe reader ID can be found in your dashboard under “POS > Terminals”tmr_123123123
webhookURL, where the HitPay server will POST a request after payment is completedhttps://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();

​
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:

ParameterDescription
payment_idPayment ID
payment_request_idPayment request ID
phoneBuyer’s phone number
amountAmount related to the payment
currencyCurrency related to the payment
statusPayment status (completed / failed)
reference_numberArbitrary reference number mapped during payment request creation
hmacMessage Authentication code of this webhook request

​
Validating a Webhook

To validate a webhook payload from HitPay, follow these steps:

  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

  1. Exclude HMAC and Values: Remove the "hmac" key and its corresponding value from the extracted payload. For example:

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

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

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