Documentação da API de Links de Pagamento - Cliente Final (Checkout)

Esta documentação detalha os endpoints públicos utilizados pela interface de checkout para processar pagamentos através de Links de Pagamento.

Base URL: /api/public

---

Endpoints Públicos

1. Visualizar Informações do Link

Recupera os detalhes básicos do link de pagamento e da conta associada para exibição no checkout. O sistema valida automaticamente se o link está expirado.

• Método: GET
• Rota: /paymentLink/\{external_id\}

Exemplo de Resposta (200 OK):

{
  "payment_link": {
    "id": 12,
    "external_id": "pl_65d8a0f1b2c3d",
    "title": "Doação para Projeto Social",
    "amount": 50.0,
    "is_variable_amount": true,
    "min_amount": 10.0,
    "max_amount": 5000.0,
    "installments": 1,
    "payment_methods": [
      { "value": "PIX", "label": "Pix" },
      { "value": "CARD", "label": "Cartão de Crédito" }
    ],
    "due_date": "2026-12-31 23:59:59",
    "status": { "value": "active", "label": "Ativo" },
    "description": "Sua contribuição ajuda milhares de pessoas.",
    "public_url": "https://checkout-gateway.fastgivr.com.br/pl_65d8a0f1b2c3d"
  },
  "account": {
    "name": "ONG Brasil Solidário",
    "email": "doe@ong.org.br",
    "document": "00.000.000/0001-91",
    "path_logo": "https://api.pague.me/storage/logos/logo_ong.png"
  }
}

---

2. Processar Pagamento

Gera a cobrança final e processa o pagamento. Toda a operação é executada sob transação para garantir integridade.

• Método: POST
• Rota: /paymentLink/\{external_id\}/pay

Parâmetros do Payload:

Campo	Tipo	Obrigatório	Descrição
payment_method	String	Sim	PIX, BOLETO ou CARD.
amount	Numeric	Sim*	Obrigatório se is_variable_amount for true no link.
name	String	Sim**	Nome do pagador.
document	String	Sim**	CPF/CNPJ do pagador.
email	String	Sim**	E-mail do pagador.
installments	Integer	Não	Parcelas (Obrigatório para CARD, min 1, max definido no link).
card	Object	Condicional	Dados do cartão (obrigatório para CARD).
address	Object	Condicional	Endereço de cobrança (obrigatório para CARD).

* Se o link for de valor fixo, o parâmetro amount é ignorado se enviado.
** Se client_id for fornecido, estes campos são carregados automaticamente.

Detalhes do Objeto card (exigido para CARD):

• cardholder_name: Nome conforme impresso no cartão.
• card_number: Número do cartão (apenas Visa e Mastercard são aceitos).
• expiry: Data de expiração (MM/YY).
• cvv: Código de segurança.

Detalhes do Objeto address (exigido para CARD):

• zipcode, street, number, district, city, state (sigla 2 letras).

---

3. Consultar Status do Pagamento

Utilizado pelo checkout para verificar a liquidação da cobrança.

• Método: GET
• Rota: /payment-status/\{charge_id\}/charge

Exemplo de Resposta (200 OK):

{
  "data": {
    "charge": {
      "id": 1024,
      "status_id": 2,
      "payment_method": "PIX",
      "value": 50.0
    },
    "pix": { "status": "CONCLUIDA", "txid": "789abc...", "qrcode": "..." },
    "account": { "name": "ONG Brasil", "path_logo": "..." }
  },
  "message": "Status da cobrança recuperado."
}

---

Tabela de Erros

Código	Descrição
410 Gone	Link expirado (verificação via status ou expires_at).
422 Unprocessable	Erro de validação nos campos (ex: parcelas excedidas).
404 Not Found	Link ou conta associada não encontrada.
500 Server Error	Erro interno (logado com link_id para rastreio).