Skip to content

Get Checkout Session Status API

Used by the partner to retrieve the authoritative status of a Checkout Session.

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

Method - GET

When to call

Call this endpoint after Pyng redirects the customer back to returnTarget.url. The redirect is the signal that the customer's interaction with Hosted Checkout has ended; this endpoint then provides the authoritative outcome.

If the response is non-terminal (Pending or InProgress), retry after a short delay; the final state typically settles within seconds of the redirect. Stop on any terminal status (Settled, Declined, Expired) and stop at expiresAt.

Do not call this endpoint before the redirect.

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 The Checkout Session id that was queried
transactionStatus string Y Current payment status of the Checkout Session (see below)
transactionId string N Payment reference, present once payment processing has started
transactionUpdated number N Last status change, epoch milliseconds
orderId string N Partner order identifier supplied at session creation
amountPaid number N Amount in cents
transactionStatusDescription string N Human-readable failure description, present when Declined
metadata object (string values) N The flat string key/value metadata supplied at session creation, echoed verbatim. Omitted when none was supplied.

Optional fields are omitted from the response when not available.

Status Values

  • Pending — payment has not started yet
  • InProgress — payment has started and is being processed
  • Settled — payment completed successfully
  • Declined — payment was unsuccessful (rejected, failed, returned, or cancelled)
  • Expired — the session's payment window lapsed before payment completed

Error Responses

Status Code Meaning
401 Missing or invalid access token
403 Bearer token is not authorised for siteId
404 Not Found The Checkout Session was not found for the supplied siteId

Notes

  • This status API is authoritative. Redirect return is UX only and must not be treated as confirmation.
  • A 404 means the Checkout Session was not found for the supplied siteId.
  • Expired is terminal: the session is no longer payable. Partners should treat it as closed and create a new Checkout Session if the user needs to retry.