Confirm payment

Path parameters

• paymentIdstringRequired

Headers

• TeststringOptional
  Sandbox scenario simulation: price_changed | sold_out | ambiguous | hold_expired | payment_declined | supplier_timeout | partial_search | duplicate_order (case-insensitive).Show more

  Sandbox scenario simulation: price_changed | sold_out | ambiguous | hold_expired | payment_declined | supplier_timeout | partial_search | duplicate_order (case-insensitive). Read on every travel verb before the permission wall and idempotency; a scenario sent on a verb it does not apply to has no effect. Every simulated error carries details.simulated true and details.scenario. price_changed (reprice, hold, orders) → 409 PRICE_CHANGED; sold_out → 422 SOLD_OUT; hold_expired (orders) → 409 HOLD_EXPIRED; duplicate_order (orders) → 409 DUPLICATE_ORDER existingOrderRef MO-SIM-DUPLICATE; payment_declined (orders, POST /v1/payments/{paymentId}/confirm) → 402 PAYMENT_FAILED; supplier_timeout → 502 UPSTREAM_UNAVAILABLE; partial_search (search) → two SUPPLIER_DROPPED warnings; ambiguous (orders) → 202 PENDING_RECONCILIATION on an MO-SIM- ref. wallet_insufficient → 402 PAYMENT_FAILED details.reason WALLET_INSUFFICIENT.
• 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 more

  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 is 409 IDEMPOTENCY_IN_PROGRESS.
• X-Actor-KindstringOptional
  The channel that initiated a money verb: ai marks an AI-initiated call, which must then carry X-Approval-Token.Show more

  The channel that initiated a money verb: ai marks an AI-initiated call, which must then carry X-Approval-Token. The header is accepted for compatibility and can only mark a call ai, never un-mark one. New routes (POST /v1/approvals, /v1/agent-proposals) do not take it.
• X-Approval-TokenstringOptional
  Redeemed by the payment verbs and by POST /v1/orders (orders.create), cancel (orders.cancel) and amend COMMIT (amend.commit).Show more

  Redeemed by the payment verbs and by POST /v1/orders (orders.create), cancel (orders.cancel) and amend COMMIT (amend.commit). Human sessions and system keys are exempt. Single use, ~2 min TTL, bound to tenant + action + resource + amount; any drift fails closed and burns the token.

Request bodyPaymentConfirmRequest

• threeDSTransactionRefNumberstringOptional
• pspTokenRefstringOptional
  Vaulted PSP token reference — never a PAN
• pixConfirmationstringOptional
• checkoutSignatureCheckoutSignatureOptional
  The signed triple a hosted checkout hands the browser.Show more

  The signed triple a hosted checkout hands the browser. The platform verifies it against ITS stored provider order id, then reads the provider — the triple is a hint, never the truth. Token references only; never instrument data.
  3 child attributes

  • providerOrderRefstringOptional
  • providerPaymentRefstringRequired
  • signaturestringRequired
    HMAC the provider computed; opaque to the client
• attemptIdstringOptional
  The attempt this confirm belongs to, when the client made several

Responses

• 200Confirmed; paymentRef returnedPaymentConfirmResponse
• 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
• 401
  UNAUTHENTICATED — missing or expired token.Show more

  UNAUTHENTICATED — 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
• 402
  PAYMENT_FAILED — PSP decline reason in details.Show more

  PAYMENT_FAILED — PSP decline reason in details. On POST /v1/orders with payment.mode WALLET also details.reason WALLET_INSUFFICIENT with details.required, the order total, and details.available, the wallet's available amount; nothing was sent to a supplier. With payment.mode SAVED_METHOD a declined saved method is details.reason CARD_DECLINED with details.declineCode and details.methodId; nothing was sent to a supplier.
  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 more

  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, 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 more

  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). Not retryable as sent.
  ApiErrorResponse
• 409
  CONFLICT | IDEMPOTENCY_CONFLICT | IDEMPOTENCY_IN_PROGRESS.Show more

  CONFLICT | IDEMPOTENCY_CONFLICT | IDEMPOTENCY_IN_PROGRESS. CONFLICT carries details.reason: PENDING_RECONCILIATION, PAYMENT_CANCELED, or CONCURRENT_UPDATE.
  ApiErrorResponse
• 413
  VALIDATION — the request body is larger than the surface's limit.Show more

  VALIDATION — 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 more

  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). 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 more

  VALIDATION — 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 more

  RATE_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 more

  NOT_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.