Working with terminals

Overview

Reservepay API allows you to accept in-person payments using physical hardware. You can integrate with terminals in two ways:

1. Build your own Point of Sale (POS) system that communicates directly with our Terminal API.
2. Use our terminal app on your device and trigger actions via deep links from your own mobile application.

Direct API integration

If you are building your own POS software, you can use the Reservepay Terminal API to manage device connections and the Reservepay Merchant API to trigger payments on those devices.

1. Connect a device

First, bind your physical device to a terminal defined in your dashboard.

curl -X POST https://api.reservepay.com/terminals/connect-device \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "mer_686790162102",
    "terminal_id": "trm_U4vfjCFwwK",
    "device_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

2. Start a payment

To trigger a payment on a connected terminal, use the start-payment-on-terminal endpoint from the Merchant API.

curl -X POST https://api.reservepay.com/merchants/start-payment-on-terminal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "terminal_id": "trm_U4vfjCFwwK",
    "amount": 1000,
    "currency": "THB",
    "payment_method": "CARD"
  }'

3. Receive real-time events (SSE)

To receive real-time updates from the terminal (such as payment completion or status changes), your POS should listen to our Server-Sent Events (SSE) stream.

Connect to the following endpoint using your device_id:

https://rt.reservepay.com/terminals/550e8400-e29b-41d4-a716-446655440000

Currently, the stream supports the following events:

• start_terminal_payment: Triggered when a payment is initiated on the terminal.
• abort_terminal_payment: Triggered when a payment process is cancelled.

Example using JavaScript:

const deviceId = '550e8400-e29b-41d4-a716-446655440000';
const eventSource = new EventSource(`https://rt.reservepay.com/terminals/${deviceId}`);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received terminal event:', data);
};

eventSource.addEventListener('start_terminal_payment', (event) => {
  const data = JSON.parse(event.data);
  console.log('Payment started:', data);
});

eventSource.addEventListener('abort_terminal_payment', (event) => {
  const data = JSON.parse(event.data);
  console.log('Payment aborted:', data);
});

eventSource.onerror = (error) => {
  console.error('SSE connection failed:', error);
};

Mobile app integration (deep links)

For a simpler integration, you can use the Reservepay Terminal app and trigger actions using our custom URL scheme: reservepay-terminal://.

Start a payment

To initiate a payment, open the following URL from your app:

reservepay-terminal://start-payment?amount=1000&currency=THB&payment_method=PROMPTPAY

Setup a terminal

To quickly configure a terminal on a new device:

reservepay-terminal://setup-terminal?merchant_id=mer_686790162102&terminal_id=trm_U4vfjCFwwK

Terminal management

You can manage your terminals, view their connection status, and update their configuration through the Terminals section in your Reservepay Dashboard.