> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithatoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote Payments on a PAX Terminal

> Trigger a card or Pay by Bank payment on your own PAX terminal through the Atoa API. Set up remote payments and process your first charge.

> [!WARNING]
>
> If card or terminal payments are not enabled on your account, please [contact
> support](https://help.paywithatoa.co.uk).

## Introduction

Remote Payments let a merchant trigger a payment on their own **PAX terminal**
via the API. You call the Atoa API with
your SDK API key, choose one of your registered terminals, and the terminal
prompts the customer to pay — by **card** or **Pay by Bank**.

## Prerequisites

Before you start, make sure the following are in place:

* **An Atoa SDK API key.** Generate it from the Atoa Merchant Dashboard under API
  Access. Call the Remote Payments endpoints from your **server**.
* **A registered PAX terminal with remote payments enabled.** Terminals are
  **provisioned by Atoa**. On the terminal, open the **Remote Payments** page in
  the PAX app's **Settings** view and make sure it shows **Connected** — that
  confirms the terminal can receive remote payments.

## Authentication

All Remote Payments endpoints authenticate with your SDK API key as a bearer
token:

```
Authorization: Bearer <token>
```

The merchant is resolved from the API key you authenticate with.

## End-to-end flow

**1. List your terminals**

Call [List Terminals](https://docs.paywithatoa.com/api-reference/remote-payments/list-terminals.md)
(`POST /api/terminal/list`) to fetch the terminals registered
against your merchant account. Pick one that is enabled for remote payments
and has a push-notification device (`tokenMissing: false`). Send a
`storeIds` array in the request body to filter to terminals in specific
stores; omit it to list terminals across all your stores. Live `online` /
`lastActive` presence is resolved by default — send `availability: false` to
skip it.

**2. Create the remote payment**

Call [Process Remote
Payment](https://docs.paywithatoa.com/api-reference/remote-payments/process-remote-payment.md)
(`POST /api/terminal/process-remote-payment`) with the terminal `id`, the
`amount`, and optionally the `paymentMethod` (one of `CARD` or
`PAY_BY_BANK` — if omitted or set to any other value, the terminal shows
both), `notes`, and `consumerDetails`.

On success the endpoint returns a `paymentRequestId`, and the target
terminal prompts the customer to complete the payment.

**3. Track the outcome**

Use the `paymentRequestId` to follow the payment to a terminal state. There
are two ways to do this, and you can use both:

* **Poll the status endpoint** — call [Get Payment
  Status](https://docs.paywithatoa.com/api-reference/payment/get-payment-status.md)
  (`GET /api/payments/v1/payment-status/:id`) with the `paymentRequestId`.
  Poll at intervals (an [exponential
  back-off](https://en.wikipedia.org/wiki/Exponential_backoff) is
  recommended) until the status is terminal.
* **Receive the webhook** — subscribe to the [`POS_PAYMENT_STATUS`
  webhook](https://docs.paywithatoa.com/api-reference/webhook/pos-payment-status-webhook-response), which is
  pushed to your endpoint when the terminal payment reaches a terminal
  state. This requires a [V2 signing
  secret](https://docs.paywithatoa.com/api-reference/webhook/v2-signing.md) (a `whsec_` secret) — you must
  generate one before you can subscribe to `POS_PAYMENT_STATUS`.

## Errors

For the full list of error responses on the create call — `400`, `401`, `404`,
`500` and when each occurs — see the error table on [Process
Remote Payment](https://docs.paywithatoa.com/api-reference/remote-payments/process-remote-payment.md).

## Troubleshooting

> **The terminal shows 'Not connected'**
>
> Restart the terminal app so it reconnects, then re-check Settings → Remote payments.

> **Nothing appears on the terminal after I send**
>
> The terminal is switched off or offline, or it's busy with another payment.
> Make sure it's on and shows **Connected**, finish or clear any payment already
> on screen, then send again.

> **I sent another request but the terminal didn't switch to it**
>
> The terminal only shows a new request when it isn't already handling a payment. If it's free,
> it switches to the latest request you send. But if a payment is already in progress — including
> an in-person payment on the terminal — the new request is **silently cancelled**, with no
> status update and no webhook. Wait for the current payment to finish, or clear it on the
> terminal, before sending again.

## Need help?

Email us at [hello@paywithatoa.co.uk](mailto:hello@paywithatoa.co.uk) or reach out via the dashboard's chat
support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.