---
title: "Query payment status"
method: GET
path: "/api/payments/{paymentId}"
tags: ["Status"]
---

# Query payment status

`GET /api/payments/{paymentId}`

Query the status of a payment.

For more information, see the [documentation](https://developer.peachpayments.com/docs/query-payment).

## Path parameters

- `paymentId` string, required

## Response `200`

OK.

- object
  - `payment` QueryStatusResponse
    - `id` string — Payment ID.
    - `payment` object
      - `linkId` string — Payment link ID.
      - `linkUrl` string — Payment link URL.
      - `amount` number — Payment amount.
      - `status` 'initiated' | 'processing' | 'expired' | 'cancelled' | 'completed' — Payment link status.
      - `currency` 'ZAR' | 'KES' | 'USD' — Currency code for the payment.
      - `merchantInvoiceId` string — Payment order number provided by merchant.
      - `entityId` string — Merchant channel ID that the payment link was created in.
      - `notes` string — A note to include with the payment link.
      - `expiryTime` string — Timestamp when the payment link expires.
      - `batchId` string — Batch ID for the payment link.
    - `source` 'API' | 'Xero' | 'UI' — Source of the payment link.
    - `createdAt` string — Timestamp when the payment link was created.
    - `updatedAt` string — Timestamp when the payment link was last modified.
    - `customer` Customer — Optional object sent if customer data is required.
      - `email` string, email — The customer's email address.
      - `fax` string — The customer's fax number, if provided.
      - `givenName` string — The customer's first name or given name. Peach Payments recommends including the name so that it displays in the Peach Dashboard and is available for subsequent queries.
      - `surname` string — The customer's last name or surname. Peach Payments recommends including the surname so that it displays in the Peach Dashboard and is available for subsequent queries.
      - `mobile` string — The customer's mobile phone number.
      - `phone` string — The customer's phone number.
      - `ip` string — The customer's IP address.
      - `merchantCustomerLanguage` string — The language used for the customer on the merchant's site.
      - `status` string — Used to determine if this is a new or returning customer.
      - `merchantCustomerId` string — The customer's ID on the merchant's site.
      - `taxId` string — The customer's tax ID, if required.
      - `taxType` string — The customer's tax type, if required.
      - `birthDate` string — The customer's birth date.
      - `browser` object — The customer's browser details.
        - `acceptHeader` string — The value of the accept header sent from the customer's browser.
        - `language` string — The value representing the browser language as defined in IETF BCP47.
        - `screenHeight` string — The total height of the customer's screen in pixels.
        - `screenWidth` string — The total width of the customer's screen in pixels.
        - `timezone` string — The time-zone offset in minutes between UTC and the local time of the customer's browser.
        - `userAgent` string — The exact content of the HTTP user-agent header.
        - `javaEnabled` string — The boolean that represents the ability of the customer's browser to execute Java.
        - `javascriptEnabled` string — The boolean that represents the ability of the customer's browser to execute JavaScript.
        - `screenColorDepth` string — The value representing the bit depth of the colour palette for displaying images in bits per pixel.
        - `challengeWindow` string — The dimensions of the challenge window that has been displayed to the customer.
    - `options` PaymentResponseOptions
      - `sendEmail` boolean — Indicates whether to send an email to the customer after creating the payment link.
      - `sendSms` boolean — Indicates whether to send an SMS to the customer after creating the payment link.
      - `sendWhatsapp` boolean — Indicates whether to send a WhatsApp message to the customer after creating the payment link.
      - `emailCc` string, nullable — List of comma-separated email addresses to CC.
      - `emailBcc` string, nullable — List of comma-separated email addresses to BCC.
      - `notificationUrl` string — Peach Payments sends a webhook to this URL for any changes to this payment, overriding your default webhook.
    - `checkout` CheckoutState — The checkout object contains the default payment method and whether to tokenise the card number.
      - `defaultPaymentMethod` string, nullable — The default payment method to show when Checkout loads.
      - `forceDefaultMethod` boolean, nullable — Force the default payment method to be the only payment method.
      - `tokeniseCard` boolean — Tokenise the card number to allow it to be stored. You must get permission from your customer before tokenising their cards.
      - `paymentType` 'DB' | 'PA', nullable — The payment type for the request. Does not accept `RG`, but you can tokenise a card by performing a DB or PA with `tokeniseCard`. PA is only supported when `forceDefaultMethod` is set to `true` and `defaultPaymentMethod` is `CARD`. Following a PA, you can either [capture](https://developer.peachpayments.com/docs/card-manage-payments#capture-a-preauthorisation) or [reverse](https://developer.peachpayments.com/docs/card-manage-payments#reverse-a-preauthorisation) the PA. Refund transactions through the Dashboard or as described in the [documentation](https://developer.peachpayments.com/docs/checkout-refund).
      - `registrationId` string — Registration ID added if tokeniseCard is true on card payment.
      - `checkoutId` string — Checkout ID of payment.
      - `transactionUniqueId` string — Unique transaction ID of payment.
      - `resultCode` string — Result code returned for payment.
      - `paymentBrand` string — Payment brand used for payment.
    - `termsOfService` object
      - `id` string — The id of the terms of service that was agreed to.
      - `accepted` boolean — Whether the user agreed to the terms of service.
  - `audit` object[]
    - `oldStatus` 'none' | 'initiated' | 'processing' | 'expired' | 'cancelled' | 'completed' — The previous status of the payment link.
    - `newStatus` 'initiated' | 'processing' | 'expired' | 'cancelled' | 'completed' — The new status of the payment link.
    - `timestamp` string, yyyy-MM-ddTHH:mm:ssZ — The UTC time that the status changed.

## Other responses

- `401` — Request lacks valid authentication.
- `404` — The specified resource was not found.

---

[API](https://skmtc.net/peachpayments/apis/checkout.md) · [All operations](https://skmtc.net/peachpayments/apis/checkout/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/peachpayments/checkout/revisions/3a98165665f8/schema)