curl --request POST \
  --url https://besimplo.com/api/v1/invoices/{invoice_id}/checkout \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payment_method_type": "pix"
}
'

{
  "id": "in_01h455vb4pex5vsknk084sn02q",
  "object": "invoice",
  "amount_due": 19990,
  "amount_paid": 0,
  "amount_remaining": 19990,
  "created": 1764040287,
  "currency": "brl",
  "customer": "cus_01h455vb4pex5vsknk084sn02p",
  "customer_email": "cliente@example.com",
  "customer_name": "João da Silva",
  "live_mode": true,
  "paid": false,
  "payment_intent": "pi_01h455vb4pex5vsknk084sn02z",
  "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": "open",
  "status_transitions": {
    "paid_at": null
  },
  "subscription": null,
  "total": 19990
}

Faturas

Realizar checkout de uma fatura

Cobra uma fatura em aberto via PIX ou cartão de crédito.

Fluxo canônico para cobrança avulsa via API:

POST /api/v1/invoices cria a fatura avulsa
Este endpoint (POST /api/v1/invoices/{invoice_id}/checkout) efetua a cobrança
Para PIX, a confirmação chega via webhook invoice.paid; para cartão, a resposta já retorna a fatura paga

Uma sessão de checkout com mode: payment também gera uma fatura avulsa (fluxo de página hospedada): informe o cliente (customer_id ou customer), pegue o invoice.id retornado e chame este endpoint da mesma forma.

Também funciona para faturas de assinatura em aberto, com o mesmo comportamento do endpoint de checkout da assinatura.

Fluxo para PIX:

Gera um QR code PIX sincronamente
Retorna o QR code, código copia-e-cola e data de expiração
O pagamento é confirmado via webhook (invoice.paid) quando o cliente pagar
Se chamado novamente enquanto o PIX estiver válido, retorna o mesmo (idempotente)
Se o PIX expirou, gera um novo automaticamente
Se o pagamento já foi confirmado e a fatura aguarda a baixa, retorna PIX_PAYMENT_CONFIRMED em vez de gerar um novo QR code

Fluxo para cartão de crédito:

Valida os dados do cartão e as informações de cobrança
Se houver um QR code PIX em aberto para a fatura, ele é expirado antes da cobrança — sem risco de pagamento duplicado
Processa a cobrança sincronamente: se aprovada, a fatura já retorna com status paid (sem esperar webhook)
Se o cartão for recusado, retorna CARD_DECLINED; a fatura continua open e um novo checkout (cartão ou PIX) pode ser tentado
O limite de parcelas (installments) é definido pelo preço do primeiro item da fatura

POST

api

invoices

{invoice_id}

checkout

curl --request POST \
  --url https://besimplo.com/api/v1/invoices/{invoice_id}/checkout \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "payment_method_type": "pix"
}
'

{
  "id": "in_01h455vb4pex5vsknk084sn02q",
  "object": "invoice",
  "amount_due": 19990,
  "amount_paid": 0,
  "amount_remaining": 19990,
  "created": 1764040287,
  "currency": "brl",
  "customer": "cus_01h455vb4pex5vsknk084sn02p",
  "customer_email": "cliente@example.com",
  "customer_name": "João da Silva",
  "live_mode": true,
  "paid": false,
  "payment_intent": "pi_01h455vb4pex5vsknk084sn02z",
  "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": "open",
  "status_transitions": {
    "paid_at": null
  },
  "subscription": null,
  "total": 19990
}

Authorizations

Authorization

string

header

required

A chave de API usada para autenticar a requisição e identificar a sua conta.

Exemplo: Authorization: ApiKey my-secure-key

Path Parameters

invoice_id

string

required

ID único da fatura a ser cobrada, no formato TypeID com prefixo in_.

Pattern: ^in_[0-9a-z]{26}$

Example:

"in_01h455vb4pex5vsknk084sn02q"

Body

application/json

Dados do método de pagamento.

Para payment_method_type: pix: não requer campos adicionais. Para payment_method_type: card: requer os objetos card e billing_details, e aceita installments dentro do limite definido pelo preço do primeiro item da fatura.

Dados para gerar a cobrança da fatura.

Tipos suportados:

pix: gera um QR code PIX — não requer campos adicionais.
card: cartão de crédito — requer card e billing_details, aceita installments.

Cobrança no cartão:

