Retrieve a checkout session

Its status (`open`, `completed`, `expired`) and the payment behind it. A payment still waiting is verified with the provider before this answers.

Use with AI

Download Claude instructions Download Codex instructions All AI integration resources

Markdown

GEThttps://api.veyqo.org/api/v1/checkout/sessions/{id}Integration guide

Use your sandbox environment to start. Understand error codes and payment statuses before handling a live payment.

Retrieve a checkout session

curl --request GET "https://api.veyqo.org/api/v1/checkout/sessions/$CHECKOUT_SESSION_ID" \
  --header "Authorization: Bearer $VEYQO_SECRET_KEY" \
  --header "Accept: application/json"

{
  "success": true,
  "data": {
    "id": "cs_01M6EB66SC61Q3RQYAN0693DGM",
    "object": "checkout_session",
    "url": "https://veyqo.org/pay/cs_01M6EB66SC61Q3RQYAN0693DGM",
    "status": "open",
    "source": "api",
    "provider": "paystack",
    "amount": 50000,
    "currency": "NGN",
    "reference": "ORDER-1001",
    "description": "Order 1001",
    "customer_email": "customer@example.com",
    "payment": null,
    "success_url": "https://shop.example.com/thanks",
    "cancel_url": "https://shop.example.com/cart",
    "expires_at": "2026-11-02T13:00:00+00:00",
    "completed_at": null,
    "created_at": "2026-11-02T12:00:00+00:00"
  }
}

Illustrative examples. Replace IDs and environment variables with your own values. Keep secret keys on your server.

Headers

Authorizationstringrequired: Bearer <secret-key>. This key determines your project environment and must stay on your server.
Acceptstringoptional: application/json

Endpoint

GET https://api.veyqo.org/api/v1/checkout/sessions/{id}

Server secret key required. Scope: payments:read. The key determines the project and environment; no project-selection header is accepted.

Path and query parameters

Parameter	Location	Required	Description
id	path	Yes	Use the ID returned when this resource was created.

Response fields

idstringrequired: Checkout session ID (cs_ prefix).
object"checkout_session"required: See the JSON example.
urlstringrequired: Hosted Veyqo URL; redirect here or open this session using VeyqoCheckout. Format: uri.
statusstringrequired: Values: open, completed, expired.
sourcestringrequired: Values: api, browser, link.
providerstringrequired: Selected provider slug; this field is an object on the browser session detail endpoint.
amountintegerrequired: Server-defined amount in minor units.
currencystringrequired: Three-letter currency.
referencestring | nullrequired: Your order reference, when supplied.
descriptionstring | nullrequired: Checkout description.
customer_emailstring | nullrequired: Customer email if already supplied.
paymentobject | nullrequired: Current payment attempt, if any. A session can have multiple attempts over time.
success_urlstring | nullrequired: Configured return URL. A redirect is not proof of payment.
cancel_urlstring | nullrequired: Configured cancellation URL.
expires_atstringrequired: Session expiry time. Format: date-time.
completed_atstring | nullrequired: ISO 8601 timestamp. Format: date-time.
created_atstring | nullrequired: ISO 8601 timestamp. Format: date-time.

Errors and recovery

Code	HTTP	Recovery	Retry policy
INVALID_API_KEY	401	Use a current kc_test_ or kc_live_ secret key on /api/v1. Use a pk_test_ or pk_live_ publishable key only on browser checkout.	After fixing credentials.
INSUFFICIENT_PERMISSION	403	Grant the required scope or use a suitably scoped key. Dashboard organization roles and staff permissions are separate.	After permission changes.
RATE_LIMIT_EXCEEDED	429	Honor Retry-After, use bounded exponential backoff with jitter, and reduce concurrent requests. Read X-RateLimit headers.	Yes, after Retry-After; preserve write idempotency.
METHOD_NOT_ALLOWED	405	Use the method documented for the endpoint, such as POST for verification and refunds.	After fixing the method.
INTERNAL_ERROR	500	Record X-Request-Id, timestamp and sanitized request context. Reconcile unknown payment outcomes before retrying a write; contact support if it persists.	Safe reads: bounded backoff. Writes: reconcile first.
RESOURCE_NOT_FOUND	404	Check the ID, project and environment. Do not guess another project’s IDs. An inactive payment link is also not-found.	No blind retry.
PROVIDER_UNAVAILABLE	503	Check the existing payment and verify its state before starting another attempt. Retry safe reads with backoff; preserve operation identity for retried writes.	Conditional: reconcile unknown outcomes first.

Complete error catalogue

Every Veyqo error code, including which surface emits it and how to recover.