> ## Documentation Index > Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar nova sessão de checkout > Criar nova sessão de checkout na sua conta. A sessão permite que um cliente complete um pagamento ou assinatura através de uma interface web. O cliente é opcional. Você pode: - Enviar `customer_id` para vincular um cliente já existente. - Enviar `customer` com os dados para criar um cliente junto com a sessão. - Omitir ambos: a sessão é criada sem cliente vinculado e o próprio comprador preencherá os dados (nome, CPF/CNPJ, e-mail e telefone) ao acessar a `url` retornada. Nesse caso, `customer`, `invoice`, `subscription` e `amount` voltam `null` na resposta e são preenchidos somente após o comprador finalizar o cadastro. Validação de `line_items` e `discounts` ocorre em todos os casos — uma sessão sem cliente também recebe `404 RESOURCE_MISSING` para `price_id` inexistente e `422` para `TOO_MANY_LINE_ITEMS` / `DISCOUNT_EXCEEDS_SUBTOTAL`. **Limite de taxa:** 10 requisições por minuto por chave de API. ## OpenAPI ````yaml /api-reference/openapi.yml post /api/v1/checkout/sessions openapi: 3.1.0 info: title: API - Simplo version: 1.0.0 description: API para cobrança e assinaturas para contas Simplo contact: name: Simplo url: https://besimplo.com email: team@besimplo.com servers: - url: https://besimplo.com description: Produção security: - apiKeyAuth: [] tags: - name: Clientes description: Clientes são as pessoas que pagarão pelos produtos da sua conta - name: Produtos description: Produtos representam os bens ou serviços que você vende - name: Preços description: Preços definem quanto cobrar e a frequência de cobrança de um Produto - name: Assinaturas description: Assinaturas conectam clientes aos seus planos para cobrança recorrente - name: Checkout description: >- Sessões de checkout permitem que clientes completem pagamentos e assinaturas através de uma interface web - name: Faturas description: Faturas representam cobranças geradas para clientes - name: Reembolsos description: Reembolsos permitem devolver pagamentos já realizados aos clientes - name: Webhooks description: > Eventos enviados via HTTP POST para a URL configurada na sua conta. Responda com status 2xx rapidamente. Processe o evento de forma assincrona. Use o campo `event.id` para garantir idempotencia. paths: /api/v1/checkout/sessions: post: tags: - Checkout summary: Criar nova sessão de checkout description: > Criar nova sessão de checkout na sua conta. A sessão permite que um cliente complete um pagamento ou assinatura através de uma interface web. O cliente é opcional. Você pode: - Enviar `customer_id` para vincular um cliente já existente. - Enviar `customer` com os dados para criar um cliente junto com a sessão. - Omitir ambos: a sessão é criada sem cliente vinculado e o próprio comprador preencherá os dados (nome, CPF/CNPJ, e-mail e telefone) ao acessar a `url` retornada. Nesse caso, `customer`, `invoice`, `subscription` e `amount` voltam `null` na resposta e são preenchidos somente após o comprador finalizar o cadastro. Validação de `line_items` e `discounts` ocorre em todos os casos — uma sessão sem cliente também recebe `404 RESOURCE_MISSING` para `price_id` inexistente e `422` para `TOO_MANY_LINE_ITEMS` / `DISCOUNT_EXCEEDS_SUBTOTAL`. **Limite de taxa:** 10 requisições por minuto por chave de API. operationId: createCheckoutSession requestBody: description: Dados da sessão de checkout que será criada required: true content: application/json: schema: type: object unevaluatedProperties: false required: - session properties: session: type: object unevaluatedProperties: false required: - success_url - line_items properties: external_code: type: - string - 'null' nullable: true description: >- ID externo usado para referenciar a sessão de checkout, deve ser único maxLength: 250 example: CHECKOUT-SESSION-XYZ customer_id: type: - string - 'null' nullable: true pattern: ^cus_[0-9a-z]{26}$ description: > ID de um Cliente existente que realizará o checkout, no formato TypeID com prefixo `cus_`. Opcional. Se omitido em conjunto com `customer`, a sessão é criada sem cliente vinculado e o próprio comprador preencherá os dados na página de checkout (`url`). Não envie `customer_id` e `customer` ao mesmo tempo. example: cus_01h455vb4pex5vsknk084sn02p customer: type: - object - 'null' nullable: true description: > Dados do cliente que será criado junto com a sessão. Opcional. Se omitido em conjunto com `customer_id`, o comprador preenche os dados na página de checkout. Não envie `customer_id` e `customer` ao mesmo tempo. allOf: - type: object unevaluatedProperties: false required: - name properties: external_code: type: - string - 'null' nullable: true description: >- Código externo para integração. Deve ser único por conta. maxLength: 250 example: 01953808-3a3a-712f-99ce-f6943c8141db identifier: type: - string - 'null' nullable: true description: CPF ou CNPJ do cliente. maxLength: 250 example: 123.456.789-00 name: type: string description: Nome do cliente. minLength: 1 maxLength: 250 example: João Silva email: type: - string - 'null' nullable: true description: E-mail do cliente. format: email maxLength: 250 example: joao.silva@exemplo.com phone: type: - string - 'null' nullable: true description: Telefone do cliente. maxLength: 250 example: '+5511999998888' address: type: object unevaluatedProperties: false required: - zip_code - street - number - district - city - state properties: zip_code: type: string description: CEP example: '12345012' street: type: string description: Rua example: Alguma Rua number: type: string description: Número example: '9934' district: type: string description: Bairro example: D'algum Bairro city: type: string description: Cidade example: Campinas state: type: string description: Estado example: SP complement: type: - string - 'null' description: Complemento example: Apt. 123 mode: type: string description: Modo da sessão de checkout enum: - payment - subscription default: subscription example: subscription success_url: type: string format: uri description: >- URL para redirecionar o cliente após o pagamento bem-sucedido example: https://example.com/success return_url: type: - string - 'null' nullable: true format: uri description: >- URL para redirecionar o cliente caso ele cancele ou retorne example: https://example.com/return metadata: type: array description: Metadados adicionais associados à sessão de checkout items: type: object additionalProperties: true example: [] line_items: type: array description: Lista de itens que serão incluídos na sessão de checkout minItems: 1 items: type: object unevaluatedProperties: false required: - price_id - quantity properties: price_id: type: string pattern: ^price_[0-9a-z]{26}$ description: >- ID do Preço existente, no formato TypeID com prefixo `price_`. example: price_01h455vb4pex5vsknk084sn02q quantity: type: integer description: Quantidade do item minimum: 1 example: 1 example: - price_id: price_01h455vb4pex5vsknk084sn02q quantity: 1 discounts: type: array description: > Desconto aplicado à sessão de checkout. No modo `subscription`, o desconto é registrado na assinatura criada. No modo `payment`, é aplicado como abatimento na fatura única gerada (`cycles` é ignorado nesse modo). maxItems: 1 items: oneOf: - type: object unevaluatedProperties: false required: - type properties: type: type: string description: >- Tipo de desconto. `percentage` aplica um percentual sobre o subtotal; `fixed` aplica um valor fixo em centavos. enum: - percentage - fixed example: percentage percentage: type: - integer - 'null' nullable: true description: >- Percentual do desconto (1 a 100). Obrigatório quando `type` é `percentage` e proibido quando `type` é `fixed`. minimum: 1 maximum: 100 example: 20 amount_cents: type: - integer - 'null' nullable: true description: >- Valor fixo do desconto em centavos. Obrigatório quando `type` é `fixed` e proibido quando `type` é `percentage`. minimum: 1 example: 5000 cycles: type: - integer - 'null' nullable: true description: > Número de ciclos de cobrança em que o desconto será aplicado. `0` significa ilimitado. Padrão `0`. Ignorado no modo `payment`. minimum: 0 default: 0 example: 3 description: type: - string - 'null' nullable: true description: Descrição livre exibida na fatura. maxLength: 250 example: Promo Q2 example: - type: percentage percentage: 20 cycles: 3 description: Promo Q2 responses: '201': description: Operação realizada com sucesso content: application/json: schema: type: object unevaluatedProperties: false required: - live_mode - customer - invoice - amount - currency - url properties: live_mode: type: boolean description: Indica se a requisição foi feita em modo produção. example: true customer: type: - object - 'null' nullable: true description: > Cliente vinculado à sessão. `null` quando `customer_id`/`customer` não foram enviados na criação — o comprador irá preencher os dados na página de checkout, e o cliente será criado nesse momento. unevaluatedProperties: false required: - id properties: id: type: string pattern: ^cus_[0-9a-z]{26}$ description: ID do cliente, no formato TypeID com prefixo `cus_`. example: cus_01h455vb4pex5vsknk084sn02p invoice: type: - object - 'null' nullable: true description: > Fatura gerada para a sessão. `null` quando o cliente ainda não foi informado — a fatura é criada após o comprador preencher os dados na página de checkout. unevaluatedProperties: false required: - id properties: id: type: string pattern: ^in_[0-9a-z]{26}$ description: ID da fatura, no formato TypeID com prefixo `in_`. example: in_01h455vb4pex5vsknk084sn02q subscription: type: - object - 'null' nullable: true description: > Dados da assinatura. Presente apenas quando `mode` é `subscription` e a fatura já foi criada. `null` quando o cliente ainda não foi informado ou quando `mode` é `payment`. unevaluatedProperties: false required: - id properties: id: type: string pattern: ^sub_[0-9a-z]{26}$ description: >- ID da assinatura, no formato TypeID com prefixo `sub_`. example: sub_01h455vb4pex5vsknk084sn02s amount: type: - integer - 'null' nullable: true description: > Valor total em centavos. `null` quando o cliente ainda não foi informado e a fatura não foi gerada. example: 9990 currency: type: string description: Código da moeda (ISO 4217). enum: - brl example: brl discounts: type: object description: >- Descontos aplicados à sessão (presente apenas quando há descontos). unevaluatedProperties: false required: - object - data properties: object: type: string enum: - list example: list data: type: array items: type: object unevaluatedProperties: false required: - type properties: type: type: string description: >- Tipo de desconto aplicado (`percentage` ou `fixed`). enum: - percentage - fixed example: percentage percentage: type: - integer - 'null' nullable: true description: >- Percentual do desconto. Presente apenas quando `type` é `percentage`. example: 20 amount_cents: type: - integer - 'null' nullable: true description: >- Valor fixo do desconto em centavos. Presente apenas quando `type` é `fixed`. example: 5000 cycles: type: - integer - 'null' nullable: true description: >- Número de ciclos de cobrança em que o desconto será aplicado. `0` significa ilimitado. Sempre `0` no modo `payment`. example: 3 description: type: - string - 'null' nullable: true description: Descrição livre do desconto, exibida na fatura. example: Promo Q2 url: type: string format: uri description: URL da sessão de checkout para redirecionar o cliente example: >- https://besimplo.com/checkout/sessions/cs_01h455vb4pex5vsknk084sn02q?session_id=cs_01h455vb4pex5vsknk084sn02q example: live_mode: true customer: id: cus_01h455vb4pex5vsknk084sn02p invoice: id: in_01h455vb4pex5vsknk084sn02q subscription: id: sub_01h455vb4pex5vsknk084sn02s amount: 9990 currency: brl url: >- https://besimplo.com/checkout/sessions/cs_01h455vb4pex5vsknk084sn02q?session_id=cs_01h455vb4pex5vsknk084sn02q '404': description: Recurso não encontrado content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: not_found: summary: Recurso não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: The requested resource was not found code: NOT_FOUND customer_not_found: summary: Cliente não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: 'No such customer: ''cus_01h455vb4pex5vsknk084sn02p''' code: RESOURCE_MISSING price_not_found: summary: Preço não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: 'No such price: ''price_01h455vb4pex5vsknk084sn02p''' code: RESOURCE_MISSING '422': description: Erro de regra de negócio ou validação content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: invalid_mode: summary: Modo inválido value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: >- Modo de checkout inválido. Modos válidos: 'subscription', 'payment' code: INVALID_MODE too_many_discounts: summary: Mais de um desconto enviado value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Apenas um desconto por sessão de checkout é permitido code: TOO_MANY_DISCOUNTS too_many_line_items: summary: Mais de um item enviado em assinatura value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: >- Apenas um item por sessão de checkout é permitido em assinaturas code: TOO_MANY_LINE_ITEMS invalid_discount: summary: Desconto inválido value: type: https://problems-registry.smartbear.com/validation-error status: 422 title: Unprocessable Entity detail: >- Tipo de desconto inválido. Tipos válidos: 'percentage', 'fixed' code: INVALID_DISCOUNT discount_exceeds_subtotal: summary: Desconto fixo acima do subtotal value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: O valor do desconto excede o subtotal do pedido code: DISCOUNT_EXCEEDS_SUBTOTAL checkout_creation_failed: summary: Falha ao criar checkout value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Não foi possível criar o checkout code: CHECKOUT_CREATION_FAILED validation_error: summary: Erro de validação value: type: https://problems-registry.smartbear.com/validation-error status: 422 title: Unprocessable Entity detail: The request payload contains validation errors code: VALIDATION_ERROR errors: - detail: Campo obrigatório não informado pointer: /checkout/success_url components: securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: > A chave de API usada para autenticar a requisição e identificar a sua conta. **Exemplo:** `Authorization: ApiKey my-secure-key` ````