Integrando o Checkout

Este guia mostra como implementar um checkout completo aceitando cartão de crédito, Pix e boleto bancário.

Escolha os métodos de pagamento

Defina quais métodos serão oferecidos ao cliente. Cartão é processado imediatamente; Pix e boleto geram um código para o cliente pagar depois.

Colete os dados do pagador

Sempre colete nome, CPF/CNPJ e e-mail do cliente. Para cartão, use tokenização para não trafegar dados sensíveis pelo seu servidor.

Crie a transação

Chame `POST /transactions` com os dados coletados. O retorno contém campos específicos por método (QR code para Pix, linha digitável para boleto).

Exiba a confirmação

Para cartão, mostre o status imediatamente. Para Pix e boleto, exiba as instruções de pagamento e aguarde o webhook.

Confirme via webhook

Monitore `transaction.paid` para liberar o pedido no seu sistema após a confirmação do pagamento.

Cartão de Crédito

curl --request POST \
  --url "{apiUrl}/transactions" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 15000,
    "payment_method": "credit_card",
    "installments": 3,
    "card": {
      "number": "4111111111111111",
      "holder_name": "Maria Silva",
      "exp_month": 12,
      "exp_year": 2028,
      "cvv": "123"
    },
    "customer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "document": "11144477735"
    }
  }'

Exemplo de resposta (cartão aprovado):

json

{
  "order": {
    "id": "txn_abc123",
    "status": "paid",
    "amount": 15000,
    "installments": 3,
    "payment_method": "credit_card"
  }
}

Pix

curl --request POST \
  --url "{apiUrl}/transactions" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 15000,
    "payment_method": "pix",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "document": "11144477735"
    }
  }'

Exemplo de resposta (Pix gerado):

json

{
  "order": {
    "id": "txn_def456",
    "status": "pending",
    "payment_method": "pix",
    "pix": {
      "qr_code": "00020126...",
      "qr_code_url": "https://...",
      "expiration_date": "2026-03-27T16:00:00Z"
    }
  }
}

Boleto

curl --request POST \
  --url "{apiUrl}/transactions" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 15000,
    "payment_method": "boleto",
    "boleto": {
      "due_at": "2026-04-01"
    },
    "customer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "document": "11144477735"
    }
  }'

Exemplo de resposta (boleto gerado):

json

{
  "order": {
    "id": "txn_ghi789",
    "status": "pending",
    "payment_method": "boleto",
    "boleto": {
      "url": "https://boleto.dompagamentos.com.br/...",
      "barcode": "34191.09008 64455.520144 95000.063305 1 99690000015000"
    }
  }
}

Tratamento de erros

Código	Causa	O que fazer
`400`	Cartão recusado	Exiba mensagem ao usuário; ofereça outro método de pagamento
`422`	Parâmetros inválidos	Verifique os campos obrigatórios e formatos esperados
`401`	Chave de API inválida	Confira as credenciais no painel

[!TIP] Use o ambiente Sandbox para testar todos os métodos sem movimentar dinheiro. O cartão 4012 8888 8888 1881 simula recusa.

Próximos passos

Tokenizando Cartões — salve cartões sem armazenar dados sensíveis
Configurando Webhooks — confirme pedidos automaticamente
Criar transação — todos os parâmetros disponíveis