> ## Documentation Index > Fetch the complete documentation index at: https://docs.payra.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a checkout session > Creates a hosted payment page for one order and answers its `url`. Send the customer there: the page collects a card or a US bank account with Payra Elements, charges it in your name (the payment shows in RevOS like any other), and sends the customer back to `success_url`. The page pays once and expires after 24 hours unless `expires_at` says otherwise. Requires an `Idempotency-Key`. If your workspace has no active publishable key in this environment, one named "Hosted checkout" is created for the page. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /checkout-sessions openapi: 3.1.0 info: title: Payra API version: v1 description: >- The Payra API. Authenticate with a secret key: `Authorization: Bearer sk_test_...`. The two payment method session endpoints Payra Elements calls also take a publishable key with the session's `client_secret`. servers: - url: https://api-dashboard.payra.com/v1 description: 'Sandbox and live: the key decides which' security: [] paths: /checkout-sessions: post: tags: - Checkout sessions summary: Create a checkout session description: >- Creates a hosted payment page for one order and answers its `url`. Send the customer there: the page collects a card or a US bank account with Payra Elements, charges it in your name (the payment shows in RevOS like any other), and sends the customer back to `success_url`. The page pays once and expires after 24 hours unless `expires_at` says otherwise. Requires an `Idempotency-Key`. If your workspace has no active publishable key in this environment, one named "Hosted checkout" is created for the page. requestBody: required: true content: application/json: schema: type: object properties: amount: type: integer exclusiveMinimum: 0 example: 12550 description: In the smallest unit (cents). currency: type: string enum: - USD - CAD example: USD reference: type: string minLength: 1 maxLength: 100 example: '1042' description: >- Your order or invoice number; stored on the payment and shown in the dashboard. description: type: string minLength: 1 maxLength: 500 example: 'Northwind order #1042' description: >- Shown to the customer on the page, and stored on the payment. success_url: type: string maxLength: 2048 format: uri example: https://shop.example/thanks?order=1042 description: >- Where the customer goes after paying; `?checkout_session=cs_…` is appended. Must be https; a sandbox key may also use `http://localhost` while you test. cancel_url: type: string maxLength: 2048 format: uri example: https://shop.example/cart description: >- Where "Back to store" goes, and where an expired page sends the customer. Must be https; a sandbox key may also use `http://localhost` while you test. customer_email: type: string maxLength: 254 format: email example: ana@example.com description: >- Kept on the session and returned with it, for your records. The page does not show it. customer: type: string format: uuid description: >- One of your customers: the payment is filed on them, and a card can be saved to them. payment_method_types: type: array items: type: string enum: - card - us_bank_account minItems: 1 example: - card - us_bank_account description: >- What the page offers. Omitted means a card only; `us_bank_account` needs `USD`. metadata: allOf: - $ref: '#/components/schemas/CheckoutSessionMetadata' - type: object expires_at: type: string format: date-time example: '2026-09-26T12:00:00.000Z' description: >- When the page stops accepting a payment. Default 24 hours from now; at most 7 days. required: - amount - currency - success_url - cancel_url responses: '201': description: The session, with the URL to send the customer to content: application/json: schema: $ref: '#/components/schemas/CreatedCheckoutSession' '400': description: >- Invalid parameters, a missing Idempotency-Key, an unknown customer, a bank account offered in CAD, or an expiry in the past or more than 7 days out content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid or revoked API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The API is not enabled for the workspace, or the key lacks the scope content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded; see Retry-After content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: CheckoutSessionMetadata: type: - object - 'null' additionalProperties: type: string maxLength: 500 description: >- Up to 20 keys of your own (keys up to 40 characters, values up to 500); stored and returned, never interpreted. example: order_id: '1042' cart: a1b2c3 CreatedCheckoutSession: allOf: - $ref: '#/components/schemas/CheckoutSession' - type: object properties: url: type: string example: >- https://dashboard.payra.com/checkout/cs_test_7Hs2kQ9mL1pXv4cR8tWzAbCd?key=… description: >- Where to send the customer. Returned only here: it carries the key that opens the page. required: - url Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - idempotency_error - card_error - api_error code: type: string message: type: string param: type: string request_id: type: string required: - type - code - message - request_id additionalProperties: type: string required: - error CheckoutSession: type: object properties: object: type: string enum: - checkout_session id: type: string example: cs_test_7Hs2kQ9mL1pXv4cR8tWzAbCd status: type: string enum: - open - complete - expired example: open description: >- `open` while the customer can pay; `complete` once one payment succeeded (or, for a bank debit, was accepted) on the page; `expired` after `expires_at`, or once you expired it. A session pays once. amount: type: integer example: 12550 description: In the smallest unit of the currency (cents). currency: type: string enum: - USD - CAD example: USD reference: type: - string - 'null' example: '1042' description: type: - string - 'null' example: 'Northwind order #1042' success_url: type: string example: https://shop.example/thanks?order=1042 cancel_url: type: string example: https://shop.example/cart customer_email: type: - string - 'null' example: ana@example.com customer: type: - string - 'null' example: null payment_method_types: type: array items: type: string enum: - card - us_bank_account example: - card metadata: $ref: '#/components/schemas/CheckoutSessionMetadata' payment: type: - string - 'null' example: pay_test_7Hs2kQ9mL1pXv4cR8tWzAbCdEf description: >- The payment made on the page, once the session is `complete`; read it at `GET /payments/{id}`. livemode: type: boolean example: false expires_at: type: string example: '2026-09-26T12:00:00.000Z' completed_at: type: - string - 'null' example: null created_at: type: string example: '2026-09-25T12:00:00.000Z' required: - object - id - status - amount - currency - reference - description - success_url - cancel_url - customer_email - customer - payment_method_types - metadata - payment - livemode - expires_at - completed_at - created_at securitySchemes: bearerAuth: type: http scheme: bearer description: >- A secret key, `sk_test_...` or `sk_live_...`; a publishable key (`pk_...`) on the browser routes only ````