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

```bash
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.

```bash
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:

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