POST
/
api
/
payments
/
process-payment
  curl --request POST \
  --url https://api.atoa.me/api/payments/process-payment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customerId": "549000a4-eee4-4b7d-bc88-c529a92544cd",
  "orderId": "6eb7e0f8-972a-4bf6-99d2-864bdccd5a34",
  "amount": 123,
  "currency": "GBP",
  "institutionId": "modelo-sandbox",
  "storeId": "43c7b991-0803-4177-9589-d165d9a779f6",
  "paymentType": "TRANSACTION",
  "autoRedirect": true,
  "consumerDetails": {
    "phoneCountryCode": "44",
    "phoneNumber": "7598570522",
    "email": "John@gmail.com",
    "firstName": "John",
    "lastName": "Doe"
  },
  "callbackParams": {"atoa":"https://paywithatoa.co.uk"},
  "expiresIn": 180000,
  "enableTips": true,
  "allowRetry": true,
  "redirectUrl": "https://paywithatoa.co.uk",
  "splitBill": false,
  "template": "EXTERNAL_DISPLAY or RECEIPT or EXTERNAL_DISPLAY_PNG or RECEIPT_PNG"
}'

{
  "qrCodeUrl": "https://atoa-merchant-dev.s3.eu-west-2.amazonaws.com/payment-qr-codes/eed6202f-4dfd-42fc-9bc6-48323556b59d/1692703721570.svg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASV2VH7U5MIC62E5K%2F20230822%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230822T112842Z&X-Amz-Expires=3600&X-Amz-Signature=a17f22e0291ba9f3706fd686b41a8eda0aa5335e1f5bcac90aa05aa2425a4a7f&X-Amz-SignedHeaders=host",
  "qrCodeUrlPng": "https://atoa-merchant-dev.s3.eu-west-2.amazonaws.com/payment-qr-codes/eed6202f-4dfd-42fc-9bc6-48323556b59d/1692703721570.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASV2VH7U5MIC62E5K%2F20230822%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230822T112842Z&X-Amz-Expires=3600&X-Amz-Signature=a17f22e0291ba9f3706fd686b41a8eda0aa5335e1f5bcac90aa05aa2425a4a7f&X-Amz-SignedHeaders=host",
  "templateUrl": "https://atoa-merchant-dev.s3.eu-west-2.amazonaws.com/payment-qr-codes/eed6202f-4dfd-42fc-9bc6-48323556b59d/1692703721570.svg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIASV2VH7U5MIC62E5K%2F20230822%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230822T112842Z&X-Amz-Expires=3600&X-Amz-Signature=a17f22e0291ba9f3706fd686b41a8eda0aa5335e1f5bcac90aa05aa2425a4a7f&X-Amz-SignedHeaders=host",
  "paymentUrl": "https://atoa.me/pay/?paymentRequestId=9baa68d8-362a-4127-994d-2ea622ef35ee&callbackParams=e30=&source=EXTERNAL_MERCHANT",
  "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee"
}

To initiate a new payment request that can be completed by the customer, you will need to obtain your API key from the Atoa Business App. This endpoint should be called on the server-side to prevent exposing your API key.

AUTHORIZATIONS: Bearer <token>

REQUEST BODY SCHEMA

customerId
string
required

Unique Customer Id.

orderId
string
required

An Identifier you can use for transaction reference and signature verification.

amount
number
required

The total cart amount for the payment.

currency
string
required

The currency for this payment.(ISO Code format) e.g GBP for UK.

institutionId
string

Bank institution id - List of banks provided to the customer to complete the transaction.

storeId
string

If you want to create a payment under a particular store, else the transaction would be created in the default store. Refer to Getstore API.

paymentType
string
required

We only allow merchants to accept domestic payment for now.

autoRedirect
boolean

Auto-redirection is disabled by default (false). Enabling it (true) automatically redirects users to Atoa’s payment webpage for transaction completion.

consumerDetails
object
callbackParams
object

The completion of the payment process, the specified data is appended to the redirected URL. For example, if your redirected URL is https://paywithatoa.co.uk/ and your callback data is {couponCode:245561,refId:2342}, the final redirected URL would be https://paywithatoa.co.uk/?couponCode=245561&refId=2342.

expiresIn
number
default: "180000"

Expressed in milliseconds: This specifies the time after which an individual payment request will expire. If no expiresIn time is provided when creating a payment request, it will default to expire exactly 3 minutes later.

Note:- All URLs received in the API response will never expire. It’s the individual payment request that will expire if the user does not complete the payment within the specified time. Refer to the webhook guide for more details about the expiry payload.
enableTips
boolean
default: "true"

Deciding whether to include tip collection on payments. The option to enter tips will only be displayed if tips are enabled in the Atoa Business app as well. In the event that tips are enabled in the app but ‘enableTips’ is passed as false, it will override and prevent the tips input from being shown to the user.

allowRetry
boolean
default: "true"

To enable consumers to retry their payment if the transaction fails or stalls, set this parameter to true. If not, set it to false. The default value is true.

redirectUrl
string

You have the option to include a redirect URL. Once the payment is successfully completed, the customer will be automatically redirected to the specified URL.

splitBill
boolean
default: "false"

By default, split bill is set to false. The ‘splitBill’ parameter empowers your customers with the ability to seamlessly divide the total bill among their friends during the payment process. This feature proves particularly valuable in scenarios like dining at restaurants, facilitating a hassle-free equal distribution of expenses within a group of friends.

template
enum

To elevate your customer’s payment experience through ATOA QR codes on both the Till display and customer receipts, utilize the following parameter.

Displaying QR Codes on Kiosk or Till:

Generate an ATOA QR template image for external displays by including the ‘template’ parameter with values ‘EXTERNAL_DISPLAY’ (SVG format) or ‘EXTERNAL_DISPLAY_PNG’ (PNG format). This feature enables customers to easily scan the QR code from the kiosk or till, ensuring a swift and seamless payment process.

Printing QR Codes on Customer Receipts:

Effortlessly integrate an ATOA QR image into your customer receipts by using the ‘template’ parameter with values ‘RECEIPT’ (SVG format) or ‘RECEIPT_PNG’ (PNG format). Print this on the customer receipt from the terminal printer, allowing customers to scan the QR code and complete the payment process.

If a redirection URL is initially set during access token creation but a different URL is provided in the process-payment API, the URL from the process-payment API will be prioritized.

RESPONSE

qrCodeUrl
string

URL to retrieve the QR code for payment initiation. Suitable for scanning with any camera app.

qrCodeUrlPng
string

URL for the QR code in PNG format, offering a background-free image for versatile use.

templateUrl
string

URL to fetch display or receipt images based on the specified template. Ideal for QR displays on kiosks or printing on receipts.

paymentUrl
string

Direct link for payment, encoded in the QR code. It bridges the QR scan to the payment gateway.

paymentRequestId
string

A unique identifier for the payment request, crucial for tracking the payment from start to finish.

Get StoresCancel Payment