Skip to content
ApiqDevelopers
API v1.64.0Open console
API referencepayments

Create checkout session

POST/v1/payments/{paymentId}/checkout-session
Idempotency-Key requiredAccepts X-Api-Key · oauthClientCredentials · bearer

Open a hosted checkout for an intent; the caller never handles card data

Mints a single-use hosted checkout session for an existing intent and answers the URL to open in the system browser.Show moreMints a single-use hosted checkout session for an existing intent and answers the URL to open in the system browser. The hosted page collects the payment at the provider and confirms the intent there, so neither the calling app nor this platform ever sees a PAN. Only an intent in CREATED or REQUIRES_ACTION can get a session; any other state is 409 CONFLICT. An intent has at most ONE active session: a new session (a new Idempotency-Key) voids the previous one, and a confirm of the intent by any other route voids it too. When the hosted page finishes it redirects to returnUrl with `paymentId` and `status` query parameters; `status` is advisory, and the caller re-reads the intent (GET /v1/payments/{paymentId}) before acting on it. payment.captured and payment.failed fire as for any intent. Idempotency-Key is REQUIRED: the same key and body within 48h replay the original answer (Idempotency-Replayed true) — including its expiresAt, so a replayed session may already be expired or spent; create a new one with a new key. Permission is that of a NEW payment: payments:write plus the tenant's standing, so a SUSPENDED tenant is refused TENANT_SUSPENDED and, on the production deployment, a tenant whose activation is not approved is refused PERMISSION_DENIED TENANT_NOT_LIVE (403, as on intent create). A deployment with no payment provider (provider=none) answers 501 NOT_IMPLEMENTED; a provider that has no hosted checkout, or the harness provider above DEV, answers 501 NOT_IMPLEMENTED with details.reason HOSTED_CHECKOUT_UNSUPPORTED. The harness provider's hosted page is DEV-only and is not an operation of this contract.

Path parameters

  • paymentIdstringRequired
    The paymentId returned by POST /v1/payments/intent

Headers

  • Idempotency-KeystringRequired
    Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show moreMandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.

Request bodyCheckoutSessionRequest

  • returnUrlstringOptional
    Where the hosted page sends the browser when it finishes, with `paymentId` and `status` query parameters appended.Show moreWhere the hosted page sends the browser when it finishes, with `paymentId` and `status` query parameters appended. Anything else — http, another scheme, another origin, userinfo, a relative or malformed URL — is 400 VALIDATION with details.reason RETURN_URL_NOT_ALLOWED; never an open redirect. Absent = the hosted page ends on its own result screen.

