Process Remote Payment
curl --request POST \
--url 'https://api.atoa.me/api/terminal/process-remote-payment' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"id": "1",
"amount": 42.50,
"paymentMethod": "PAY_BY_BANK",
"notes": "Table 12",
"consumerDetails": {
"phoneCountryCode": "+44",
"phoneNumber": "7700900123",
"email": "[email protected]",
"firstName": "Alex",
"lastName": "Doe"
}
}'
{
"paymentRequestId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
}
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
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.
The amount to charge. Must have at most 2 decimal places.
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.
Optional note shown to the customer. Trimmed of surrounding whitespace and must not exceed 30 characters.
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.
Response
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
| Status | When |
|---|---|
400 | Missing id, remote payments not enabled for the merchant or the terminal, terminal not configured for push notifications, or notes over the 30-character limit. |
401 | Missing or invalid API key. |
404 | Terminal not found, or not owned by the authenticated merchant. |
500 | Unexpected internal error. |
curl --request POST \
--url 'https://api.atoa.me/api/terminal/process-remote-payment' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"id": "1",
"amount": 42.50,
"paymentMethod": "PAY_BY_BANK",
"notes": "Table 12",
"consumerDetails": {
"phoneCountryCode": "+44",
"phoneNumber": "7700900123",
"email": "[email protected]",
"firstName": "Alex",
"lastName": "Doe"
}
}'
{
"paymentRequestId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301"
}