Getting started

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

​

Step 1 - Sign up for developer access

To generate an API Access token from the Atoa Business App, follow the step-by-step instructions below:

1. Install the Atoa Business app from Play store or Appstore.
2. Sign up and verify with your business and personal details.
3. Click on the store icon on the homepage’s left side and tap on settings.
4. Click on API access and generate a sandbox key for testing When you’re prepared to go live, create a production key. For further instructions, see the video provided below.

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.

Option 1: Redirection and polling

Polling allows you to periodically check the transaction’s status by querying it at regular intervals.

If you wish to redirect users back to your website or a page for further interaction. In that case, you can specify the desired redirection URL.

After payment is successful, we send customers back to the redirection URL. You can set up this redirected URL while creating the API keys in step 1.

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

If a payment is still in process (status: PENDING), you need to check back periodically to see if it’s done. This usually takes 2-3 minutes, but it can vary based on the bank. For a more effective approach, consider implementing an exponential back-off strategy. Stop polling once a definitive status (SUCCESS or FAILURE) is received.

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

Pass query param &env=sandbox for sanbox testing

Option 2: Subscribe to webhook

Atoa uses webhooks to notify your application whenever an event happens in your account. Webhooks are particularly useful for events such as changes in payment status like completion, failure, or pending.

To get started, you need to Register your webhook endpoint so Atoa knows where to deliver events.

After registration, your endpoint will start receiving detailed webhook payloads. These will inform you of payment status updates, such as COMPLETED, PENDING, FAILED or EXPIRED.

Here are the payloads that you will receive for different payment status:

{
  "merchantId": "41a77f74-8b67-4f04-be50-c8dd5ad8836f",
  "customerId": "Abcam",
  "consumerId": "60513141-4d0f-4d3d-9c8a-cc1bd61f40fd",
  "merchantName": "John doe",
  "paymentIdempotencyId": "ATOA1695808662681",
  "status": "COMPLETED",
  "statusDetails": {
    "status": "COMPLETED",
    "statusUpdateDate": "2023-09-27T09:58:13.347Z",
    "isoStatus": {
      "code": "ACSC",
      "name": "AcceptedSettlementCompleted"
    }
  },
  "paidAmount": "1005",
  "tipAmount": "5.00",
  "currency": "GBP",
  "createdAt": "2023-09-27T09:57:50.067Z",
  "updatedAt": "2023-09-27T09:57:50.067Z",
  "taxAmount": 50.25,
  "serviceAmount": 30.15,
  "storeDetails": {
    "id": "ee39ecfa-e336-461c-a957-1adc76ac087c",
    "address": "Welwyn Garden City, Hertfordshire",
    "locationName": "DEFAULT"
  },
  "orderId": "003decb3-c35",
  "paymentRequestId": "6d1803f8-038a-48f3-8cd4-b44d37a3ab91",
  "signatureHash": "1ea6ff07ca90ec4ca34dfd3b420dcdfe5db2d73e3a5de05e5379e8aa325a5e2e",
  "errorDescription": null,
  "redirectUrlParams": {},
  "redirectUrl": "https://paywithatoa.co.uk",
  "splitBill": false
}

Here are the details of the payment status of the given payload :

​

Step 4 - Verify Signature

Verifying your signature helps to keep transactions processed on Atoa secure. Completing this step correctly safeguards against fraudulent activities and confirms the legitimacy of each transaction.

    1 orderId: Retrieve the orderId from your server. Do not use the atoaOrderId.
    2 paymentRequestId: Returned by Redirect url or polling api.
    3 atoaSecret: That was generated from first step.

generatedSignature = hmac_sha256(orderId + "|" + paymentRequestId, atoaSecret);
if (generatedSignature == atoaSignatureHash) {
   payment is successful
}

/**
* This class defines routines for generating signatures for verfying the payments authenticity.
*/
public class Signature
{
    private static final String HMAC_SHA256_ALGORITHM = "HmacSHA256";
    /**
    * Computes RFC 2104-compliant HMAC signature.
    * * @param data
    * The data to be signed.
    * @param key
    * The signing key.
    * @return
    * The Base64-encoded RFC 2104-compliant HMAC signature.
    * @throws
    * java.security.SignatureException when signature generation fails
    */
    public static String calculateRFC2104HMAC(String data, String secret)
    throws java.security.SignatureException
    {
        String result;
        try {

            // get an hmac_sha256 key from the raw secret bytes
            SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(), HMAC_SHA256_ALGORITHM);

            // get an hmac_sha256 Mac instance and initialize with the signing key
            Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM);
            mac.init(signingKey);

            // compute the hmac on input data bytes
            byte[] rawHmac = mac.doFinal(data.getBytes());

            // base64-encode the hmac
            result = DatatypeConverter.printHexBinary(rawHmac).toLowerCase();

        } catch (Exception e) {
            throw new SignatureException("Failed to generate HMAC : " + e.getMessage());
        }
        return result;
    }
}

All set! You are all set to start accepting payment. We are constantly making efforts to improve atoa so If you are looking for deeper integration with atoa or have any doubts or feedback to improve feel free to share it with us at hello@paywithatoa.co.uk.