Tema
Links de pagamento
O link de pagamento é uma página pronta (checkout) onde o cliente paga. O seu sistema cria o link e manda ao cliente o endereço de public_url.
Todas as chamadas desta página levam Authorization: Bearer SEU_TOKEN_DE_ACESSO. Veja Autenticação.
| Método | Caminho | Faz |
|---|---|---|
POST | /billing/payment-links | Cria um link |
GET | /billing/payment-links | Lista os links |
GET | /billing/payment-links/{external_id} | Consulta um link |
PUT | /billing/payment-links/{external_id} | Altera um link |
DELETE | /billing/payment-links/{external_id} | Remove um link |
GET | /billing/payment-links/{external_id}/payments | Lista os pagamentos do link |
GET | /billing/payment-links/{external_id}/paid-payments | Lista só os pagamentos pagos |
Use o external_id
Nos caminhos com identificador, use o external_id (texto no formato UUID) que volta na criação. O id numérico não funciona nesses caminhos.
Criar um link
http
POST /billing/payment-links
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Content-Type: application/json| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
title | texto | sim | Até 255 caracteres. O cliente vê. |
payment_methods | lista | sim | Pelo menos um: PIX, BOLETO, CARD. |
amount | número | sim, com valor fixo | Valor em reais. Mande sempre maior que 0. |
is_variable_amount | sim/não | não | true: o cliente escolhe o valor. Padrão false. |
min_amount | número | sim, com valor livre | Menor valor aceito. |
max_amount | número | não | Maior valor aceito. Maior que min_amount. |
description | texto | não | Texto livre. |
expires_at | data e hora | não | Validade do link. Precisa ser no futuro. |
max_uses | número | não | Quantos pagamentos o link aceita. Mínimo 1. Sem o campo: 1. null: sem limite. |
installments | número | não | Parcelas, de 1 a 12. |
pass_transaction_fee_to_customer | sim/não | não | true: a taxa da transação é cobrada do cliente. |
client_id | número | não | ID de um cliente da sua conta. A API só confere: o cliente não fica gravado no link. Cliente de outra conta volta 422. Veja Clientes. |
reference_code | texto | não | Seu código do pedido. Até 255. Sem o campo, a API gera REF-.... |
success_url | URL | não | Para onde o cliente vai depois de pagar. |
cancel_url | URL | não | Para onde o cliente vai se desistir. |
webhook_url | URL | não | Recebe os avisos do link. Só na criação: não muda depois. |
currency | texto | não | 3 letras. Padrão BRL. |
bash
curl -X POST https://v1.api.fastgivr.com.br/billing/payment-links \
-H "Authorization: Bearer SEU_TOKEN_DE_ACESSO" \
-H "Content-Type: application/json" \
-d '{
"title": "Pedido 12345",
"amount": 89.90,
"payment_methods": ["PIX", "BOLETO"],
"max_uses": 1,
"expires_at": "2026-11-30T23:59:00-03:00",
"reference_code": "PEDIDO-12345",
"success_url": "https://sualoja.exemplo.com.br/obrigado"
}'Resposta 201
json
{
"data": {
"id": 77,
"external_id": "9b1d3f5e-0000-0000-0000-000000000000",
"title": "Pedido 12345",
"amount": 89.9,
"is_variable_amount": false,
"payment_methods": [{ "value": "PIX", "label": "PIX" }, { "value": "BOLETO", "label": "BOLETO" }],
"status": { "value": "active", "label": "Ativo" },
"reference_code": "PEDIDO-12345",
"max_uses": 1,
"current_uses": 0,
"expires_at": "2026-12-01T02:59:00.000000Z",
"public_url": "https://checkout-gateway.fastgivr.com.br/9b1d3f5e-0000-0000-0000-000000000000"
},
"message": "Link de pagamento criado com sucesso."
}Exemplo resumido.
| Campo | O que é |
|---|---|
data.external_id | Identificador do link nas outras chamadas. Guarde. |
data.public_url | Endereço da página de pagamento. Mande ao cliente. |
data.status | Status do link. Ele nasce active e já aceita pagamento. |
data.current_uses | Quantos pagamentos o link já recebeu. |
Listar links
http
GET /billing/payment-links?status=active&page=1&per_page=50
Authorization: Bearer SEU_TOKEN_DE_ACESSO| Parâmetro | Regra |
|---|---|
search | Busca no título, na descrição ou no reference_code. |
status | Um status da tabela abaixo. |
id | O id numérico de um link. |
created_start / created_end | Data de criação. |
updated_start / updated_end | Data da última alteração. |
order | asc ou desc (padrão), pela data de criação. |
page | Página, a partir de 1. |
per_page | Itens por página: de 1 a 100. Padrão 15. |
A resposta traz os links em data, a paginação em meta e os totais por status em summary. Cada item de summary tem value, label, count e amount. summary.all soma todos.
Status do link
status.value | Quer dizer |
|---|---|
active | Aceita pagamento. |
paid | Pago. |
exhausted | Chegou em max_uses. Não aceita mais pagamento. |
expired | Passou de expires_at. |
canceled | Desligado pela conta. |
pending, draft, unknown | Outros estados. Trate como "não aceita pagamento". |
Consultar um link
http
GET /billing/payment-links/{external_id}
Authorization: Bearer SEU_TOKEN_DE_ACESSOResponde 200 com o link em data. O campo client vem null: o link não guarda o cliente. 404 se o link não existe ou é de outra conta.
Alterar um link
http
PUT /billing/payment-links/{external_id}
Authorization: Bearer SEU_TOKEN_DE_ACESSO
Content-Type: application/json
{ "status": "canceled" }Mande só os campos que mudam: title, description, status, amount, is_variable_amount, min_amount, max_amount, payment_methods, expires_at, max_uses, installments, pass_transaction_fee_to_customer, success_url e cancel_url. As regras são as da criação; amount e min_amount têm mínimo 0.01.
statusaceita sóactive(ligar) oucanceled(desligar).webhook_urlereference_codenão mudam depois de criados.
| Status | Quando | message |
|---|---|---|
422 | O link passou da validade. | Este link passou da validade e não pode ser editado. Crie um novo link. |
422 | O link já recebeu pagamento e o valor mudou. | Este link já recebeu pagamentos. Para outro valor, crie um novo link. |
422 | O link está paid ou exhausted e o status mudou. | Este link já foi pago e não pode mudar de status. |
404 | O link não existe ou é de outra conta. | — |
Deu certo: 200 com o link em data e a mensagem Link de pagamento atualizado com sucesso.
Remover um link
http
DELETE /billing/payment-links/{external_id}
Authorization: Bearer SEU_TOKEN_DE_ACESSOResponde 200 com Link de pagamento removido com sucesso. e o link sai da lista.
Prefira desligar
Para só parar de receber, use PUT com { "status": "canceled" }. O link continua na lista, com o histórico de pagamentos.
Pagamentos do link
http
GET /billing/payment-links/{external_id}/payments?status=paid&page=1&per_page=15
Authorization: Bearer SEU_TOKEN_DE_ACESSO| Parâmetro | Regra |
|---|---|
status | paid, pending, canceled ou failed. Sem o campo: todos. |
search | Busca no nome ou no e-mail de quem pagou. |
page / per_page | Paginação. Padrão 15 por página. |
json
{
"data": [
{
"id": 501,
"base_amount": 89.9,
"transaction_fee": 0,
"final_amount": 89.9,
"currency": "BRL",
"payer_name": "Cliente Exemplo",
"payer_email": "cliente@exemplo.com.br",
"payment_method": "PIX",
"status": "paid",
"created_at": "2026-11-10 13:45:00",
"charge": { "id": 1001, "code": "codigo-da-cobranca", "status": "paid", "payment_date": "2026-11-10T16:45:00.000000Z" }
}
],
"meta": { "total": 1, "page": 1, "limit": 15, "total_pages": 1, "has_next_page": false, "has_prev_page": false },
"summary": { "paid": { "count": 1, "amount": 89.9 } },
"message": "Pagamentos recuperados com sucesso."
}Exemplo resumido.
- Cada pagamento cria uma cobrança. Ela vem em
charge: consulte em Cobranças antes de dar baixa. summarysoma o link inteiro por status, não só a página.GET .../paid-paymentslista só os pagos. Não aceita filtros, sóper_page, e não trazchargenemsummary.