> ## 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. # Finalizar checkout da assinatura > Ativa uma assinatura fornecendo um método de pagamento e efetuando a cobrança. Este endpoint permite completar o processo de checkout de uma assinatura pendente, associando um método de pagamento e processando a primeira cobrança imediatamente. **Tipos de pagamento suportados:** - `card`: Cartão de crédito - `pix`: Pagamento instantâneo via PIX (QR Code) **Fluxo para cartão de crédito:** 1. Valida os dados do cartão e informações de cobrança 2. Cria o método de pagamento associado ao cliente 3. Processa a cobrança do cartão 4. Retorna a assinatura ativada com os detalhes do método de pagamento **Fluxo para PIX:** 1. Gera um QR code PIX sincronamente 2. Retorna o QR code, código copia-e-cola e data de expiração 3. O pagamento é confirmado via webhook quando o cliente pagar 4. Se chamado novamente enquanto o PIX estiver válido, retorna o mesmo (idempotente) 5. Se o PIX expirou, gera um novo automaticamente 6. A assinatura só passa a adotar PIX como método recorrente após a confirmação do pagamento ## OpenAPI ````yaml /api-reference/openapi.yml post /api/v1/subscriptions/{subscription_id}/checkout 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/subscriptions/{subscription_id}/checkout: post: tags: - Assinaturas summary: Finalizar checkout da assinatura description: > Ativa uma assinatura fornecendo um método de pagamento e efetuando a cobrança. Este endpoint permite completar o processo de checkout de uma assinatura pendente, associando um método de pagamento e processando a primeira cobrança imediatamente. **Tipos de pagamento suportados:** - `card`: Cartão de crédito - `pix`: Pagamento instantâneo via PIX (QR Code) **Fluxo para cartão de crédito:** 1. Valida os dados do cartão e informações de cobrança 2. Cria o método de pagamento associado ao cliente 3. Processa a cobrança do cartão 4. Retorna a assinatura ativada com os detalhes do método de pagamento **Fluxo para PIX:** 1. Gera um QR code PIX sincronamente 2. Retorna o QR code, código copia-e-cola e data de expiração 3. O pagamento é confirmado via webhook quando o cliente pagar 4. Se chamado novamente enquanto o PIX estiver válido, retorna o mesmo (idempotente) 5. Se o PIX expirou, gera um novo automaticamente 6. A assinatura só passa a adotar PIX como método recorrente após a confirmação do pagamento operationId: createSubscriptionCheckout parameters: - name: subscription_id in: path description: >- ID único da assinatura a ser finalizada, no formato TypeID com prefixo `sub_`. required: true schema: type: string pattern: ^sub_[0-9a-z]{26}$ example: sub_01h455vb4pex5vsknk084sn02s requestBody: description: > Dados do método de pagamento para finalizar o checkout. O campo `payment_method_type` determina qual método de pagamento será utilizado. **Para `payment_method_type: card`:** requer os objetos `card` e `billing_details`, e aceita `installments` dentro do limite configurado no preço. **Para `payment_method_type: pix`:** não requer campos adicionais e sempre usa `installments: 1`. required: true content: application/json: schema: type: object description: > Dados para finalizar o checkout de uma assinatura. O campo `payment_method_type` determina o método de pagamento a ser utilizado. **Tipos suportados:** - `card`: Cartão de crédito - requer `card` e `billing_details` - `pix`: Pagamento via PIX - não requer campos adicionais required: - payment_method_type properties: payment_method_type: type: string description: | Tipo de método de pagamento a ser utilizado. **Valores suportados:** - `card`: Cartão de crédito - `pix`: Pagamento instantâneo via PIX (QR Code) enum: - card - pix example: card installments: type: integer description: > Quantidade de parcelas para cobrança no cartão de crédito. Use apenas quando `payment_method_type` for `card` e dentro do limite permitido pelo preço da assinatura. Para `pix`, o backend sempre considera `1`. minimum: 1 maximum: 12 default: 1 example: 3 card: type: object description: > Dados do cartão de crédito para processamento do pagamento. **Segurança:** Os dados do cartão são tokenizados e nunca armazenados em texto claro. Apenas os últimos 4 dígitos e a bandeira são mantidos para referência. required: - number - exp_month - exp_year - cvc properties: number: type: string description: > Número completo do cartão de crédito (PAN). Deve conter entre 13 e 19 dígitos. Espaços e hífens são removidos automaticamente. **Bandeiras suportadas:** Visa, Mastercard, American Express, Elo, Hipercard pattern: ^[\d\s-]{13,19}$ example: '4242424242424242' exp_month: type: integer description: | Mês de expiração do cartão (1-12). O cartão não pode estar expirado no momento da cobrança. minimum: 1 maximum: 12 example: 12 exp_year: type: integer description: | Ano de expiração do cartão (formato de 4 dígitos). O cartão não pode estar expirado no momento da cobrança. minimum: 2024 maximum: 2099 example: 2026 cvc: type: string description: | Código de verificação do cartão (CVV/CVC/CID). - 3 dígitos para Visa, Mastercard, Elo - 4 dígitos para American Express pattern: ^\d{3,4}$ example: '123' billing_details: type: object description: > Informações do titular do cartão para validação e prevenção de fraude. O nome e documento são obrigatórios. O endereço é opcional mas recomendado para aumentar a taxa de aprovação das transações. required: - name - document properties: name: type: string description: > Nome completo do titular do cartão exatamente como impresso no cartão. Este nome será validado contra o cadastro do emissor. minLength: 3 maxLength: 100 example: João P Silva document: type: string description: > CPF do titular do cartão (apenas números, 11 dígitos). Usado para validação antifraude e conformidade regulatória. pattern: ^\d{11}$ example: '12345678900' address: type: object description: > Endereço de cobrança do titular do cartão. Fornecer o endereço completo aumenta significativamente a taxa de aprovação das transações, pois permite validação AVS (Address Verification System). properties: street: type: string description: | Nome da rua, avenida ou logradouro. Exemplo: "Rua das Flores", "Av. Paulista" maxLength: 200 example: Rua das Flores number: type: string description: | Número do endereço. Exemplo: "123", "456-A", "S/N" maxLength: 20 example: '123' complement: type: string description: > Complemento do endereço (apartamento, bloco, sala, etc). Opcional. Deixe vazio se não houver complemento. maxLength: 100 example: Apto 45 neighborhood: type: string description: Bairro do endereço de cobrança. maxLength: 100 example: Centro city: type: string description: Cidade do endereço de cobrança. maxLength: 100 example: São Paulo state: type: string description: | Estado (UF) do endereço de cobrança. Use a sigla de 2 letras (ex: SP, RJ, MG). pattern: ^[A-Z]{2}$ maxLength: 2 example: SP postal_code: type: string description: > CEP do endereço de cobrança. Formato aceito: "12345-678" ou "12345678" (com ou sem hífen). pattern: ^\d{5}-?\d{3}$ example: 01310-100 examples: pix: summary: Checkout com PIX description: Gera um QR code PIX para pagamento instantâneo value: payment_method_type: pix cartao_completo: summary: Checkout com cartão de crédito (dados completos) description: >- Exemplo com todos os campos de endereço de cobrança preenchidos value: payment_method_type: card installments: 3 card: number: '4242424242424242' exp_month: 12 exp_year: 2026 cvc: '123' billing_details: name: João da Silva document: '12345678900' address: street: Rua das Flores number: '123' complement: Apto 45 neighborhood: Centro city: São Paulo state: SP postal_code: 01310-100 cartao_minimo: summary: Checkout com cartão de crédito (dados mínimos) description: Exemplo com apenas os campos obrigatórios value: payment_method_type: card card: number: '5555555555554444' exp_month: 6 exp_year: 2027 cvc: '456' billing_details: name: Maria Santos document: '98765432100' responses: '201': description: > Checkout realizado com sucesso. O response inclui os detalhes da assinatura e do método de pagamento. **Para cartão:** A cobrança é processada imediatamente e a assinatura passa para `active`. **Para PIX:** O QR code é retornado para o cliente pagar; a assinatura permanece `pending` até a confirmação do pagamento. content: application/json: schema: type: object description: > Resposta do checkout bem-sucedido contendo a assinatura e os detalhes do método de pagamento gerado. required: - id - object - live_mode - created - customer - status properties: id: type: string pattern: ^sub_[0-9a-z]{26}$ description: >- ID único da assinatura, no formato TypeID com prefixo `sub_`. example: sub_01h455vb4pex5vsknk084sn02s object: type: string description: Tipo do objeto retornado. Sempre "subscription". enum: - subscription example: subscription live_mode: type: boolean description: Indica se a requisição foi feita em modo produção. example: true created: type: integer format: int64 description: Timestamp Unix de quando a assinatura foi criada. example: 1764040287 current_period_end: type: integer format: int64 description: Timestamp Unix do fim do período atual de cobrança. example: 1766632287 current_period_start: type: integer format: int64 description: Timestamp Unix do início do período atual de cobrança. example: 1764040287 customer: type: string pattern: ^cus_[0-9a-z]{26}$ description: >- ID do cliente associado à assinatura, no formato TypeID com prefixo `cus_`. example: cus_01h455vb4pex5vsknk084sn02p payment_method: type: object description: > Detalhes do método de pagamento criado e associado à assinatura. Para cartão: por segurança, apenas os últimos 4 dígitos são retornados. Para PIX: retorna o QR code, código copia-e-cola e data de expiração. required: - id - object - type properties: id: type: string pattern: ^(card|txn)_[0-9a-z]{26}$ description: > ID do método de pagamento, no formato TypeID. Para cartões usa prefixo `card_` (Payment::CreditCard); para PIX usa prefixo `txn_` (Payment::Transaction). example: card_01h455vb4pex5vsknk084sn02c object: type: string description: Tipo do objeto. Sempre "payment_method". enum: - payment_method example: payment_method card: type: object description: > Informações resumidas do cartão para exibição. Por segurança, apenas dados não-sensíveis são retornados. Campos em ordem alfabética. properties: brand: type: string description: > Bandeira do cartão identificada automaticamente. Valores possíveis: visa, mastercard, amex, elo, hipercard, etc. example: visa exp_month: type: integer description: Mês de expiração do cartão (1-12). minimum: 1 maximum: 12 example: 12 exp_year: type: integer description: Ano de expiração do cartão. example: 2026 last4: type: string description: Últimos 4 dígitos do número do cartão. pattern: ^\d{4}$ example: '4242' created: type: integer format: int64 description: >- Timestamp Unix de quando o método de pagamento foi criado. example: 1764040285 pix: type: object description: > Dados do QR code PIX para pagamento. O QR code é válido até a data de expiração (`expires`). Após esse período, um novo QR code será gerado automaticamente se o endpoint for chamado novamente. required: - qr_code - pix_copy_paste properties: qr_code: type: string description: > Imagem do QR code em formato base64 (PNG). Este QR code pode ser exibido diretamente ao usuário para leitura pelo aplicativo do banco. example: iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAYAAACI7Fo9... pix_copy_paste: type: string description: > Código PIX copia-e-cola (formato EMV). O usuário pode copiar este código e colar diretamente no aplicativo do banco para realizar o pagamento sem escanear o QR code. example: >- 00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1c4c12345678... expires: type: - integer - 'null' format: int64 description: > Timestamp Unix de quando o QR code PIX expira. Após esta data, o QR code não será mais válido e um novo será gerado automaticamente ao chamar o endpoint novamente. Pode ser null em ambiente de testes. example: 1764047487 type: type: string description: Tipo do método de pagamento. enum: - card - pix example: card status: type: string description: > Status atual da assinatura após o checkout. - `card`: a cobrança é processada imediatamente e o status passa para `active`. - `pix`: o QR code é gerado, mas o pagamento ainda não foi confirmado; o status permanece `pending` até a confirmação via webhook. enum: - pending - active - inactive - suspended example: active examples: pix_sucesso: summary: PIX gerado com sucesso description: Retorna o QR code PIX para pagamento value: id: sub_01h455vb4pex5vsknk084sn02s object: subscription live_mode: true created: 1764040287 current_period_end: 1766632287 current_period_start: 1764040287 customer: cus_01h455vb4pex5vsknk084sn02p payment_method: id: txn_01h455vb4pex5vsknk084sn02x object: payment_method type: pix pix: qr_code: iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6CAYAAACI7Fo9... pix_copy_paste: >- 00020126580014br.gov.bcb.pix0136a629532e-7693-4846-852d-1c4c12345678... expires: 1764047487 created: 1764040285 status: pending cartao_sucesso: summary: Cartão processado com sucesso description: Retorna os detalhes do cartão utilizado value: id: sub_01h455vb4pex5vsknk084sn02s object: subscription live_mode: true created: 1764040287 current_period_end: 1766632287 current_period_start: 1764040287 customer: cus_01h455vb4pex5vsknk084sn02p payment_method: id: card_01h455vb4pex5vsknk084sn02c object: payment_method card: brand: visa exp_month: 12 exp_year: 2026 last4: '4242' created: 1764040285 status: active '404': description: Não encontrado content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: URI que identifica o tipo de problema format: uri enum: - https://problems-registry.smartbear.com/not-found status: type: integer description: O código de status HTTP format: int32 enum: - 404 title: type: string description: O nome do status HTTP enum: - Not Found detail: type: string description: Mensagem descritiva do erro code: type: string description: Código de erro interno da API enum: - NOT_FOUND - RESOURCE_MISSING 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: ''019abc12-3456-7890-abcd-ef1234567890''' 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: unsupported_payment_type: summary: Tipo de pagamento não suportado value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: >- Tipo de pagamento não suportado. Tipos válidos: 'card', 'pix' code: UNSUPPORTED_PAYMENT_TYPE card_declined: summary: Cartão recusado value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Cartão recusado pela operadora code: CARD_DECLINED subscription_inactive: summary: Assinatura inativa value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Assinatura não está ativa code: SUBSCRIPTION_INACTIVE no_open_invoice: summary: Nenhuma fatura aberta value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Assinatura não possui fatura em aberto code: NO_OPEN_INVOICE pix_generation_failed: summary: Falha ao gerar PIX value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Falha ao gerar QR code PIX code: PIX_GENERATION_FAILED payment_failed: summary: Falha no pagamento value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Falha no processamento do pagamento code: PAYMENT_FAILED invalid_installments: summary: Parcelamento inválido value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Parcelamento invalido para este preco code: INVALID_INSTALLMENTS validacao_cartao: summary: Dados do cartão inválidos 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: Número do cartão inválido pointer: /checkout/card_number 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` ````