Integrate Atoa as the payment method in just four easy steps..

​
Step 1 - Sign up for developer access

You can generate an API Access Token via the Atoa Dashboard or the Atoa Business App. Follow the steps below:

  1. Sign up via Atoa dashboard or Install the Atoa Business app from Play store or App store.
  2. Complete KYB to verify your business and personal details.
  3. To access API settings:
    • On the App: Tap the store icon on the homepage’s top left → go to Settings → API Access.
    • On the Dashboard: Visit your Dashboard API Access page directly
  4. Generate a Sandbox Key for testing.
  5. When you’re ready to go live, create a Production Key.
  6. For detailed guidance, refer to the video walkthrough for the Atoa Business App.

Follow Our sandbox guide to simulate successful, failed and cancelled payment scenarios with Atoa.

If you need any help please contact our team at hello@paywithatoa.co.uk.

​
Step 2 - Create Payment Request.

Generate a Payment Request.

API Endpoint:

https://api.atoa.me/api/payments/process-payment

curl --location --request POST 'https://api.atoa.me/api/payments/process-payment' \
--header 'Authorization: Bearer {Access Secret}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "customerId": "<Your Unique Customer Id>",
    "orderId": "<Order Id>",
    "amount": "<Total Amount >",
    "currency": "GBP",
    "paymentType": "<DOMESTIC>",
}'

You can include additional parameters in the body of the request, check the API reference for further information.

After you generate a payment request, you will receive a qrCodeUrl and a paymentUrl. You can use either of these to handle payments, depending on your needs: There are two ways to handle the payment flow depending on the use case.

Option 1:

Payment URL - Use the payment URL from response to let your customers complete their payment online.

Option 2:

QR Code URL - If you’re using a Point Of Sale (POS) system, you can show this QR code on a screen, receipt, or any device at your store. Customers can scan this QR code to pay.

​
Step 3 - Handle Payment Status

Once the user completes the payment, you must verify the payment status. Atoa offers two methods for this: Polling and Webhook.

We recommend webhooks over polling for a more reliable integration. Webhooks deliver status updates in real time, removing the need for repeated API calls.

​
Option 1: Redirection and polling

When you create a payment request, you can specify a redirection URL. After the customer completes (or abandons) the payment, Atoa redirects them back to that URL with the payment status appended as query parameters:

https://<yourRedirectUrl>?status=<SUCCESS/FAILURE/PENDING>&paymenRequestId=<paymenRequestId>&paymentIdempotencyId=<paymentIdempotencyId>&orderId=<atoaOrderId>&atoaSignature=<atoaSignature>

You can set up your redirection URL when creating API keys in Step 1.

If the status is PENDING, the payment is still being processed by the bank. Poll the Get Payment Status endpoint until you receive a definitive status (SUCCESS or FAILURE). Use an exponential back-off strategy to avoid excessive requests.

curl --location --request GET 'https://api.atoa.me/api/payments/payment-status/<paymenRequestId>?type=request'

Pass query param &env=sandbox for sandbox testing.

StatusDescription
COMPLETEDPayment processed successfully. Funds have been transferred to the merchant’s account.
PENDINGPayment is in progress and awaiting final confirmation from the bank.
FAILEDTransaction was unsuccessful. The customer will have to retry the payment.

Webhooks notify your server in real time whenever a payment is completed, fails, expires, or is refunded — no polling required. Atoa delivers a signed HTTP POST to your registered endpoint with the full event payload.

For everything you need to set up webhooks — registering endpoints, event types, payload references, signature verification, and retry mechanism — see the Webhook guide.

All set! You are ready to start accepting payments. If you have any questions or feedback, reach out to us at hello@paywithatoa.co.uk.

Design GuidelinesSandbox Guide