A cobrança é síncrona: se aprovada, a fatura já retorna com status paid.
Se houver um QR code PIX em aberto para a fatura, ele é expirado antes da cobrança — sem risco de pagamento duplicado.
O limite de parcelas é definido pelo preço do primeiro item da fatura.

payment_method_type

enum<string>

required

Tipo do método de pagamento: - pix: Pagamento instantâneo via PIX (QR Code). - card: Cartão de crédito.

Available options:

pix,

card

Example:

"pix"

installments

integer

default:1

Quantidade de parcelas para cobrança no cartão de crédito.

Use apenas quando payment_method_type for card. O limite de parcelas é definido pelo preço do primeiro item da fatura. Para pix, o backend sempre considera 1.

Required range: 1 <= x <= 12

Example:

3

card

object

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.

Show child attributes

billing_details

object

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.

Show child attributes

Response

Cobrança realizada com sucesso.

Para PIX: o response inclui a fatura e o QR code para pagamento. A fatura permanece open até a confirmação do pagamento via webhook. Para cartão: a cobrança é processada imediatamente e a fatura já retorna com status paid.

Resposta do checkout bem-sucedido contendo a fatura e os detalhes do método de pagamento utilizado.

pix: inclui o QR code gerado; a fatura permanece open até a confirmação do pagamento via webhook.
card: a cobrança é síncrona; quando aprovada, a fatura já retorna com status paid.

string

required

read-only

ID único da fatura, no formato TypeID com prefixo in_.

Pattern: ^in_[0-9a-z]{26}$

Example:

"in_01h455vb4pex5vsknk084sn02q"

object

enum<string>

required

Tipo do objeto. Sempre 'invoice'.

Available options:

invoice

Example:

"invoice"

amount_due

integer

required

Valor a pagar em centavos. R$ 99,90 = 9990.

Example:

9990

created

integer<int64>

required

read-only

Timestamp Unix da criação da fatura.

Example:

1704672000

currency

enum<string>

required

Moeda do valor. Sempre 'brl' (Real brasileiro).

Available options:

brl

Example:

"brl"

customer

string

required

ID do cliente associado à fatura, no formato TypeID com prefixo cus_.

Pattern: ^cus_[0-9a-z]{26}$

Example:

"cus_01h455vb4pex5vsknk084sn02p"

live_mode

boolean

required

Indica ambiente de produção (true) ou sandbox (false). Dados de sandbox são limpos periodicamente.

Example:

true

status

enum<string>

required

Status atual da fatura.

draft: Rascunho, ainda não finalizada.
open: Aberta, aguardando pagamento.
paid: Paga.
uncollectible: Marcada como incobrável.
void: Cancelada.

Available options:

draft,

open,

paid,

uncollectible,

void

Example:

"open"

total

integer

required

Valor total da fatura em centavos. R$ 99,90 = 9990.

Example:

9990

payment_method

object

required

Método de pagamento utilizado na cobrança da fatura.

Option 1
Option 2

Show child attributes

amount_paid

integer

Valor já pago em centavos. R$ 99,90 = 9990.

Example:

0

amount_refunded

integer

Valor estornado em centavos. Permanece separado de status: uma fatura paga continua com status: paid depois de um estorno total ou parcial.

Example:

0

amount_remaining

integer

Valor restante a pagar em centavos. R$ 99,90 = 9990.

Example:

9990

customer_email

string | null

E-mail do cliente.

Example:

"joao.silva@exemplo.com"

customer_name

string | null

Nome do cliente.

Example:

"João Silva"

external_code

string | null

Código externo para integração com outros sistemas. Único por conta.

Example:

"PEDIDO-123"

paid

boolean

Indica se a fatura foi paga.

Example:

false

payment_intent

string | null

ID da cobrança associada à fatura, no formato TypeID com prefixo pi_. null enquanto a fatura ainda não tem cobrança gerada.

Example:

"pi_01h455vb4pex5vsknk084sn02r"

status_transitions

object

Timestamps de quando a fatura mudou de status. Campos são null se a transição ainda não ocorreu.

Show child attributes

subscription

string | null

ID da assinatura associada (se aplicável), no formato TypeID com prefixo sub_.

Example:

"sub_01h455vb4pex5vsknk084sn02s"

Visão geral

Endpoints

Realizar checkout de uma fatura

Authorizations

Path Parameters

Body

Response