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

# Get Payment Status | Payments API

> Retrieve payment status via the Atoa Payments API, request parameters, response schema and code samples in cURL, Python, JavaScript, PHP, Go and Java.

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).For a more effective approach, consider implementing an [exponential back-off strategy](https://en.wikipedia.org/wiki/Exponential_backoff).

So this API can be used to check the status of an individual payment transaction through polling, in case your integration hasn't been setup for webhook usage.

> [!NOTE]
>
> NOTE: If the customer hasn't initiated any payment, calling this API will
> result in a '200 OK' with message: Payment not initiated.

> [!NOTE]
>
> **Card Payments:** For card transactions, this endpoint returns additional `cardPaymentDetails` in each transaction detail. Within `cardPaymentDetails`, `metadata.isMitPayment: true` indicates a merchant-initiated [card-on-file](https://docs.paywithatoa.com/api-reference/card-on-file/introduction.md) payment. The overall payment `status` may be `AUTHORIZED` (for MANUAL\_CAPTURE payments not yet captured) or `CANCELLED` (for cancelled authorizations), in addition to the standard statuses — these values only appear for card-on-file payments.

**Request Body Schema**

**id** `string` *required*

The PaymentRequestId is required for this step, which you'll receive it from
the process-payment API when generating a payment request.

**env** `string` (default: production)

pass env=sandbox in case of sandbox env.

**Response**

**userUuid** `string`

Unique identifier assigned to the user who initiated the payment

**paymentRequestId** `string`

Unique identifier for this specific payment request

**customerId** `string`

Unique identifier for the customer making the payment

**merchantId** `string`

Unique identifier for the merchant

**merchantName** `string`

Business name of the merchant

**applicationUserId** `string`

Unique Identifier for the customer who made the payment

**callback** `string`

URL that will be called after payment completion

**avatar** `string`

URL of the merchant's store profile image

**signatureHash** `string`

Cryptographic hash used to verify payment authenticity

**redirectUrlParams** `object`

Additional parameters passed in the redirect URL after payment

**status** `string`

Current status of the payment: `COMPLETED`, `PENDING`, `FAILED`, `AUTHORIZED`, or `CANCELLED`. The `AUTHORIZED` and `CANCELLED` statuses only apply to [card-on-file](https://docs.paywithatoa.com/api-reference/card-on-file/introduction.md) payments with `MANUAL_CAPTURE` or `CAPTURE_BEFORE_EXPIRY` capture type.

**paidAmount** `number`

Total amount paid by the customer

**currency** `string`

Currency code for the transaction (e.g. GBP)

**taxAmount** `number`

Amount of tax charged on the transaction

**serviceAmount** `number`

Service fees charged on the transaction

**tipAmount** `number`

Tip amount added by the customer

**notes** `string`

Custom note provided during [Payment Request Creation](https://docs.paywithatoa.com/api-reference/payment/process-payment.md).

**storeDetails** `object`

**id** `string`

Unique identifier for the merchant's store location

**address** `string`

Physical address of the store

**locationName** `string`

Display name of the store location

**transactionDetails** `array`

**paymentIdempotencyId** `string`

Unique reference ID provided by ATOA eg. ATOA1692417435050

**consumerId** `string`

Unique identifier for the customer

**consumerName** `string`

Name of the customer as registered with their bank

**institutionId** `string`

Identifier for the customer's banking institution

**tracingId** `string`

Internal tracking ID for the transaction

**statusDetails** `object`

**status** `string`

Current processing status of the payment

**statusUpdateDate** `string`

Timestamp of the last status update

**isoStatus** `object`

**code** `string`

Standardized ISO payment status code

**name** `string`

Human-readable description of the ISO status code

**paidAmount** `number`

Amount paid in this specific transaction

**currency** `string`

Currency code for this transaction

**BankName** `string`

Name of the customer's bank

**bankAccountNo** `string`

Masked bank account number of the customer

**createdAt** `string`

Timestamp when the transaction was initiated

**updatedAt** `string`

Timestamp of the last transaction update

**totalRefundAmount** `number`

Total amount refunded for this transaction

**taxAmount** `number`

Tax amount for this specific transaction

**serviceAmount** `number`

Service fees for this specific transaction

**tipAmount** `number`

Tip amount for this specific transaction

**notes** `string`

Additional notes or comments on the transaction

**metadata** `object`

Only present when metadata was supplied on the payment. See [Process Payment](https://docs.paywithatoa.com/api-reference/payment/process-payment.md) for the field limits.

**errorDescription** `string`

Detailed description of any errors that occurred

**paymentDevice** `object`

Details about the device used for payment

**splitBill** `boolean`

Indicates if this was part of a split bill payment

**refundDetails** `array`

**id** `string`

Unique identifier for this refund transaction

**amount** `number`

Amount refunded in this transaction

**status** `string`

Current status of the refund

**createdAt** `string`

Timestamp when the refund was initiated

**updatedAt** `string`

Timestamp of the last refund status update

**refundNotes** `string`

Reason or notes provided for the refund

**refundType** `string`

Indicates whether refund is FULL or PARTIAL

**currency** `string`

Currency code for the refund amount

**refundId** `string`

Unique UUID assigned to this refund

**cardPaymentDetails** `object`

Card-specific details. **Only present for card transactions.** The `metadata.isMitPayment` field indicates whether this was a merchant-initiated [card-on-file](https://docs.paywithatoa.com/api-reference/card-on-file/introduction.md) payment.

**cardType** `string`

Card brand (e.g., `VISA`, `MASTERCARD`)

**transactionSubType** `string`

Payment sub-type: `CARD`, `GOOGLE_PAY`, or `APPLE_PAY`

**displayText** `string`

Masked card display text (e.g., "Visa \*\*\*\* 4242")

**captureType** `string`

`AUTO_CAPTURE`, `MANUAL_CAPTURE`, or `CAPTURE_BEFORE_EXPIRY`

**metadata** `object`

Card payment metadata. `isMitPayment: true` indicates this is a card-on-file (merchant-initiated) payment. Also includes authorization/capture timestamps.

**paymentMethodId** `string`

The saved card/payment method ID used for this transaction

```json 200 theme={null}
{
  "userUuid": "65abed89-7e7f-44e1-8855-0ca696f9a75b",
  "paymentRequestId": "75abed89-7e7f-44e1-8855-0ca696f9a75b",
  "customerId": "string",
  "merchantId": "eed6202f-4dfd-42fc-9bc6-48323556b59d ",
  "merchantName": "John",
  "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": {
    "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
    "address": "London",
    "locationName": "Location 1"
  },
  "transactionDetails": [
    {
      "paymentIdempotencyId": "ATOA1692417435050",
      "consumerId": "eed6202f-4dfd-42fc-9bc6-48323556b59d ",
      "consumerName": "Doe",
      "institutionId": "modelo-sandbox",
      "tracingId": "e21d31cc354d44559d3c7b92ca07060a",
      "statusDetails": {
        "status": "COMPLETED",
        "statusUpdateDate": "2023-08-19T03:31:49.073Z",
        "isoStatus": {
          "code": "ACSC",
          "name": "AcceptedSettlementCompleted"
        }
      },
      "paidAmount": "100",
      "totalRefundAmount": "4",
      "currency": "GBP",
      "bankName": "Barclays",
      "bankAccountNo": "756",
      "createdAt": "2023-08-19T03:57:20.871Z",
      "updatedAt": "2023-08-19T03:57:20.871Z",
      "taxAmount": "2",
      "serviceAmount": "16",
      "tipAmount": "5",
      "notes": "string",
      "metadata": {
        "bookingId": "BK-42427",
        "orderReference": "ORD-1"
      },
      "errorDescription": "Insufficient funds",
      "paymentDevice": {},
      "splitBill": false,
      "refundDetails": [
        {
          "id": "ATOA1745651316374",
          "amount": 4,
          "currency": "GBP",
          "status": "COMPLETED",
          "createdAt": "2025-04-26T01:38:36.460Z",
          "updatedAt": "2025-04-26T01:38:40.337Z",
          "refundNotes": "notes",
          "refundType": "PARTIAL",
          "refundId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
  ]
}
```

```json 200 (Card Payment) theme={null}
{
  "paymentRequestId": "9baa68d8-362a-4127-994d-2ea622ef35ee",
  "customerId": "550e8400-e29b-41d4-a716-446655440000",
  "merchantId": "eed6202f-4dfd-42fc-9bc6-48323556b59d",
  "merchantName": "My Shop",
  "applicationUserId": "99abed89-7e7f-44e1-8855-0ca696f9a75b",
  "callback": "string",
  "avatar": "string",
  "orderId": "ORDER-001",
  "signatureHash": "string",
  "redirectUrlParams": {},
  "status": "AUTHORIZED",
  "paidAmount": 10.50,
  "currency": "GBP",
  "taxAmount": 0,
  "serviceAmount": 0,
  "tipAmount": 0,
  "storeDetails": {
    "id": "d77e02d5-4e93-46cf-a8be-50da650df562",
    "address": "London",
    "locationName": "London Store"
  },
  "transactionDetails": [
    {
      "paymentIdempotencyId": "ATOA1692417435050",
      "consumerId": "consumer_123",
      "consumerName": "John Doe",
      "tracingId": "e21d31cc354d44559d3c7b92ca07060a",
      "statusDetails": {
        "status": "AUTHORIZED",
        "statusUpdateDate": "2025-06-15T10:30:05.000Z",
        "isoStatus": {
          "code": "PDNG",
          "name": "Pending"
        }
      },
      "paidAmount": 10.50,
      "totalRefundAmount": 0,
      "currency": "GBP",
      "createdAt": "2025-06-15T10:30:00.000Z",
      "updatedAt": "2025-06-15T10:30:05.000Z",
      "notes": "Payment for order #001",
      "metadata": {
        "bookingId": "BK-42427",
        "orderReference": "ORD-1"
      },
      "splitBill": false,
      "refundDetails": [],
      "cardPaymentDetails": {
        "cardType": "VISA",
        "transactionSubType": "CARD",
        "displayText": "Visa **** 4242",
        "captureType": "MANUAL_CAPTURE",
        "metadata": {
          "authorized": true,
          "authorizedAt": "2025-06-15T10:30:05.000Z",
          "captured": false,
          "isMitPayment": true
        },
        "paymentMethodId": "card_abc123def456"
      }
    }
  ]
}
```

```json 401 theme={null}
{
  "name": "UNAUTHORIZED",
  "message": "Unauthorized",
  "status": 401,
  "errors": "[]"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.