Create a checkout
POST/checkouts
Creates a durable checkout managed by the service. The returned launch URL hides whether the configured payment provider uses a redirect or a browser SDK. The durable Checkout ID is passed to the provider for correlation; provider webhooks remain authoritative for payment and subscription results. A subscription Checkout must contain prices from exactly one Subscription Group, currency, recurrence interval, and recurrence count. The service validates that composition before Customer lookup or provider I/O. A zero-due Checkout is supported; this contract does not author a provider trial policy.
Request
Responses
- 201
- 400
- 401
- 403
- 409
- 422
- 429
- 500
Created
Response Headers
Checkout resource URL
Bad Request
Unauthorized
Forbidden (realm/account mismatch, billing account not derived from your session/principal, or insufficient role)
Conflict (idempotency body mismatch, duplicate adjustment, or an unsupported provider capability). Unsupported mutations return BILLING.PAYMENT_PROVIDER_CAPABILITY_UNSUPPORTED before Customer creation, provider I/O, or local state mutation. Concurrent use of the same Idempotency-Key returns WRITE.IDEMPOTENCY_IN_PROGRESS; different keys are independent requests whose final ordering is owned by the PSP. A subscription Checkout with mixed group, currency, or recurrence facts is rejected before Customer lookup or provider I/O. Missing or inconsistent selected Customer bindings return BILLING.PAYMENT_PROVIDER_CUSTOMER_REQUIRED or BILLING.PAYMENT_PROVIDER_CUSTOMER_CONFLICT without silently replacing the binding.
Unprocessable Entity (validation, visibility, or binding/meter unresolved)
Rate limited
Response Headers
Seconds to wait before retry.
Internal Server Error