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
- 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:
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.
Mandatory fields are amount and currency
|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|
$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.
- Create an endpoint (E.g. /payment-confirmation/webhook) in your server that accepts POST requests. This request is
- Validate the webhook data using your salt value. Refer to this section for more details
- Return HTTP status code 200 to Hitpay
- Mark your order as paid
Sample webhook payload data
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
Updated 2 months ago