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

# Create checkout session

> Cria uma sessão de checkout hospedado. Redirecione o comprador para a `checkoutUrl` retornada — a Bob cuida da tela de pagamento, dos métodos disponíveis e da confirmação. Requer API key (Bearer).

Create a session on your backend and redirect the buyer to the returned `checkoutUrl`. In `paymentMethods`, use `['pix']` (the default) or `['crypto']` for crypto payments. Support for `credit_card` will be added when card payments launch.

<Warning>
  Never create a session in the frontend with a `sk_test_` or `sk_live_` key. This endpoint requires a secret key and must be called from your server.
</Warning>


## OpenAPI

````yaml POST /api/v1/checkout-sessions/
openapi: 3.0.3
info:
  title: Bob Payments API
  description: >-
    API de pagamentos Bob Payments para criar, acompanhar e conciliar transações
    com PIX e cartão de crédito.
  version: 1.0.0
servers:
  - url: https://api.payments.bob.company
    description: Servidor de produção
security: []
paths:
  /api/v1/checkout-sessions/:
    post:
      tags:
        - Checkout
      summary: Criar sessão de checkout
      description: >-
        Cria uma sessão de checkout hospedado. Redirecione o comprador para a
        `checkoutUrl` retornada — a Bob cuida da tela de pagamento, dos métodos
        disponíveis e da confirmação. Requer API key (Bearer).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amountCents:
                  type: integer
                  minimum: 1
                  maximum: 50000000
                  description: Valor total em centavos (ex. 10000 = R$ 100,00)
                currency:
                  type: string
                  enum:
                    - BRL
                  default: BRL
                customer:
                  type: object
                  description: Dados do comprador para pré-preencher o checkout (opcional)
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 255
                    email:
                      type: string
                      format: email
                    document:
                      type: string
                      minLength: 11
                      maxLength: 14
                    documentType:
                      type: string
                      enum:
                        - CPF
                        - CNPJ
                    phone:
                      type: string
                      minLength: 8
                      maxLength: 25
                items:
                  type: array
                  description: >-
                    Itens exibidos no resumo do pedido (metadado de exibição — o
                    catálogo é seu)
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 255
                      quantity:
                        type: integer
                        minimum: 1
                      unitAmountCents:
                        type: integer
                        minimum: 0
                    required:
                      - name
                      - quantity
                      - unitAmountCents
                paymentMethods:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum:
                      - pix
                      - credit_card
                      - boleto
                  description: >-
                    Métodos aceitos no checkout. Default [pix]. Use credit_card
                    para oferecer cartão de crédito quando houver rota
                    publicada.
                metadata:
                  type: object
                  additionalProperties: true
                successUrl:
                  type: string
                  format: uri
                cancelUrl:
                  type: string
                  format: uri
                webhookUrl:
                  type: string
                  format: uri
                  description: >-
                    URL que recebe os webhooks desta sessão. Quando presente, a
                    resposta traz o `webhookSecret` de assinatura.
                webhookVersion:
                  type: string
                  enum:
                    - v1
                    - v2
                  default: v1
                  description: >-
                    Versão do payload/assinatura do webhook. Recomendado v2
                    (valores em centavos + assinatura anti-replay). O SDK
                    oficial envia v2 por padrão.
                expiresAt:
                  type: string
                  format: date-time
                  description: >-
                    Expiração do LINK de checkout (default 24h). Para PIX, não
                    confundir com a expiração da cobrança gerada dentro dele.
              required:
                - amountCents
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    default: true
                    type: boolean
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      sessionId:
                        type: string
                      checkoutToken:
                        type: string
                      checkoutUrl:
                        type: string
                        description: >-
                          URL do checkout hospedado — redirecione o comprador
                          para cá
                      status:
                        type: string
                        enum:
                          - PENDING
                          - PAID
                          - EXPIRED
                          - CANCELLED
                          - FAILED
                          - REFUNDED
                      expiresAt:
                        nullable: true
                        type: string
                      webhookSecret:
                        type: string
                        nullable: true
                        description: >-
                          Secret HMAC dos webhooks desta sessão — exibido apenas
                          aqui, guarde com segurança (null quando webhookUrl não
                          foi enviado)
                      webhookApiVersion:
                        type: string
                        enum:
                          - v1
                          - v2
                    required:
                      - sessionId
                      - checkoutToken
                      - checkoutUrl
                      - status
                      - expiresAt
                      - webhookSecret
                      - webhookApiVersion
                required:
                  - success
                  - message
                  - data
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Token JWT para endpoints autenticados do dashboard

````