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'

Successful response

{
  "status": "SUCCEEDED",
  "data": {
    "id": "page_abc123xyz",
    "status": "PAID",
    "clientReferenceId": "order-<your-unique-id>",
    "customer": {
      "id": "cus_abc123xyz",
      "referenceId": "<your-customer-id>",
      "email": "[email protected]"
    },
    "payinDetails": {
      "amount": 100,
      "currency": "USD",
      "type": "CARD",
      "scheme": "AMEX",
      "last4": "0602",
      "cardType": "CREDIT",
      "bin": "377910",
      "issuer": "DBS BANK LTD"
    },
    ...
  }
}

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