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

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.

HTTP Request

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

Query Parameters

Mandatory fields are amount and currency

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

1. Create an endpoint (E.g. /payment-confirmation/webhook) in your server that accepts POST requests. This request is application/x-www-form-urlencoded.
2. Validate the webhook data using your salt value. Refer to this section for more details
3. Return HTTP status code 200 to Hitpay
4. 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&currency=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