Tema
Cobranças
A cobrança é o pedido de pagamento para um cliente. Pela API ela pode ser:
payment_method | O cliente recebe |
|---|---|
PIX | Um QR Code Pix (código copia e cola). |
BOLETO | Um boleto registrado no banco. |
BOLEPIX | Um boleto com QR Code Pix. Paga com qualquer um dos dois. |
Todas as chamadas desta página levam Authorization: Bearer SEU_TOKEN_DE_ACESSO. Veja Autenticação.
| Método | Caminho | Faz |
|---|---|---|
POST | /billing/charges | Cria uma cobrança |
GET | /billing/charges/{id} | Consulta uma cobrança |
GET | /billing/charges | Lista as cobranças |
PUT | /billing/charges/{id} | Altera uma cobrança pendente |
DELETE | /billing/charges/{id} | Apaga uma cobrança |
POST | /billing/charges/{id}/notify | Avisa o cliente da cobrança |
GET | /billing/charges/{id}/download-pdf | Baixa o PDF da cobrança |
GET | /enums/charge-status | Lista os status |
Outros caminhos para o mesmo recurso
/invoices e /invoicesv2 são apelidos de /billing/charges: mesmas regras e mesmos campos. Só a listagem em /invoices usa outro formato de paginação. Use /billing/charges em integrações novas.
Criar uma cobrança
http
POST /billing/charges
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Content-Type: application/json
Idempotency-Key: pedido-12345O cabeçalho Idempotency-Key é opcional, mas recomendado. Ele evita cobrança duplicada quando o seu sistema repete a chamada. Veja Idempotência.
Corpo: dados da cobrança
| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
payment_method | texto | sim | PIX, BOLETO ou BOLEPIX. |
value | número | sim (ou amount) | Valor em reais. Mínimo 0.01. |
amount | número | sim (ou value) | Mesmo que value. Mande um dos dois. |
due_date | data | sim | Vencimento, AAAA-MM-DD. Hoje ou depois. |
webhook | texto | não | URL válida que recebe o aviso de pagamento. Veja Webhooks. |
description | texto | não | Até 500 caracteres. |
details | texto | não | Detalhes livres da cobrança. |
instructions | texto | não | Instruções livres. |
Corpo: cliente
Mande um destes dois jeitos:
Jeito 1 — cliente já cadastrado:
| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
client_id | número | sim | ID de um cliente da sua conta. Cliente de outra conta volta 422. Veja Clientes. |
Jeito 2 — dados do cliente na própria cobrança:
| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
name | texto | sim | Até 200 caracteres. |
email | texto | sim | E-mail válido. |
document | texto | sim | CPF ou CNPJ do cliente. |
phone | texto | não | Telefone. |
No jeito 2, a API procura na sua conta um cliente com o mesmo document:
- achou: usa esse cliente e atualiza nome, e-mail e telefone;
- não achou: cadastra um cliente novo.
Mande o documento sempre no mesmo formato
A busca compara o texto do document como foi enviado. Escolha um formato (por exemplo, só números: 00000000000) e use sempre o mesmo, para não cadastrar o mesmo cliente duas vezes.
Boleto precisa de CPF/CNPJ
Em BOLETO e BOLEPIX, o cliente precisa ter CPF ou CNPJ. Se o client_id for de um cliente sem documento, a resposta é 422 no campo document.
Corpo: juros, multa e desconto (só boleto)
Valem para BOLETO e BOLEPIX. Valor 0 ou ausente = sem juros, sem multa ou sem desconto.
| Campo | Tipo | Regra |
|---|---|---|
amount_rate | número | Juros após o vencimento. Mínimo 0. |
type_rate | texto | PERCENTAGE (padrão): % ao mês. ABSOLUTE: reais por dia de atraso. |
late_fee | número | Multa após o vencimento. Mínimo 0. |
late_fee_type | texto | PERCENTAGE (padrão) ou ABSOLUTE (reais). |
discount | número | Desconto para pagamento antecipado. Mínimo 0. |
type_discount | texto | ABSOLUTE (padrão, reais) ou PERCENTAGE. |
days_discount | número | Quantos dias antes do vencimento o desconto acaba. A data resultante não pode ser antes de hoje. |
Percentual (PERCENTAGE) acima de 100 é recusado com 422. Juros e multa começam a contar no dia seguinte ao vencimento.
Exemplo: BolePix com cliente novo
bash
curl -X POST https://v1.api.fastgivr.com.br/billing/charges \
-H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-12345" \
-d '{
"payment_method": "BOLEPIX",
"value": 150.90,
"due_date": "2026-11-30",
"description": "Pedido 12345",
"webhook": "https://seusistema.exemplo.com.br/webhooks/fastgivr",
"name": "Cliente Exemplo",
"email": "cliente@exemplo.com.br",
"document": "00000000000",
"late_fee": 2,
"late_fee_type": "PERCENTAGE",
"amount_rate": 1,
"type_rate": "PERCENTAGE"
}'js
async function createCharge(order) {
const token = await getValidToken(); // see the Authentication page
const response = await fetch('https://v1.api.fastgivr.com.br/billing/charges', {
method: 'POST',
headers: {
Authorization: `Bearer ${token}`,
'Content-Type': 'application/json',
'Idempotency-Key': `order-${order.id}`,
},
body: JSON.stringify({
payment_method: 'BOLEPIX',
value: order.total,
due_date: order.dueDate, // 'YYYY-MM-DD'
description: `Order ${order.id}`,
webhook: 'https://seusistema.exemplo.com.br/webhooks/fastgivr',
name: order.customer.name,
email: order.customer.email,
document: order.customer.document,
}),
});
const body = await response.json();
if (response.status !== 201 && response.status !== 200) {
throw new Error(`Charge not created: HTTP ${response.status} ${body.message ?? ''}`);
}
return body.data; // charge
}Resposta 201
A cobrança criada vem dentro de data. Exemplo resumido:
json
{
"data": {
"id": 1001,
"code": "codigo-da-cobranca-32-caracteres",
"amount": 150.9,
"value": 150.9,
"amount_paid": 0,
"payment_method": "BOLEPIX",
"description": "Pedido 12345",
"due_date": "2026-11-30T03:00:00.000000Z",
"payment_date": null,
"pix_id": 2001,
"boleto_id": 3001,
"status": { "id": 1, "title": "pending", "description": "Pendente" },
"pix": {
"id": 2001,
"txid": "TXID_DO_PIX",
"qrcode": "CODIGO_PIX_COPIA_E_COLA",
"amount": 150.9,
"status": 0,
"paid_amount": 0,
"payment_date": null
},
"boleto": {
"boleto_id": 3001,
"txid": "TXID_DO_BOLETO",
"barcode": "CODIGO_DE_BARRAS_DO_BOLETO",
"digitable_line": null,
"status": 0,
"amount": "150.90",
"paid_amount": null,
"webhook": "https://seusistema.exemplo.com.br/webhooks/fastgivr",
"terms": {
"amount_rate": 1,
"type_rate": "PERCENTAGE",
"late_fee": 2,
"late_fee_type": "PERCENTAGE",
"discount": null,
"days_discount": null,
"type_discount": null
},
"path_pdf": "https://ENDERECO_DO_PDF_DO_BOLETO.pdf"
},
"splits": [],
"timestamps": {
"due_date": { "raw": "...", "formatted": "30/11/2026 00:00:00", "iso": "...", "human": "..." },
"created_at": { "raw": "...", "formatted": "...", "iso": "...", "human": "..." }
}
}
}Campos mais usados:
| Campo | O que é |
|---|---|
data.id | ID da cobrança. Guarde: é usado para consultar e alterar. |
data.code | Código da cobrança (texto). Também serve para consultar. |
data.status | Status atual. Veja Status da cobrança. |
data.pix.qrcode | Código Pix copia e cola. Gere a imagem do QR Code a partir dele. |
data.pix.txid | Identificador do Pix. Vem no webhook de pagamento. |
data.boleto.barcode | Código de barras do boleto. |
data.boleto.digitable_line | Linha digitável. Pode vir vazia (null): use barcode ou o PDF. |
data.boleto.path_pdf | Link do PDF do boleto. |
data.boleto.txid | Identificador do boleto. |
pix aparece em PIX e BOLEPIX. boleto aparece em BOLETO e BOLEPIX. Quando não existe, vem null.
O cliente pode receber um e-mail
Ao criar a cobrança, o cliente pode receber um e-mail com ela. Isso depende das regras de aviso aos clientes configuradas na conta, no portal.
Validade do QR Code Pix
Informação ainda não publicada — fale com o suporte.
Erros ao criar
| Status | Quando |
|---|---|
422 | Campo faltando ou inválido. Os detalhes vêm por campo em errors. Veja Erros. |
409 | Repetição de uma cobrança que ainda está sendo criada, ou cujo resultado está em verificação. Veja Idempotência. |
4xx ou 5xx | O banco recusou o Pix ou o boleto. A mensagem do banco vem em message. |
500 | Erro inesperado. A mensagem vem em message. |
Não confie só no campo success
Quando o banco recusa a emissão, a resposta pode vir com status de erro e "success": true. Use sempre o status HTTP: só 200 e 201 são sucesso.
Quando a criação falha depois de começar, a cobrança pode ficar registrada na sua lista com o status failed. Ela não tem Pix nem boleto para pagar.
Consultar uma cobrança
http
GET /billing/charges/{id}
Authorization: Bearer SEU_TOKEN_DE_ACESSO{id} é o id numérico da cobrança ou o code dela.
bash
curl https://v1.api.fastgivr.com.br/billing/charges/1001 \
-H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"Resposta 200
json
{
"code": 200,
"success": true,
"data": {
"id": 1001,
"code": "codigo-da-cobranca-32-caracteres",
"amount": 150.9,
"amount_paid": 150.9,
"payment_method": "PIX",
"payment_date": "2026-11-10T13:45:00.000000Z",
"status": { "id": 2, "title": "paid", "description": "Pago" },
"client": {
"client_id": 501,
"name": "Cliente Exemplo",
"email": "cliente@exemplo.com.br",
"document": { "formatted": "000.000.000-00", "raw": "00000000000" }
},
"pix": { "txid": "TXID_DO_PIX", "status": 1, "paid_amount": 150.9 },
"boleto": null,
"splits": []
},
"message": "Detalhes da Cobrança"
}O data tem os mesmos campos da criação, mais client. Exemplo resumido.
Use esta consulta para confirmar um pagamento antes de dar baixa no seu sistema: data.status.title igual a paid e data.amount_paid com o valor pago.
| Status | Quando |
|---|---|
404 | A cobrança não existe ou é de outra conta. message: Cobrança não encontrada. |
Listar cobranças
http
GET /billing/charges?status_id=2&due_date_start=2026-11-01&due_date_end=2026-11-30&page=1&per_page=50
Authorization: Bearer SEU_TOKEN_DE_ACESSOFiltros (query string)
| Parâmetro | Tipo | Regra |
|---|---|---|
search | texto | Até 100 caracteres. Busca no nome, e-mail ou documento do cliente. |
status_id | texto | Um ou mais IDs de status separados por vírgula: 1,2. Veja Status. |
payment_method | texto | Um ou mais, separados por vírgula: PIX,BOLEPIX. |
client_id | número | Só as cobranças desse cliente. |
created_at_start / created_at_end | data | Criação, AAAA-MM-DD. |
due_date_start / due_date_end | data | Vencimento, AAAA-MM-DD. |
payment_date_start / payment_date_end | data | Pagamento, AAAA-MM-DD. |
order_by | texto | created_at, due_date, payment_date ou id (padrão). |
order_dir | texto | asc ou desc (padrão). |
page | número | Página, a partir de 1. |
per_page | número | Itens por página: de 1 a 500. Padrão 15. |
Resposta 200
json
{
"data": [
{ "id": 1001, "code": "codigo-da-cobranca-32-caracteres", "amount": 150.9, "status": { "id": 2, "title": "paid", "description": "Pago" } }
],
"meta": {
"total": 120,
"page": 1,
"limit": 50,
"total_pages": 3,
"has_next_page": true,
"has_prev_page": false
}
}Cada item de data tem os campos da cobrança (exemplo resumido). Para buscar todas as páginas, repita a chamada com page + 1 enquanto meta.has_next_page for true.
Alterar uma cobrança
http
PUT /billing/charges/{id}
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Content-Type: application/json{id} é o id ou o code. Só altera cobrança com status pendente (pending). Mande só os campos que quer mudar.
| Campo | Tipo | Regra |
|---|---|---|
due_date | data | Novo vencimento, AAAA-MM-DD. Hoje ou depois. O Pix e o boleto são atualizados no banco. |
description | texto | Até 500 caracteres. |
details | texto | Texto livre. |
instructions | texto | Texto livre. |
webhook | texto | Nova URL de aviso. |
amount_rate, type_rate | número, texto | Juros do boleto. Mesmas regras da criação. 0 remove. |
late_fee, late_fee_type | número, texto | Multa do boleto. 0 remove. |
discount, type_discount, days_discount | número, texto, número | Desconto do boleto. days_discount de 0 a 365. 0 remove o desconto. |
O valor não muda depois de emitido
Cobrança com Pix ou boleto já emitido não aceita valor novo (422 no campo amount). Para cobrar outro valor, crie uma nova cobrança.
Juros, multa e desconto só existem em cobranças com boleto em aberto. Em outros casos a resposta é 422 no campo late_fee.
bash
curl -X PUT https://v1.api.fastgivr.com.br/billing/charges/1001 \
-H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
-H "Content-Type: application/json" \
-d '{ "due_date": "2026-12-15" }'Resposta 200
json
{
"code": 200,
"success": true,
"charge": {
"id": 1001,
"code": "codigo-da-cobranca-32-caracteres",
"value": "150.90",
"due_date": "2026-12-15T03:00:00.000000Z",
"status_id": 1
},
"message": "Cobrança atualizada com sucesso!"
}Atenção: aqui a cobrança vem na chave charge (não em data), com os campos gravados da cobrança. Para ter o formato completo, consulte com GET /billing/charges/{id}.
Erros ao alterar
| Status | Quando |
|---|---|
404 | A cobrança não existe ou é de outra conta. |
422 | Campo inválido, valor bloqueado, vencimento antes de hoje, ou o banco recusou a alteração. Detalhes por campo em errors ou em data. Veja Erros. |
500 | A cobrança não está pendente (por exemplo, já paga), ou erro inesperado. |
Apagar uma cobrança
http
DELETE /billing/charges/{id}
Authorization: Bearer SEU_TOKEN_DE_ACESSO{id} é o id ou o code. A cobrança passa para o status DELETED e a resposta é 200 com message Cobrança apagado com sucesso!.
Antes de apagar, a API:
- Recusa a cobrança paga:
422comEsta cobrança já foi paga e não pode ser excluída. - Recusa a cobrança cancelada:
422comEsta cobrança já foi excluída ou cancelada. - Cancela o Pix no banco: o QR Code deixa de valer. Se o banco não responder, volta
422comNão foi possível cancelar o Pix no banco. Nada foi alterado; tente novamente. - Cancela o boleto no banco (baixa). Se o banco não responder, volta
422e a cobrança fica. Tente de novo.
Depois disso, ninguém consegue mais pagar o Pix nem o boleto da cobrança.
404se a cobrança não existe, é de outra conta ou já foi apagada.
Avisar o cliente
Manda de novo a cobrança para o cliente, por e-mail ou SMS.
http
POST /billing/charges/{id}/notify
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Content-Type: application/json
{ "channels": ["email"], "message": "Seu boleto vence amanhã." }| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
channels | lista | sim | Um ou mais: email, sms. |
message | texto | não | Recado junto com a cobrança. Até 1000 caracteres. |
Para avisar várias cobranças de uma vez, use POST /billing/charges/notify com os IDs ou códigos em ids: { "ids": [1001, 1002], "channels": ["email"] }.
Resposta 200:
json
{
"code": 200,
"success": true,
"data": { "count": 1 },
"message": "Notificações enfileiradas com sucesso!"
}Na message você pode usar marcadores, trocados pelos dados de cada cobrança:
| Marcador | Vira |
|---|---|
:name | Nome do cliente. |
:value | Valor, como R$ 150,90. |
:due_date | Vencimento, como 30/11/2026. |
:code | Código da cobrança. |
:link | Link para pagar. |
:account_name | Nome da sua conta. |
:date | Data de hoje. |
Sem message, o texto padrão lembra o vencimento.
data.count é o número de cobranças avisadas. O envio acontece logo depois, em segundo plano.
- O e-mail vai para o e-mail do cliente; o SMS, para o telefone dele. Cliente sem e-mail ou sem telefone não recebe por esse canal.
whatsappé aceito, mas está desligado: nada é enviado por ele.400: nenhuma cobrança informada.404: nenhuma cobrança da conta com esses IDs.422:channelsfaltando ou com valor inválido. Aqui os detalhes por campo vêm emdata, não emerrors.
Baixar o PDF
http
GET /billing/charges/{id}/download-pdf
Authorization: Bearer SEU_TOKEN_DE_ACESSOResponde o arquivo PDF da cobrança (Content-Type: application/pdf), como anexo com o nome fatura_{id}.pdf.
bash
curl -o fatura.pdf https://v1.api.fastgivr.com.br/billing/charges/1001/download-pdf \
-H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"Status da cobrança
O status vem em data.status: id, title e description.
title | description | Quer dizer |
|---|---|---|
pending | Pendente | Aguardando pagamento. |
paid | Pago | Pago. Veja amount_paid e payment_date. |
canceled | Cancelado | Cancelada. |
failed | Falhou | A emissão falhou. Não há o que pagar. |
DELETED | Deletado | Apagada. |
A lista completa, com os IDs, vem de uma chamada sem token:
bash
curl https://v1.api.fastgivr.com.br/enums/charge-statusjson
[
{ "id": 1, "title": "pending", "description": "Pendente" },
{ "id": 2, "title": "paid", "description": "Pago" }
]Compare pelo title
No seu sistema, decida pelo title (paid, pending...). Use o id só nos filtros da listagem, depois de ler a lista acima.
Dividir o recebimento (split)
Uma cobrança Pix pode repassar parte do valor para outras contas FastGivr. O repasse acontece quando o Pix é pago.
Mande o campo splits na criação:
json
{
"payment_method": "PIX",
"value": 100.00,
"due_date": "2026-11-30",
"client_id": 501,
"splits": [
{ "account": "NUMERO_DA_CONTA_DESTINO", "document": "00000000000000", "type": "PERCENTAGE", "value": 10 }
]
}| Campo | Tipo | Regra |
|---|---|---|
splits | lista | Até 10 recebedores. |
splits[].account | texto | Número da conta FastGivr que recebe. Até 30 caracteres. |
splits[].document | texto | CPF ou CNPJ do dono dessa conta. Até 20 caracteres. |
splits[].type | texto | PERCENTAGE ou ABSOLUTE (reais). |
splits[].value | número | Mínimo 0.01. Percentual até 100. |
Regras:
- só em
PIX, sem parcelamento; - o usuário de API precisa da permissão de gerenciar splits na conta;
- a conta de destino precisa estar ativa e ser outra conta, sem repetir;
- a soma dos repasses precisa caber no valor líquido: a taxa do Pix fica com quem emite a cobrança.
Se uma regra falhar, a resposta é 422 com o motivo no campo splits. Mais sobre o split no portal: Split de cobranças.