> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plugtopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a checkout session

> Creates a short-lived, single-use checkout session. Pass the returned token to your frontend cart — it submits payments without ever seeing the API key.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/checkout/sessions
openapi: 3.0.0
info:
  title: PlugToPay API
  description: API to make payments easy in multiple gateways.
  version: 1.0.0
servers:
  - url: http://localhost:7701
    description: Test Server
security: []
paths:
  /api/v1/checkout/sessions:
    post:
      tags:
        - Checkout
      summary: Create a checkout session
      description: >-
        Creates a short-lived, single-use checkout session. Pass the returned
        token to your frontend cart — it submits payments without ever seeing
        the API key.
      operationId: 16fe3b8df2a33a8e47413e93fe6b3d91
      parameters:
        - $ref: '#/components/parameters/XClientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - amount
                - currency
                - merchant_order_id
              properties:
                amount:
                  description: Amount in cents
                  type: integer
                  example: 15000
                currency:
                  type: string
                  enum:
                    - BRL
                    - USD
                  example: BRL
                merchant_order_id:
                  type: string
                  example: ORD-123
                payment_method:
                  description: Restrict to a specific method. Omit to allow both.
                  type: string
                  enum:
                    - card
                    - pix
                  example: card
                  nullable: true
                gateway_first_try:
                  description: >-
                    Gateway slug to attempt first. Falls back to routing rules
                    if not set or if the gateway is not enabled for this
                    company.
                  type: string
                  enum:
                    - pagarme
                    - picpay
                    - safe2pay
                    - pagbank
                    - stripe
                    - asaas
                    - erede
                  example: pagarme
                  nullable: true
                expires_in:
                  description: 'Lifetime in seconds (60–86400). Default: 1800.'
                  type: integer
                  example: 1800
                metadata:
                  description: Arbitrary data forwarded to your frontend.
                  type: object
                  nullable: true
                success_url:
                  description: Frontend redirect after successful payment.
                  type: string
                  format: uri
                  example: https://mystore.com/order/success
                  nullable: true
                cancel_url:
                  description: Frontend redirect after failed or cancelled payment.
                  type: string
                  format: uri
                  example: https://mystore.com/order/failed
                  nullable: true
                customer:
                  description: >-
                    Customer identification to load saved cards. Provide token,
                    email, or document — checked in that priority order.
                  properties:
                    token:
                      description: PlugToPay customer token.
                      type: string
                      example: cus_abc123
                      nullable: true
                    email:
                      type: string
                      format: email
                      example: customer@example.com
                      nullable: true
                    document:
                      description: CPF or CNPJ (digits only or formatted).
                      type: string
                      example: '12345678909'
                      nullable: true
                  type: object
                  nullable: true
              type: object
      responses:
        '201':
          description: Checkout session created
          content:
            application/json:
              schema:
                properties:
                  token:
                    description: Single-use session token to pass to your frontend.
                    type: string
                    example: cs_live_a1b2c3d4e5f6...
                  amount:
                    description: Amount in cents — immutable once session is created.
                    type: integer
                    example: 15000
                  currency:
                    type: string
                    example: BRL
                  merchant_order_id:
                    type: string
                    example: ORD-123
                  payment_method:
                    type: string
                    enum:
                      - card
                      - pix
                    example: card
                    nullable: true
                  gateway_first_try:
                    type: string
                    example: pagarme
                    nullable: true
                  metadata:
                    type: object
                    nullable: true
                  success_url:
                    type: string
                    format: uri
                    example: https://mystore.com/order/success
                    nullable: true
                  cancel_url:
                    type: string
                    format: uri
                    example: https://mystore.com/order/failed
                    nullable: true
                  expires_at:
                    description: ISO 8601 UTC timestamp when the session expires.
                    type: string
                    format: date-time
                    example: '2026-06-23T14:30:00+00:00'
                  saved_cards:
                    description: >-
                      Active saved cards for the identified customer. Empty
                      array when no customer was identified or no cards exist.
                    type: array
                    items:
                      properties:
                        token:
                          type: string
                          example: card_abc123
                        holder_name:
                          type: string
                          example: John Doe
                        brand:
                          type: string
                          example: visa
                        first_6_digits:
                          type: string
                          example: '411111'
                        last_4_digits:
                          type: string
                          example: '1111'
                        expire_month:
                          type: string
                          example: '12'
                        expire_year:
                          type: string
                          example: '2029'
                        status:
                          type: string
                          example: active
                        created_at:
                          type: string
                          format: date-time
                          example: '2026-06-26T10:00:00+00:00'
                        updated_at:
                          type: string
                          format: date-time
                          example: '2026-06-26T10:00:00+00:00'
                      type: object
                type: object
        '401':
          description: Unauthorized — Invalid API Key
        '422':
          description: Validation error or unsafe redirect URL
      security:
        - ApiKeyAuth: []
components:
  parameters:
    XClientId:
      name: x-client-id
      in: header
      description: Client identifier for the company in the request.
      required: true
      schema:
        type: string
        example: client_abc123
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Company API key. Send in the X-API-Key header.
      name: X-API-Key
      in: header

````