Payment Page — Query Status & Expire

This guide shows how to look up the current status of a payment page and how to expire it before the user makes the payment. It follows the same API response pattern as the rest of Breeze.

Recommended approach: Rely on webhooks for real-time state (event type: PAYMENT_SUCCEEDED, PAYMENT_EXPIRED) and use the read endpoints below when you need an immediate, on-demand check (e.g., rendering an admin screen).

Prerequisites

You’ve already created a payment page via POST /v1/payment_pages and received an id (e.g., page_abc123xyz) and the hosted URL.

1. Get Payment Page by ID

Use this if you already have the Breeze payment page id (e.g., from creation response or webhook payload).

curl -X GET 'https://api.breeze.cash/v1/payment_pages/page_abc123xyz' \
  -u "YOUR_API_KEY:" \
  --header 'Accept: application/json'

Field	Type	Description
id	string	Payment page unique identifier
currency	string	Currency code, e.g., `"USD"`
amount	number	Payment amount in minor units (e.g., cents)
lineItems	array	Array of purchased line items
├─ name	string	Name of the item
├─ currency	string	Currency for the item
├─ amount	number	Amount for the item in minor units
├─ price	number	Price per item
├─ quantity	number	Quantity of the item
├─ description	string	Description of the item
└─ images	string[]	Array of image URLs
clientReferenceId	string	Reference to merchant's original client order
successReturnUrl	string	URL customer gets redirected to on success
failReturnUrl	string	URL customer gets redirected to on failure
createdAt	number	Timestamp (ms since epoch)
url	string	Hosted payment page URL
status	string	Payment page status`PAID` `UNPAID` `EXPIRED`
transactionAmount	number	The amount transacted (in minor units)
billingEmail	string	Email address associated with the billing
paymentType	string	Payment method type, e.g., `"card"`
customer	object	Customer metadata
├─ id	string	Customer ID
├─ referenceId	string	Reference for customer
└─ email	string	Customer email address
payinDetails	object	Details of the payment method used, only populated if the payment status is `PAID`
├─ amount	number	Paid amount (minor units)
├─ currency	string	Paid currency
├─ scheme	string	Card scheme: Visa \| Mastercard \| American Express
├─ last4	string	Last four of card number
├─ taxAmount	number	Tax collected (minor units), for example if the `taxAmount` is 60, it indicates a tax of $0.60 was collected from the customer
├─ type	string	Payin type, e.g., `"card"`
├─ cardType	string	Card type: CREDIT \| DEBIT \| PREPAID
├─ bin	string	Bank identification number (first 6 of card)
└─ issuer	string	Issuing bank name

Successful response

{
    "status": "SUCCEEDED",
    "data": {
        "id": "page_xxxxxxxxxxxxxxxx",
        "currency": "USD",
        "amount": 1000,
        "lineItems": [
            {
                "name": "item-name",
                "currency": "CUR",
                "amount": 1000,
                "price": 1000,
                "quantity": 1,
                "description": "item description",
                "images": [
                    "https://example.com/image.png"
                ]
            }
        ],
        "clientReferenceId": "order-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "successReturnUrl": "https://example.com/success",
        "failReturnUrl": "https://example.com/fail",
        "createdAt": 1234567890123,
        "url": "https://pay.example.com/page_xxxxxxxxxxxxxxxx/token_xxxxxxxxxxxxxxxx",
        "status": "PAID",
        "transactionAmount": 1000,
        "billingEmail": "[email protected]",
        "isRecurring": false,
        "paymentType": "card",
        "customer": {
            "id": "cus_xxxxxxxxxxxxxxxx",
            "referenceId": "ref_xxxxxxxxxxxx",
            "email": "[email protected]"
        },
        "payinDetails": {
            "amount": 1000,
            "currency": "CUR",
            "scheme": "VISA",
            "last4": "1234",
            "taxAmount": 0,
            "type": "card",
            "cardType": "CREDIT",
            "bin": "123456",
            "issuer": "Bank Name"
        }
    }
}

2. Expire a payment page

Use this to explicitly expire a payment page before the user makes the payment. After a successful expire, subsequent webhook(s) will also reflect PAYMENT_EXPIRED.

Breeze will reject the expire request if the user has already made the payment.

curl -X POST 'https://api.breeze.cash/v1/payment_pages/page_abc123xyz/expire' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json'

Successful response

{
  "status": "SUCCEEDED",
  "data": {
    "id": "page_abc123xyz",
    "status": "EXPIRED",
    "clientReferenceId": "order-<your-unique-id>",
    ...
  }
}

Error responses

{  
  "status": "FAILED",  
  "errorCode": "WRONG_PARAMETER",
  "errorMessage": "<more-detailed-error-message>"
}