Remote Payments
Process Remote Payment
Trigger a payment on a merchant’s own PAX terminal remotely through the Atoa API, and track it to completion using webhooks.
POST
Creates a remote payment request and notifies a POS terminal so it can present the payment to the customer. The merchant is resolved from the SDK API key you authenticate with.
Pick the target terminal with List Terminals and pass its
Response
id. On success the endpoint returns a paymentRequestId you can use to track the payment.
The whole payment is assembled server-side. Fields such as the customer id,
order id, expiry, tips, retry and split behaviour, store and terminal
binding, and environment are all set by Atoa. Only the fields documented
below are read from your request; any other field in the body is ignored.
Authorization
Bearer<token>
Body Parameters
string
required
The
id of the POS terminal that should receive the payment, as returned by
List Terminals. The terminal
must belong to the authenticated merchant, have a registered
push-notification device (tokenMissing: false), and have remote payments
enabled.number
required
The amount to charge. Must have at most 2 decimal places.
string
Controls the set of payment methods shown to the customer on the terminal. If not specified, the terminal defaults to offering all payment methods enabled on the merchant account.
Possible enum values
Possible enum values
-
PAY_BY_BANK– When provided, only Pay by Bank will be shown to the customer. -
CARD– When provided, only card payment will be shown to the customer. If card is not enabled in your account please contact support. - If omitted or set to any other value, both options are displayed, allowing the customer to choose their preferred payment method.
string
Optional note shown to the customer. Trimmed of surrounding whitespace and must
not exceed 30 characters.
object
Optional customer details, saved as a consumer record and linked to this
payment. When both
phoneCountryCode and phoneNumber are supplied the phone
number is validated.object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- Up to 50 key-value pairs.
- Each key must be 1–40 characters and must not contain
[or]. - Each value must be a string of at most 500 characters.
Metadata is frozen when the payment is created and cannot be changed afterwards. An empty object (
{}) is treated as no metadata.string
required
The identifier (UUID) of the created payment request. Use it to track the
payment via the payment-status endpoint or the
POS_PAYMENT_STATUS webhook.What happens next
The target terminal prompts the customer to complete the payment. To track the outcome, poll Get Payment Status with the returnedpaymentRequestId, and/or subscribe to the
POS_PAYMENT_STATUS webhook.
Receiving webhooks requires a whsec_ signing secret configured for your
endpoint.
If you’re experiencing issues, please check the Troubleshooting
section.
Errors