Skip to main content
If card or terminal payments are not enabled on your account, please contact support.

​
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:
The merchant is resolved from the API key you authenticate with.

​
End-to-end flow

1

List your terminals

Call 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.
2

Create the remote payment

Call 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.
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 (GET /api/payments/v1/payment-status/:id) with the paymentRequestId. Poll at intervals (an exponential back-off is recommended) until the status is terminal.
  • Receive the webhook — subscribe to the POS_PAYMENT_STATUS webhook, which is pushed to your endpoint when the terminal payment reaches a terminal state. This requires a V2 signing secret (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.

​
Troubleshooting

Restart the terminal app so it reconnects, then re-check Settings → Remote payments.
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.
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.

​
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 for simulating Pay by Bank outcomes.
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.

​
Need help?

Email us at [email protected] or reach out via the dashboard’s chat support.