Overview

​

Overview

• Self Server Kiosk
• Point of Sale
• Vending Machines

​

Terminal Devices Supported

• WisePOS E
• FlexiPOS
• HitPay All-in-One Ingenico S1F2
• HitPay All-in-One Ingenico DX4000

​

How It Works

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 / FlexiPOS only): 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

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',
  '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',
  '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

{
  "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
  }
}

​

Handle Webhooks

​

Register Your Webhook

1. Navigate to Developers > Webhook Endpoints in your dashboard
2. Click on New Webhook
3. Enter a name and your webhook URL
4. Select the payment_request.completed event
5. Save your webhook configuration

​

Webhook Payload

​

Sample Webhook Payload

{
  "id": "9c262fb5-f3cd-4187-8c3e-fbe20730b9c6",
  "name": "John Doe",
  "email": "[email protected]",
  "amount": "599.00",
  "currency": "SGD",
  "status": "completed",
  "reference_number": "ORDER123",
  "payment_methods": ["wifi_card_reader"],
  "created_at": "2024-05-28T14:37:11",
  "updated_at": "2024-05-28T14:38:25",
  "payments": [
    {
      "id": "9c262fb5-a1b2-4c3d-8e9f-123456789abc",
      "status": "succeeded",
      "currency": "sgd",
      "amount": "599.00",
      "refunded_amount": "0.00",
      "payment_type": "card_present",
      "fees": "2.50",
      "created_at": "2024-05-28T14:37:11",
      "updated_at": "2024-05-28T14:38:25"
    }
  ]
}

​

Validating the Webhook

function validateWebhook($payload, $signature, $salt) {
    $computedSignature = hash_hmac('sha256', $payload, $salt);
    return hash_equals($computedSignature, $signature);
}

// Usage
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_HITPAY_SIGNATURE'];
$salt = 'your_salt_from_dashboard';

if (validateWebhook($payload, $signature, $salt)) {
    $data = json_decode($payload, true);
    // Process the payment confirmation
    // Mark order as paid
} else {
    http_response_code(401);
    exit('Invalid signature');
}

​

Next Steps

• Learn how to handle failed payment requests
• Get started with testing in Sandbox

​

FAQs