# Terminal Payments

> For the complete documentation index, see [llms.txt](/llms.txt).

Integrate your POS (Point of Sale) terminal with Unipaas to accept in-person, card-present payments, giving your staff and customers a seamless checkout at the counter.

You initiate a payment from your server, the cardholder taps or inserts their card at the terminal, and Unipaas confirms the result through a webhook.

## Before you begin

To take terminal payments you need a Unipaas device. To find out more about getting a Unipaas device and to place an order for terminals, contact <support@unipaas.com>.

Note

Make sure your terminal is connected and ready before you send the payment request.

## Send the payment request

To initiate a terminal payment, make a **POST /pay-ins** request from your server with `isCardPresent` set to `true`.

| Field           | Type    | Required | Description                                         |
| --------------- | ------- | -------- | --------------------------------------------------- |
| `amount`        | Number  | Yes      | Amount to charge, in major currency units.          |
| `currency`      | String  | Yes      | Currency code, for example `GBP`.                   |
| `country`       | String  | Yes      | Country code, for example `GB`.                     |
| `isCardPresent` | Boolean | Yes      | Must be `true` for terminal transactions.           |
| `vendorId`      | String  | Yes      | Unique identifier of the vendor using the terminal. |
| `orderId`       | String  | Yes      | Your unique reference for this payment.             |

* cURL

  ```curl
  curl --location --request POST 'https://sandbox.unipaas.com/platform/pay-ins' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer --YOUR_PRIVATE_KEY--' \
  --data-raw '{
    "amount": 19,
    "currency": "GBP",
    "country": "GB",
    "isCardPresent": true,
    "vendorId": "{{vendor_id}}",
    "orderId": "1000456"
  }'
  ```

## Listen for the authorization/update webhook

After the customer taps or inserts their card at the terminal, Unipaas sends an `authorization/update` webhook to confirm the result. Listen for this webhook to reconcile the payment.

* JSON

  ```json
  {
    "event": "authorization/update",
    "data": {
      "transactionId": "txn_123456789",
      "status": "Captured",
      "amount": 19,
      "currency": "GBP",
      "cardType": "VISA",
      "cardLast4": "1234",
      "timestamp": "2025-05-29T14:32:10Z",
      "orderId": "1000456"
    }
  }
  ```

| Field           | Description                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `transactionId` | The Unipaas transaction identifier.                                                                                   |
| `status`        | Updates to `Captured` once the cardholder approves the transaction. You may also receive failed or declined statuses. |
| `amount`        | The amount of the payment.                                                                                            |
| `currency`      | The currency of the payment.                                                                                          |
| `cardType`      | The card scheme, for example `VISA`.                                                                                  |
| `cardLast4`     | The last four digits of the card.                                                                                     |
| `timestamp`     | When the transaction was processed.                                                                                   |
| `orderId`       | Your reference, echoed back from the payment request.                                                                 |

The `status` updates to `Captured` once the cardholder approves the transaction. You may also receive failed or declined statuses, so handle these in your POS interface and show the customer the outcome.

## Best practices

* Confirm the terminal is connected and ready before you send the payment request.
* Display clear payment instructions on your POS screen while waiting for authorisation.
* Store the webhook response for reconciliation and support purposes.