Skip to main content
Documentation Powered by Redocly

Api documentation (1.1.0)

Download OpenAPI specification:Download

Authentication

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

PaymentsController

Get Stores

By default atoa creates a store for every business. But merchants too can create multiple stores under the same business name. Atoa’s multi store feature allows merchants to manage multiple stores

Authorizations:
bearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "page": 0,
    • "size": 20,
    • "data": [
      ],
    • "totalCount": 0
    }

    Generate payment

    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:
    bearerAuth
      Request Body schema: application/json
      customerId
      required
      string (Merchant customer id) non-empty

      Details of the end user who is making the payment.

      orderId
      required
      string (Merchant order id) non-empty

      Orderid of the merchant who is accepting the payment from the customers

      amount
      number (Amount)

      The total cart amount for the payment.

      currency
      required
      string (currency) non-empty

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

      institutionId
      string (Bank institution id)

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

      storeId
      string (Merchant store id)

      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
      required
      string (Merchant payment type) non-empty

      We only allow merchants to accept domestic payment for now.

      autoRedirect
      required
      boolean (Auto Redirect)

      Auto redirect to bank app, only useful if institution id is passed.

      object (PaymentConsumerDetails)
      callbackParams
      object (Callback Params)

      After the transaction is completed by the customer they would be redirected to the callback param.

      expiresIn
      number (Expires In)
      Default: 180000

      Expressed in milliseconds after which the payment link should expire

      enableTips
      boolean (Enable Tips)
      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 (allow retry)
      Default: true

      By default, consumers have the option to retry a payment if it gets stuck. To disable the retry button, set this parameter to false.

      strictExpiry
      boolean (strict expiry)
      Default: false

      By default, strict expiry is set to false. If you wish to specify the exact duration after which a payment should expire, provide a value in milliseconds. Use this parameter when you want to enforce a specific countdown duration, such as 2 or 4 minutes, for the customer to complete the payment.

      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 (split bill)
      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.

      Responses

      Request samples

      Content type
      application/json
      {
      • "customerId": "549000a4-eee4-4b7d-bc88-c529a92544cd",
      • "orderId": "6eb7e0f8-972a-4bf6-99d2-864bdccd5a34",
      • "amount": "25",
      • "currency": "GBP",
      • "institutionId": "modelo-sandbox",
      • "storeId": "43c7b991-0803-4177-9589-d165d9a779f6",
      • "paymentType": "TRANSACTION",
      • "autoRedirect": true,
      • "consumerDetails": {
        },
      • "callbackParams": "{atoa:https://paywithatoa.co.uk}",
      • "expiresIn": 180000,
      • "enableTips": true,
      • "allowRetry": true,
      • "strictExpiry": false,
      • "redirectUrl": "https://paywithatoa.co.uk",
      • "splitBill": false,
      • "template": "EXTERNAL_DISPLAY or RECEIPT or EXTERNAL_DISPLAY_PNG or RECEIPT_PNG"
      }

      Response samples

      Content type
      application/json
      {}

      Cancel Payment

      The Cancel Payment API facilitates the quick cancellation of a payment request. Simply pass the paymentRequestId obtained during payment generation.

      Responses

      Response samples

      Content type
      application/json
      {
      • "message": "Your payment has been cancelled successfully."
      }

      Get Payment Status

      If the status is PENDING, you should Poll for success at regular intervals. It should take 2-3 minutes at maximum for payment to be completed (dependent on the bank used). So this API can be used to check the status of an individual payment transaction through polling, in case your integration hasn't been set up for webhook usage.

      Please note: If the customer hasn't initiated any payment, calling this API will result in a '200 OK' with message: Payment not initiated

      path Parameters
      id
      required
      string
      query Parameters
      env
      string
      Default: "production"

      pass env=sandbox in case of sandbox env

      Responses

      Response samples

      Content type
      application/json
      {
      • "userUuid": "65abed89-7e7f-44e1-8855-0ca696f9a75b",
      • "paymentRequestId": "75abed89-7e7f-44e1-8855-0ca696f9a75b",
      • "customerId": "string",
      • "merchantId": "eed6202f-4dfd-42fc-9bc6-48323556b59d ",
      • "merchantName": "jhon",
      • "applicationUserId": "99abed89-7e7f-44e1-8855-0ca696f9a75b",
      • "callback": "string",
      • "avatar": "string",
      • "orderId": "e21d31cc3",
      • "signatureHash": "string",
      • "redirectUrlParams": { },
      • "redirectUrl": "https://paywithatoa.co.uk",
      • "status": "COMPLETED",
      • "paidAmount": "100",
      • "currency": "GBP",
      • "taxAmount": "2",
      • "serviceAmount": "16",
      • "tipAmount": "5",
      • "storeDetails": {
        },
      • "transactionDetails": [
        ]
      }

      AccountsController

      Get Authorization Url

      The authorization URL facilitates users in acquiring the necessary web address to initiate the authorization process, thereby granting access to a designated bank application.

      Request Body schema: application/json
      applicationUserId
      required
      string non-empty

      Username of the Merchant or Consumer

      institutionId
      required
      string non-empty

      Institutions Id

      features
      required
      array

      Features specifices if it is redirect or embedded or coupled flow for authorization

      Responses

      Request samples

      Content type
      application/json
      {
      • "applicationUserId": "b58a13ed-d6e8-402c-aa28-8b93d1e22c5",
      • "institutionId": "modelo-sandbox",
      • "features": "[ACCOUNTS,ACCOUNT_TRANSACTIONS]"
      }

      Response samples

      Content type
      application/json
      {}

      Get Bank accounts

      This Get account API provide the bankaccount details for the unique consent ID

      header Parameters
      consent
      string

      Responses

      Response samples

      Content type
      application/json
      {
      • "id": "1560c034-1b01-4274-ab16-ff581e3f86cb",
      • "accountType": "CURRENT",
      • "accountNames": {
        },
      • "sortCode": "726908",
      • "accountNumber": "50978130",
      • "currency": "GBP"
      }

      InstitutionsController

      Get List of Available Institutions or Banks

      Retrieve a comprehensive list of available institutions, accompanied by their respective images

      Responses

      Response samples

      Content type
      application/json
      {}

      PaymentsTransactionController

      Get Payment Transactions

      Retrieve payment transactions specifically associated with the designated merchant.

      • 'COMPLETED': Payment transaction successfully processed.
      • 'PENDING': Payment awaiting processing.
      • 'REFUND': Payment refunded or reversed.
      • 'EXPIRED': Payment transaction time limit exceeded.
      • 'CANCELED': Payment has been canceled.
      • 'FAILED': Unsuccessful payment transaction.
      query Parameters
      page
      integer multiple of 1 >= 0
      Default: 0

      Page number.

      size
      integer multiple of 1 >= 1
      Default: 20

      Number of objects per page.

      search
      string

      Responses

      Response samples

      Content type
      application/json
      {
      • "page": 0,
      • "size": 20,
      • "data": [
        ],
      • "totalCount": 0
      }

      WebhookController

      Create webhook event

      Generate a webhook event for a specific endpoint . Atoa leverages webhooks to instantly alert your application regarding any events within your account. This proves especially valuable for asynchronous occurrences, such as updates on payment transaction statuses, including completion, failure, or pending

      Request Body schema: application/json
      url
      required
      string (Webhook url) non-empty

      Merchant webhook url provided will receive notification on status code 200 and will be retried on failure

      event
      required
      string (Event type) non-empty
      Value: "PAYMENTS_STATUS"

      Event subscribed to which the webhook will be invoked

      Responses

      Request samples

      Content type
      application/json
      {}

      Response samples

      Content type
      application/json
      {
      • "webhookId": "4a124f25-fe8d-47a0-92c8-16d94cbfe24c",
      • "url": "https://api/endpoint",
      • "event": "PAYMENTS_STATUS"
      }

      Get all merchant webhooks

      Get's all merchants webhook

      Responses

      Response samples

      Content type
      application/json
      [
      • {
        }
      ]

      Process payment web hook response payload

      When you subscribe to the Atoa payment process webhook, the following is the sample payload response that you will receive at your endpoint.

      Responses

      Response samples

      Content type
      application/json
      {
      • "merchantId": "41a77f74-8b67-4f04-be50-c8dd5ad8836f",
      • "customerId": "Abcam",
      • "consumerId": "60513141-4d0f-4d3d-9c8a-cc1bd61f40fd",
      • "merchantName": "jhon doe",
      • "paymentIdempotencyId": "ATOA1695808662681",
      • "status": "COMPLETED",
      • "statusDetails": null,
      • "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": {
        },
      • "orderId": "003decb3-c35",
      • "paymentRequestId": "6d1803f8-038a-48f3-8cd4-b44d37a3ab91",
      • "signatureHash": "1ea6ff07ca90ec4ca34dfd3b420dcdfe5db2d73e3a5de05e5379e8aa325a5e2e",
      • "errorDescription": "null",
      • "redirectUrlParams": "{}",
      • "redirectUrl": "https://paywithatoa.co.uk"
      }