> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/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).
</Warning>

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

<Steps>
  <Step title="List your terminals">
    Call [List Terminals](/api-reference/RemotePayments/list-terminals)
    (`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.
  </Step>

  <Step title="Create the remote payment">
    Call [Process Remote
    Payment](/api-reference/RemotePayments/process-remote-payment)
    (`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.
  </Step>

  <Step title="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](/api-reference/Payment/getPaymentStatus)
      (`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](/api-reference/Webhook/posPaymentStatusWebhookResponse), which is
      pushed to your endpoint when the terminal payment reaches a terminal
      state. This requires a [V2 signing
      secret](/api-reference/Webhook/v2-signing) (a `whsec_` secret) — you must
      generate one before you can subscribe to `POS_PAYMENT_STATUS`.
  </Step>
</Steps>

## 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](/api-reference/RemotePayments/process-remote-payment).

## Troubleshooting

<AccordionGroup>
  <Accordion title="The terminal shows 'Not connected'">
    Restart the terminal app so it reconnects, then re-check Settings → Remote payments.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Sandbox

There is no sandbox path for card charges on a terminal today — PAX terminals
are production hardware, and card acceptance is a live-only flow. Sandbox
testing for Atoa focuses on Pay by Bank. See the [Sandbox
Guide](/atoa-sandbox) for simulating Pay by Bank outcomes.

<Warning>
  **Card payments require a real card in every environment.** There are no test
  cards or simulated card outcomes — a physical card must be presented on the
  terminal to complete a card charge, even when you authenticate with a sandbox
  API key. Only Pay by Bank can be simulated in sandbox.
</Warning>

## Need help?

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