Cobranças
Visão Geral
Entenda como funcionam cobranças na API SoarLabz
O que são Cobranças?
Cobranças representam transações de pagamento na SoarLabz. Cada cobrança está associada a um método de pagamento e segue um ciclo de vida específico.
Métodos de Pagamento
A API suporta os seguintes métodos:
| Método | Identificador | Descrição |
|---|---|---|
| Cartão de Crédito | credit_card | Pagamento com cartão de crédito, com suporte a parcelamento |
| Cartão de Débito | debit_card | Pagamento com cartão de débito, sem parcelamento |
| PIX | pix | Transferência instantânea via QR Code |
| Boleto | boleto | Boleto bancário com data de vencimento |
Ciclo de Vida
Status da Cobrança
| Status | Descrição |
|---|---|
pending | Cobrança criada, aguardando processamento |
authorized | Pagamento autorizado (cartão de crédito ou débito) |
captured | Pagamento capturado/confirmado |
partially_refunded | Estornada parcialmente |
refunded | Estornada totalmente |
voided | Cancelada antes da captura |
failed | Falha no processamento |
expired | Expirada (PIX ou boleto não pago no prazo) |
Fluxo por Método
Cartão de Crédito
- Criação - A cobrança é criada e o cartão é autorizado
- Autorização - O valor é reservado no limite do cartão (status
authorized) - Captura - O valor é efetivamente cobrado (status
captured)
Cartão de Débito
- Criação - A cobrança é criada e o cartão é autorizado
- Autorização - O valor é reservado no saldo do cartão (status
authorized) - Captura - O valor é debitado imediatamente (status
captured)
Cobranças de cartão de débito não suportam parcelamento — o valor é sempre cobrado em parcela única.
PIX
- Criação - A cobrança é criada e um QR Code é gerado
- Pagamento - O cliente paga via PIX e o status muda para
captured - Expiração - Se não pago no prazo, o status muda para
expired
Boleto
- Criação - A cobrança é criada e o boleto é gerado
- Pagamento - O cliente paga o boleto e o status muda para
captured - Expiração - Se não pago até o vencimento, o status muda para
expired
Estrutura Básica de uma Cobrança
Independente do método de pagamento, toda cobrança exige:
| Campo | Tipo | Descrição |
|---|---|---|
amount | integer | Valor em centavos (ex: R$ 100,00 = 10000) |
payment_method | string | Método de pagamento |
product_type | string | physical ou digital |
customer | object | Dados do cliente (nome, e-mail, CPF/CNPJ, telefone) |
items | array | Lista de itens do pedido |