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

# 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>

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

**Request Body Schema**

<ParamField path="id" type="string" required>
  The PaymentRequestId is required for this step, which you'll receive it from
  the process-payment API when generating a payment request.
</ParamField>

<ParamField query="env" type="string" default="production">
  pass env=sandbox in case of sandbox env.
</ParamField>

**Response**

<ResponseField name="userUuid" type="string">
  Unique identifier assigned to the user who initiated the payment
</ResponseField>

<ResponseField name="paymentRequestId" type="string">
  Unique identifier for this specific payment request
</ResponseField>

<ResponseField name="customerId" type="string">
  Unique identifier for the customer making the payment
</ResponseField>

<ResponseField name="merchantId" type="string">
  Unique identifier for the merchant
</ResponseField>

<ResponseField name="merchantName" type="string">
  Business name of the merchant
</ResponseField>

<ResponseField name="applicationUserId" type="string">
  Unique Identifier for the customer who made the payment
</ResponseField>

<ResponseField name="callback" type="string">
  URL that will be called after payment completion
</ResponseField>

<ResponseField name="avatar" type="string">
  URL of the merchant's store profile image
</ResponseField>

<ResponseField name="signatureHash" type="string">
  Cryptographic hash used to verify payment authenticity
</ResponseField>

<ResponseField name="redirectUrlParams" type="object">
  Additional parameters passed in the redirect URL after payment
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the payment: `COMPLETED`, `PENDING`, `FAILED`, `AUTHORIZED`, or `CANCELLED`. The `AUTHORIZED` and `CANCELLED` statuses only apply to [card-on-file](/api-reference/CardOnFile/introduction) payments with `MANUAL_CAPTURE` or `CAPTURE_BEFORE_EXPIRY` capture type.
</ResponseField>

<ResponseField name="paidAmount" type="number">
  Total amount paid by the customer
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code for the transaction (e.g. GBP)
</ResponseField>

<ResponseField name="taxAmount" type="number">
  Amount of tax charged on the transaction
</ResponseField>

<ResponseField name="serviceAmount" type="number">
  Service fees charged on the transaction
</ResponseField>

<ResponseField name="tipAmount" type="number">
  Tip amount added by the customer
</ResponseField>

<ResponseField name="notes" type="string">
  Custom note provided during [Payment Request Creation](./process-payment).
</ResponseField>

<ResponseField name="storeDetails" type="object">
  <Expandable>
    <ResponseField name="id" type="string">
      Unique identifier for the merchant's store location
    </ResponseField>

    <ResponseField name="address" type="string">
      Physical address of the store
    </ResponseField>

    <ResponseField name="locationName" type="string">
      Display name of the store location
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="transactionDetails" type="array">
  <Expandable>
    <ResponseField name="paymentIdempotencyId" type="string">
      Unique reference ID provided by ATOA eg. ATOA1692417435050
    </ResponseField>

    <ResponseField name="consumerId" type="string">
      Unique identifier for the customer
    </ResponseField>

    <ResponseField name="consumerName" type="string">
      Name of the customer as registered with their bank
    </ResponseField>

    <ResponseField name="institutionId" type="string">
      Identifier for the customer's banking institution
    </ResponseField>

    <ResponseField name="tracingId" type="string">
      Internal tracking ID for the transaction
    </ResponseField>

    <ResponseField name="statusDetails" type="object">
      <Expandable>
        <ResponseField name="status" type="string">
          Current processing status of the payment
        </ResponseField>

        <ResponseField name="statusUpdateDate" type="string">
          Timestamp of the last status update
        </ResponseField>

        <ResponseField name="isoStatus" type="object">
          <Expandable>
            <ResponseField name="code" type="string">
              Standardized ISO payment status code
            </ResponseField>

            <ResponseField name="name" type="string">
              Human-readable description of the ISO status code
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="paidAmount" type="number">
      Amount paid in this specific transaction
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code for this transaction
    </ResponseField>

    <ResponseField name="BankName" type="string">
      Name of the customer's bank
    </ResponseField>

    <ResponseField name="bankAccountNo" type="string">
      Masked bank account number of the customer
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp when the transaction was initiated
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Timestamp of the last transaction update
    </ResponseField>

    <ResponseField name="totalRefundAmount" type="number">
      Total amount refunded for this transaction
    </ResponseField>

    <ResponseField name="taxAmount" type="number">
      Tax amount for this specific transaction
    </ResponseField>

    <ResponseField name="serviceAmount" type="number">
      Service fees for this specific transaction
    </ResponseField>

    <ResponseField name="tipAmount" type="number">
      Tip amount for this specific transaction
    </ResponseField>

    <ResponseField name="notes" type="string">
      Additional notes or comments on the transaction
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Only present when metadata was supplied on the payment. See [Process Payment](/api-reference/Payment/process-payment) for the field limits.
    </ResponseField>

    <ResponseField name="errorDescription" type="string">
      Detailed description of any errors that occurred
    </ResponseField>

    <ResponseField name="paymentDevice" type="object">
      Details about the device used for payment
    </ResponseField>

    <ResponseField name="splitBill" type="boolean">
      Indicates if this was part of a split bill payment
    </ResponseField>

    <ResponseField name="refundDetails" type="array">
      <Expandable>
        <ResponseField name="id" type="string">
          Unique identifier for this refund transaction
        </ResponseField>

        <ResponseField name="amount" type="number">
          Amount refunded in this transaction
        </ResponseField>

        <ResponseField name="status" type="string">
          Current status of the refund
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          Timestamp when the refund was initiated
        </ResponseField>

        <ResponseField name="updatedAt" type="string">
          Timestamp of the last refund status update
        </ResponseField>

        <ResponseField name="refundNotes" type="string">
          Reason or notes provided for the refund
        </ResponseField>

        <ResponseField name="refundType" type="string">
          Indicates whether refund is FULL or PARTIAL
        </ResponseField>

        <ResponseField name="currency" type="string">
          Currency code for the refund amount
        </ResponseField>

        <ResponseField name="refundId" type="string">
          Unique UUID assigned to this refund
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cardPaymentDetails" type="object">
      Card-specific details. **Only present for card transactions.** The `metadata.isMitPayment` field indicates whether this was a merchant-initiated [card-on-file](/api-reference/CardOnFile/introduction) payment.

      <Expandable>
        <ResponseField name="cardType" type="string">
          Card brand (e.g., `VISA`, `MASTERCARD`)
        </ResponseField>

        <ResponseField name="transactionSubType" type="string">
          Payment sub-type: `CARD`, `GOOGLE_PAY`, or `APPLE_PAY`
        </ResponseField>

        <ResponseField name="displayText" type="string">
          Masked card display text (e.g., "Visa \*\*\*\* 4242")
        </ResponseField>

        <ResponseField name="captureType" type="string">
          `AUTO_CAPTURE`, `MANUAL_CAPTURE`, or `CAPTURE_BEFORE_EXPIRY`
        </ResponseField>

        <ResponseField name="metadata" type="object">
          Card payment metadata. `isMitPayment: true` indicates this is a card-on-file (merchant-initiated) payment. Also includes authorization/capture timestamps.
        </ResponseField>

        <ResponseField name="paymentMethodId" type="string">
          The saved card/payment method ID used for this transaction
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```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": "[]"
  }
  ```
</ResponseExample>