Get payment status

Fetches payment status by string payment_details_id code.

Using Checkout Builder

After you send a payment request from the Checkout Builder, use the returned payment_details.id string as payment_details_id with:

GET /payments/status?version=2024-10-01&api_key=<your_api_key>&payment_details_id=<payment_details_id>

Endpoint

GET /payments/status

Query Parameters

• version (string, required) - API contract version. Use exactly 2024-10-01.
• diagnostics (boolean, optional) - Non-production docs only. Set true to include extra diagnostic metadata (for example observed_client_ip).
• api_key (string, required)
• payment_details_id (string, required)

Header Parameters

• PW-subscription-key (string, required)
• PW-origin-country (string, required)
• PW-request-date (string, required) - UTC request timestamp formatted as YYYY-MM-DD HH:mm:ss.
• PW-ip-address (string, required)
• User-Agent (string, required)

Header Constraints

Key	Description	Example	Data type	Requirement	Field Length
PW-subscription-key	Developer key available after portal registration. Production key is shared on request.	eed0d85c530c4b26a91d09b783d8fab3	string	mandatory	32
PW-origin-country	ISO Alpha-2 country code where the transaction is created.	TT	string	mandatory	2
PW-request-date	Current request timestamp. Format: YYYY-MM-DD HH:mm:ss (UTC).	2014-10-08 16:01:31	string	mandatory	19
PW-ip-address	Fixed institution IP used for PayWise network-level validation.	255.255.255.255	string	conditional	8-16
User-Agent	In programmable environments, this avoids running into Cloudflare issues.	Mozilla/5.0 (Windows NT 10.0; Win64; x64)	string	mandatory	255

Request Body

No JSON request body.

Downloads

• Download Postman-ready response (200)

Callback and Notify Payloads

GET /payments/status returns the same request-level transaction snapshot shape used by the frozen completed and cancelled callback fixtures.

The current contract evidence distinguishes these surfaces:

• Status lookup: synchronous polling by payment_details_id
• Callback: request-level snapshot with fields such as status, payments_status, fees, timestamps, payers, and payees
• Notify: lighter event payloads with event_type, transaction_id, status, timestamp, and either a payer or payee object

Example notify event:

{
  "event_type": "payment_completed",
  "transaction_id": "merchant-order-w9J2m",
  "status": "PAID",
  "payer": {
    "mobile_number": "+1XXXXXXXXXX",
    "amount": 25,
    "payment_method": "wallet",
    "currency": "TTD"
  },
  "timestamp": "2026-08-01T14:05:30Z",
  "description": "Payer[x] has paid"
}

Example initiation notify event:

{
  "event_type": "payment_initiated",
  "transaction_id": "merchant-order-a8Q3x",
  "status": "INITIATED",
  "payer": {
    "name": "John Doe",
    "mobile_number": "+1XXXXXXXXXX",
    "amount": 25,
    "currency": "TTD"
  },
  "timestamp": "2026-08-01T14:00:00Z",
  "description": "Payment links issued to a Payer[x]"
}

Treat notify as event delivery and /payments/status as the source of truth for the latest normalized request state.

Responses

200 - Wrapper-normalized response envelope (success cases).

Example: success

{
  "status": "success",
  "code": 200,
  "message": "Payment status fetched successfully",
  "request_id": "03cc465a-1bdd-4548-838c-562c6bc8b67f",
  "timestamp": "2026-02-11T03:59:45.617Z",
  "transaction_request": {
    "id": "checkout_demo_20260326_0001",
    "status": "succeeded"
  },
  "payment_details": {
    "id": "paydet_demo_20260326_0001",
    "status": "paid",
    "currency": "TTD",
    "amount": "25.00"
  },
  "payers": [
    {
      "mobile_number": "+1XXXXXXXXXX",
      "payment_channel": "payment_link",
      "payment_method": "card",
      "status": "paid"
    }
  ],
  "observed_client_ip": {
    "request_ip": "172.64.80.1",
    "socket_remote_address": "172.64.80.1"
  }
}

Notes

This endpoint page is generated from openapi/pw-wrappers.2024-10-01.yaml.