Cobranças

Visão Geral

As Cobranças representam transações de pagamento únicas. São o núcleo do processamento de pagamentos da plataforma, suportando os métodos:

Método	Descrição
`CreditCard`	Cartão de crédito (parcelado ou à vista)
`PIX`	Pagamento instantâneo via PIX

Header obrigatório

Todas as rotas de cobranças exigem o header account com o código da conta:

account: acc_abc123xyz

Formato de resposta padrão

A maioria das rotas retorna respostas no formato padrão da API (exceto a listagem paginada):

{
  "mensagem": "Mensagem descritiva",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 200,
  "id": "00000000-0000-0000-0000-000000000000",
  "data": { ... }
}

Campo	Tipo	Descrição
`mensagem`	string	Mensagem descritiva da operação
`erro`	boolean	`false` em caso de sucesso, `true` em caso de erro
`mensagenserro`	array	Lista de mensagens de erro (vazia em caso de sucesso)
`codigoretorno`	integer	Código HTTP de retorno
`id`	string	ID do recurso criado/afetado ou GUID vazio
`data`	mixed	Dados retornados (objeto, array ou vazio)

Fluxo de uma cobrança

POST /v1/charge → HTTP 201
    │
    ├─ Validação de dados (422 se inválido)
    ├─ Verificação de fraude (bloqueio de IP/email/CPF/BIN)
    ├─ Rate limiting por cliente
    │
    ├─ [PIX] → QR Code gerado → aguardar pagamento (status: Pending)
    └─ [CreditCard] → Autorização no gateway
              │
              ├─ Approved → Pedido aprovado (HTTP 201)
              ├─ Declined → Pedido recusado (HTTP 400)
              └─ Challenged → Verificação adicional requerida (HTTP 202)

Campos do cliente

Campo	Tipo	Req.	Descrição
`client.name`	string	Sim	Nome completo do cliente (máx. 255)
`client.email`	string	Sim	E-mail do cliente
`client.phone.ddi`	string	Sim	Código do país (DDI)
`client.phone.ddd`	string	Sim	Código de área (DDD)
`client.phone.number`	string	Sim	Número do telefone
`client.document.type`	string	Não	Tipo: `CPF`, `CNPJ`, `passport`, `undefined`
`client.document.number`	string	Não	Número do documento
`client.gender`	string	Não	`Male`, `Female`, `Other`, `Undefined`
`client.birthdate`	date	Não	Data de nascimento (YYYY-MM-DD)
`client.address.*`	object	Não*	Endereço (* todos os campos obrigatórios entre si)

Campos do pagamento

Campo	Tipo	Req.	Descrição
`payment.type`	string	Sim	`CreditCard` ou `PIX`
`payment.pix_expiration`	integer	Não	Expiração em segundos (mín. 1)
`payment.card.card_token`	string	Não¹	Token de um cartão salvo. Se enviado, dispensa os dados do cartão
`payment.card.number`	string	CreditCard²	Número do cartão (mín. 13 dígitos)
`payment.card.name`	string	CreditCard²	Nome no cartão
`payment.card.month`	string	CreditCard²	Mês de validade (MM)
`payment.card.year`	string	CreditCard²	Ano de validade (YY)
`payment.card.security_code`	string	CreditCard²	CVV
`payment.card.installments`	integer	CreditCard	Número de parcelas
`payment.card.soft_descriptor`	string	Não	Texto na fatura (3-50 chars)

¹ Alternativa aos dados do cartão — veja Cartão salvo abaixo. ² Obrigatório apenas quando card_token não é enviado.

Cartão salvo (`card_token`)

Em vez de reenviar os dados do cartão a cada cobrança, você pode cobrar um cartão já salvo enviando apenas o payment.card.card_token. O card_token é o token retornado ao salvar o cartão (campo card_token, também entregue no evento card.token_created). Quando ele é enviado, os campos number, name, month, year e security_code tornam-se opcionais — você não precisa mais trafegar os dados do cartão.

Pagamento com cartão salvo

"payment": {
  "type": "CreditCard",
  "card": {
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "installments": 1
  }
}

O card_token só é aceito se o cartão pertencer à mesma conta da cobrança. Um card_token de outra conta é rejeitado com 422, assim como um cartão excluído ou inexistente.

Billing Address — o billing address do cartão não é tokenizado. Ao criar um pedido/cobrança com card_token, você também precisa informar o billing address (client.address) na requisição.

Continue enviando payment.card.installments (mín. 1) mesmo ao usar card_token — ele define o parcelamento desta cobrança.

Toda cobrança com cartão retorna o card_token do cartão em data.orders[].charges[].payment.card_token — tanto quando você envia card_token quanto quando envia os dados completos (nesse caso o cartão é salvo e o card_token gerado é devolvido). Guarde esse valor para reutilizar o cartão nas próximas cobranças. Em pagamentos sem cartão (ex.: PIX), card_token vem null.

Exemplo: Pagamento PIX

Request

{
  "client": {
    "name": "Maria Santos",
    "email": "maria@exemplo.com.br",
    "phone": { "ddi": "55", "ddd": "21", "number": "988887777" }
  },
  "payment": {
    "type": "PIX",
    "pix_expiration": 3600
  },
  "items": [
    { "id": "curso_001", "description": "Curso Online", "amount": 297.00, "quantity": 1 }
  ]
}

Resposta PIX (HTTP 201)

{
  "mensagem": "Aguardando Pagamento",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 201,
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "charge_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "code": "pur_abc123xyz",
    "status": "Pending",
    "value": 297.00,
    "orders": [
      {
        "code": "ord_abc123xyz",
        "status": "Pending",
        "charges": [
          {
            "code": "chg_abc123",
            "status": "Pending",
            "payment": {
              "code": "pix_code_123",
              "copy_paste": "00020126580014br.gov.bcb.pix...",
              "expiration": "2026-03-11T11:00:00.000000Z",
              "payment_type": "PIX"
            }
          }
        ]
      }
    ]
  }
}

Para pagamentos PIX, o status inicial será Pending. Use webhooks para ser notificado quando o pagamento for confirmado.

A criação de cobranças passa por verificações de fraude. Clientes com IP, e-mail, CPF ou BIN do cartão bloqueados terão a cobrança rejeitada com status 400.

Estorno de cobranças

O endpoint de estorno aceita um campo value opcional do tipo inteiro (em centavos). Se omitido, o estorno é total.

Estorno parcial de R$ 50,00

{
  "value": 5000
}

O prazo e as condições para estorno dependem do gateway de pagamento utilizado. Cobranças já estornadas por completo não podem ser estornadas novamente.

Autenticação

Pedidos

Cartões

Assinaturas

Faturas

Links de Pagamento

Análise de Fraude

Webhooks

Cobranças

Visão Geral

Header obrigatório

Formato de resposta padrão

Fluxo de uma cobrança

Campos do cliente

Campos do pagamento

Cartão salvo (`card_token`)

Exemplo: Pagamento PIX

Estorno de cobranças

​Visão Geral

​Header obrigatório

​Formato de resposta padrão

​Fluxo de uma cobrança

​Campos do cliente

​Campos do pagamento

​Cartão salvo (card_token)

​Exemplo: Pagamento PIX

​Estorno de cobranças

Visão Geral

Header obrigatório

Formato de resposta padrão

Fluxo de uma cobrança

Campos do cliente

Campos do pagamento

Cartão salvo (`card_token`)

Exemplo: Pagamento PIX

Estorno de cobranças