---
updatedAt: 2026-02-26T12:55:26.000Z
agentTools:
  projectIndex: https://developer.peachpayments.com/llms.txt
---

# Query a payment status

# Overview

After creating a payment link, you can query the status of the payment transaction. The query transaction status object takes the `paymentId` and the bearer token and returns the payment details and status.

Querying the payment can return one of the following statuses:

| Webhook event | Description                                      |
| :------------ | :----------------------------------------------- |
| `initiated`   | Triggered when you create the payment link.      |
| `processing`  | Triggered when a customer attempts the payment.  |
| `completed`   | Triggered when a customer completes the payment. |
| `cancelled`   | Triggered when a customer cancels the payment.   |
| `expired`     | Triggered when the payment link expires.         |

# Flow

To learn more about the required and optional parameters, see the [API reference](https://developer.peachpayments.com/reference/get_api-payments-paymentid-1) section.

The query payment status flow works as follows:

<Image align="center" alt="Query payment status flow." border={false} caption="Query payment status flow." src="https://files.readme.io/93e6a37-pl-status-flow.svg" />

1. The merchant queries the payment status by making a request to the `/api/payments/{paymentId}` endpoint.
2. The Payment Links API responds with the payment status.

# Sample requests and responses

For sample requests and responses, see the [interactive API playground](https://developer.peachpayments.com/reference/get_api-payments-paymentid-1) or use the Peach Payments Postman collection:

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/13324425-f24f369c-3e73-4bc1-964f-5c39862aeb26?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D13324425-f24f369c-3e73-4bc1-964f-5c39862aeb26%26entityType%3Dcollection%26workspaceId%3D395353be-fe74-499e-9ef1-fc3433748710#?env%5BPayment-Links-Public%5D=W3sia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly9saW5rcy5wZWFjaHBheW1lbnRzLmNvbSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXV0aFVybCIsInZhbHVlIjoiaHR0cHM6Ly9kYXNoYm9hcmQucGVhY2hwYXltZW50cy5jb20iLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoiZGVmYXVsdCJ9LHsia2V5IjoibWVyY2hhbnRJZCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQifSx7ImtleSI6ImVudGl0eUlkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Im5vdGlmaWNhdGlvblVybCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQifSx7ImtleSI6ImNsaWVudElkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoic2VjcmV0In0seyJrZXkiOiJjbGllbnRTZWNyZXQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQifSx7ImtleSI6ImFjY2Vzc1Rva2VuIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoic2VjcmV0In0seyJrZXkiOiJsZWdhY3lfYXBpVXNlcklkIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoic2VjcmV0In0seyJrZXkiOiJsZWdhY3lfYXBpUGFzc3dvcmQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWUsInR5cGUiOiJzZWNyZXQifV0=)