Skip to main content
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 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.
  • 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.
Once set, metadata is returned in the Get Transactions, Get Payout Transactions, and Get Payment Status responses, and is included in the POS Payment Status Webhook.
Metadata is frozen when the payment is created and cannot be changed afterwards. An empty object ({}) is treated as no metadata.
Response
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 returned paymentRequestId, 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