Get Checkout Session Status API (Draft)

Draft

This document describes a proposed API contract for Pay with Pyng. It is not final and may change before public release.

API is used by the partner to retrieve the authoritative status of a Checkout Session.

URL path - /checkout/{siteId}/session/{checkoutSessionId}/status

Method - GET

Request Headers

Header Name	Header Value	Notes
Content-Type	application/json
Authorization	Bearer access_token	Access token must have an appropriate scope to access resource

Path Parameters

Parameter Key	Parameter Data Type	Notes
siteId	string	Unique site id assigned to the partner's site
checkoutSessionId	string	Unique Checkout Session id

Response

Status Code - 200 OK

Parameter Key	Parameter Data Type	Required	Notes
data	object	Y	Checkout Session status
traceId	string	Y	Unique identifier of the request

Checkout Session Status Response

Parameter Key	Parameter Data Type	Required	Notes
checkoutSessionId	string	Y	Unique Checkout Session id
orderId	string	Y	Partner order identifier
siteId	string	Y	Partner site identifier
status	string	Y	Current coarse session status
outcome	string	N	Terminal outcome when available
paymentIntentId	string	N	Related payment intent id if available
transactionId	string	N	Related transaction id if available
expiresAt	string	Y	Session expiry timestamp
updatedAt	string	Y	Last update timestamp
failureReason	string	N	Partner-safe failure description

Status Values

• Created
• Launched
• Pending
• Completed
• Cancelled
• Expired
• Failed

Outcome Values

• Succeeded
• Cancelled
• Expired
• Failed

Notes

• Internal Pyng steps such as sign-in, agreement creation, or pending bank approval are abstracted behind coarse partner-visible statuses.
• Redirect return is UX only. This status API is authoritative.
• Expired indicates that the Hosted Checkout session timed out and is no longer active.
• After timeout, partners should treat the session as closed and create a new Checkout Session if the user needs to retry.