Responses

  • 200The hosted checkout session; open url in the system browserCheckoutSession
  • 400
    VALIDATION. details.reason RETURN_URL_NOT_ALLOWED when returnUrl is not an aikonic:// URL and not an https URL on a configured origin (details.field returnUrl); a missing Idempotency-Key is VALIDATION…Show moreVALIDATION. details.reason RETURN_URL_NOT_ALLOWED when returnUrl is not an aikonic:// URL and not an https URL on a configured origin (details.field returnUrl); a missing Idempotency-Key is VALIDATION with details.header Idempotency-Key.
    ApiErrorResponse
  • 401
    UNAUTHENTICATED — missing or expired token.Show moreUNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
    ApiErrorResponse
  • 403
    PERMISSION_DENIED | TAB_DISABLED | OUT_OF_SCOPE | TENANT_MISMATCH, exactly as Forbidden, plus TENANT_SUSPENDED — declared on the verbs that start new business: search and poll, detail, schedules,…Show morePERMISSION_DENIED | TAB_DISABLED | OUT_OF_SCOPE | TENANT_MISMATCH, exactly as Forbidden, plus TENANT_SUSPENDED — declared on the verbs that start new business: search and poll, detail, schedules, seatmap, ancillaries, rules, reprice, hold and order create, and on the payments routes (intent, confirm, 3ds-callback, checkout-session). While the caller's tenant is SUSPENDED every such request is refused TENANT_SUSPENDED, except an idempotent replay of an answer completed before the suspension (see hold / createOrder), before the entitlement and permission checks, and it is not retryable: the answer changes only when platform ops reinstates the tenant. The post-booking verbs (cancel-quote, cancel, amend), the order reads, and capture and refund on an existing payment intent (whose 403 is PaymentForbidden) stay up, so no traveller is stranded. On the production deployment the same requests are refused PERMISSION_DENIED with details.reason TENANT_NOT_LIVE while the tenant's production activation has not been approved, whichever credential is presented, console session or API key; use the sandbox deployment until activation. Not retryable; the post-booking verbs stay up.
    ApiErrorResponse
  • 404NOT_FOUND — no such payment intent for this tenantApiErrorResponse
  • 405
    VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show moreVALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
    ApiErrorResponse
  • 409
    CONFLICT | IDEMPOTENCY_CONFLICT | IDEMPOTENCY_IN_PROGRESS.Show moreCONFLICT | IDEMPOTENCY_CONFLICT | IDEMPOTENCY_IN_PROGRESS. CONFLICT carries details.reason: INVALID_STATE (the intent is not CREATED or REQUIRES_ACTION — details.state names its state: already paid, failed or canceled) or PENDING_RECONCILIATION.
    ApiErrorResponse
  • 413
    VALIDATION — the request body is larger than the surface's limit.Show moreVALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
    ApiErrorResponse
  • 414
    VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show moreVALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
    ApiErrorResponse
  • 415
    VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show moreVALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
    ApiErrorResponse
  • 429
    RATE_LIMITED — the API key or its tenant is over a rate limit; wait for Retry-After, then retry.Show moreRATE_LIMITED — the API key or its tenant is over a rate limit; wait for Retry-After, then retry. Every routed request is counted against two token buckets, the key's and the tenant's (all its keys together): 50 requests a second with a burst of 100 on the standard plan. Every travel verb except polling a search also spends from a supplier budget, per key and per tenant: 10 requests a second with a burst of 20, and a plan may add a daily quota of supplier calls. Answers carry the IETF RateLimit header fields for the tightest bucket consulted (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy); a refusal adds Retry-After and details.scope (KEY or TENANT), details.budget (PLATFORM or SUPPLIER), details.reason (RATE or DAILY_QUOTA), details.tier and details.retryAfterMs. A sandbox may run with the limiter off, in which case none of these headers is sent. A search that is still warming is a different answer with a different meaning (keep polling). with the key-velocity check on, also details.reason VELOCITY_LIMIT, a soft breach of the API key's own scope (components/responses/VelocityLimited), nextAction slow_down.
    ApiErrorResponse
  • 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
  • 501
    NOT_IMPLEMENTED — this deployment serves no payments: no payment provider is configured (provider=none), so every payment route answers 501.Show moreNOT_IMPLEMENTED — this deployment serves no payments: no payment provider is configured (provider=none), so every payment route answers 501. Not a capabilities-doc bug: payments are deployment configuration.
    ApiErrorResponse
  • 502Also the order read routes (getOrder, listOrderDocuments, listOrderEvents, searchOrders) when the order store times out: details.store names the store, retryable true.ApiErrorResponse
  • 503ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.

400VALIDATION
returnUrl must be an aikonic:// URL or an https URL on an origin this deployment allows.
not retryable
401UNAUTHENTICATED
The bearer token is expired. Re-authenticate and retry.
not retryable
403PERMISSION_DENIED
Role lacks the required scope: booking:write
not retryable
403TAB_DISABLED
Tenant acme-travel is not entitled to sell CRU
not retryable
403OUT_OF_SCOPE
The token's scope ladder does not reach this customer subtree
not retryable
403TENANT_MISMATCH
orderRef MO-8KD-2FQ-9XT does not belong to tenant acme-travel
not retryable
403TENANT_SUSPENDED
This tenant is suspended: new searches, quotes, holds, orders and payments are refused until it is reinstated. Existing orders can still be read, cancelled and amended.
not retryable
404NOT_FOUND
No such payment intent.
not retryable
405VALIDATION
This method is not served.
not retryable
409CONFLICT
This payment is not in a state that can be paid through a hosted checkout.
not retryable
409IDEMPOTENCY_CONFLICT
Idempotency-Key 7f0c33d1-9a1e-4d2c-9f77-1c0f2b3a4d55 was used with a different body; never executed
not retryable
409IDEMPOTENCY_IN_PROGRESS
A request with this Idempotency-Key is still in flight. Retry shortly.
retryable
413VALIDATION
The request body is larger than this API accepts (262144 bytes).
not retryable
414VALIDATION
The request URI is longer than 8 KiB.
not retryable
415VALIDATION
Send application/json.
not retryable
429RATE_LIMITED
Too many requests for this key on the supplier budget. Wait for the Retry-After interval before trying again.
retryable
500INTERNAL
An unexpected error occurred. Quote the traceId to support.
retryable
501NOT_IMPLEMENTED
This deployment serves no payments: no payment provider is configured.
not retryable
502UPSTREAM_UNAVAILABLE
Every supplier for HTL is circuit-open; no fan-out was attempted
retryable
503PROVIDER_DOWN
EXAMPLEHOTELS is unavailable; the order was not attempted and nothing was captured
retryable