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). See 📄 API Reference — Get a payment page.

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
└─ threeDS	object	Details of the 3DS authentication
├─ requested	boolean	Indicates if 3DS was requested
├─ flow	string	"CHALLENGE" or "FRICTIONLESS"
├─ authenticationStatusCode	string	EMVCo character code for the authentication status, values include "Y", "N", "U", "A", "C", "D", "R", "I"
└─ eci	string	Electronic Commerce Indicator (ECI) value that indicate the authentication level and liability shift

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",
            "threeDS": {
                "requested": true,
                "authenticationStatusCode": "Y",
                "flow": "CHALLENGE",
                "eci": "05"
            }
        }
    }
}

Note: payinDetails is only present for card and Apple Pay payments. For crypto payments, use the fields below instead.

Field	Type	Description
network	string	Blockchain network: `POLYGON`, `ETHEREUM`, `SOLANA`, `ARBITRUM`, `OPTIMISM`
token	string	Crypto token: `USDC`, `ETH`, `SOL`, `DAI`
walletAddress	string	Customer's wallet address
walletType	string	Wallet client used: `metamask`, `walletconnect`
transactionHash	string	Blockchain transaction hash
tokenAmount	string	Amount in token units (e.g. `"10.00"`)

Successful response (crypto — USDC on Polygon)

{
    "status": "SUCCEEDED",
    "data": {
        "id": "page_abc123xyz",
        "currency": "USD",
        "amount": 1000,
        "lineItems": [
            {
                "name": "item-name",
                "currency": "USD",
                "amount": 1000,
                "price": 1000,
                "quantity": 1,
                "description": "item description",
                "images": [
                    "https://example.com/image.png"
                ]
            }
        ],
        "clientReferenceId": "order-001",
        "successReturnUrl": "https://example.com/success",
        "failReturnUrl": "https://example.com/fail",
        "createdAt": 1234567890123,
        "url": "https://pay.breeze.cash/page_abc123xyz/pcs_abc123xyz",
        "status": "PAID",
        "transactionAmount": 1000,
        "billingEmail": "[email protected]",
        "isRecurring": false,
        "paymentType": "evm_wallet_payment",
        "network": "POLYGON",
        "token": "USDC",
        "walletAddress": "0x676dB5B2585466479298f5Bf56D58699B45D563D",
        "walletType": "metamask",
        "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "tokenAmount": "10.00",
        "customer": {
            "id": "cus_abc123xyz",
            "referenceId": "ref_abc123xyz",
            "email": "[email protected]"
        }
    }
}

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>"
}

List all payment pages

Use this to fetch a paginated list of payment pages, for example when building a dashboard or running reconciliation.

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

Query parameters

Parameter	Type	Description
limit	integer	Number of payment pages to return (1–100, default 100)
offset	integer	Number of payment pages to skip (min 0, default 0)
status	string	Filter by status: `UNPAID` \| `PAID` \| `EXPIRED` \| `CANCELED`

Each object in data follows the same schema as Get Payment Page by ID above.

Field	Type	Description
data	array	Array of payment page objects
hasMore	boolean	`true` if there are more results beyond this page

Successful response

{
  "status": "SUCCEEDED",
  "data": [
    {
      "id": "page_abc123xyz",
      "status": "PAID",
      ...
    }
  ],
  "hasMore": false
}

Error codes — For a complete list of errors returned by the payin endpoints, see the Error Reference.

Webhooks — For payload examples and event sequences fired during payment flows (PAYMENT_CREATED, PAYMENT_SUCCEEDED, PAYMENT_EXPIRED, PAYMENT_ATTEMPT_FAILED), see the Webhook Event Reference.