> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.paywithatoa.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Atoa Payments

> Get started with Atoa payments: create a payment, show a QR code or link, and let customers pay from their bank app in seconds.

**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](https://dashboard.paywithatoa.co.uk/) or Install the Atoa Business app from [Play store](https://play.google.com/store/apps/details?id=com.atoa.merchant) or [App store](https://apps.apple.com/gb/app/atoa-business/id1620667507).
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](https://dashboard.paywithatoa.co.uk/my-account/settings/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.

<iframe width="560" height="315" src="https://www.youtube.com/embed/NW3OUzChG1E" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

<br />

{" "}

<Note>
  {" "}

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

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:

```bash theme={null}
https://api.atoa.me/api/payments/process-payment
```

```bash theme={null}
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](../api-reference/Payment/process-payment) 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**.

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

### 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](/api-reference/Payment/getPaymentStatus) endpoint until you receive a definitive status (`SUCCESS` or `FAILURE`). Use an [exponential back-off strategy](https://en.wikipedia.org/wiki/Exponential_backoff) to avoid excessive requests.

```bash theme={null}
curl --location --request GET 'https://api.atoa.me/api/payments/payment-status/<paymenRequestId>?type=request'
```

<Note>
  Pass query param `&env=sandbox` for sandbox testing.
</Note>

| Status    | Description                                                                            |
| --------- | -------------------------------------------------------------------------------------- |
| COMPLETED | Payment processed successfully. Funds have been transferred to the merchant's account. |
| PENDING   | Payment is in progress and awaiting final confirmation from the bank.                  |
| FAILED    | Transaction was unsuccessful. The customer will have to retry the payment.             |

<a id="payment-expiration-payload" />

### Option 2: Subscribe to webhooks (Recommended)

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](/api-reference/Webhook/introduction).

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`.