Endpoints

Todos os caminhos abaixo são relativos a https://api.gaudpay.com.br. Escritas (POST, PUT) aceitam o cabeçalho Idempotency-Key.

Visão geral

6.1 Clientes

Toda cobrança avulsa (POST /payments) precisa de um cliente. No link de pagamento, o cliente é opcional: quem paga se identifica na própria página.

POST /customers

{
  "first_name": "Maria",
  "last_name": "Souza",
  "document": "12345678909",
  "phone": "51999990000",
  "email": "maria@exemplo.com.br",
  "street": "Rua das Flores",
  "number": "100",
  "neighborhood": "Centro",
  "city": "Porto Alegre",
  "state": "RS",
  "zip_code": "90000000"
}

Obrigatórios: first_name, last_name, document (CPF/CNPJ, só números), phone, email. O endereço é opcional para Pix, mas obrigatório e completo (rua, número, bairro, cidade, UF e CEP) para boleto e cartão.

Resposta 201:

{
  "id": 4821,
  "merchant_id": 77,
  "first_name": "Maria",
  "last_name": "Souza",
  "document": "12345678909",
  "phone": "51999990000",
  "email": "maria@exemplo.com.br",
  "street": "Rua das Flores",
  "number": "100",
  "complement": null,
  "neighborhood": "Centro",
  "city": "Porto Alegre",
  "state": "RS",
  "zip_code": "90000000"
}

6.2 Links de pagamento

Um link de pagamento abre um checkout hospedado. É a forma recomendada de receber por Pix e por cartão: o Gaud Pay exibe o QR Code do Pix, faz a autenticação 3DS e trata os dados do cartão, sem que eles passem pelo seu sistema.

POST /payment-links

Importante sobre o parcelamento: o pagador não paga juros. O valor da cobrança é sempre o valor cheio, e o custo do parcelamento fica com o lojista.

Resposta 201:

{
  "id": 912,
  "merchant_id": 77,
  "customer_id": null,
  "amount_cents": 15990,
  "description": "Pedido 1001",
  "allowed_methods": ["PIX", "BOLETO", "CARD"],
  "max_installments": 3,
  "public_token": "k3Hq...Zp9",
  "status": "OPEN",
  "created_at": "2026-10-10T14:30:00Z"
}

O endereço para o cliente é https://app.gaudpay.com.br/pay/{public_token}.

6.3 Cobranças

Use POST /payments para cobranças avulsas ligadas a um cliente.

POST /payments

Resposta 201:

{
  "id": 30511,
  "merchant_id": 77,
  "customer_id": 4821,
  "subscription_id": null,
  "amount_cents": 15990,
  "payment_method": "BOLETO",
  "status": "PENDING",
  "retry_count": 0,
  "due_date": "2026-10-13T00:00:00Z",
  "installments": null
}

Importante — qual meio usar por qual caminho:

Meio	Pela cobrança avulsa (POST /payments)	Pelo link de pagamento
Boleto	✅ Devolve a linha digitável, o código de barras e o PDF (GET /payments/{id}/boleto)	✅
Pix	⚠️ A cobrança é criada, mas a API não devolve o código copia e cola nem o QR Code	✅ Recomendado: o checkout exibe o QR Code
Cartão	⚠️ Exige um token de cartão que a API pública não emite	✅ Recomendado: checkout hospedado com 3DS

Para Pix e cartão, use o link de pagamento.

Consultar e listar

curl https://api.gaudpay.com.br/payments/30511 \
  -H "Authorization: Bearer $GAUDPAY_TOKEN"

GET /payments aceita os filtros descritos em Paginação e Filtros.

Alterar — PUT /payments/{id} com amount_cents e/ou due_date. Só é possível enquanto a cobrança está PENDING e não há tentativa de cobrança em andamento; caso contrário a resposta é 409.

Estornar — POST /payments/{id}/refund. Somente cobranças de cartão podem ser estornadas pela API, e o estorno segue as regras do processador de pagamentos (prazo e dia da liquidação). Pix e boleto não são estornados por aqui.

Comprovante — GET /payments/{id}/receipt:

{
  "payment_id": 30511,
  "amount_cents": 15990,
  "payment_method": "BOLETO",
  "paid_at": "2026-10-12T17:02:11Z",
  "gateway_transaction_id": "8f3c..."
}

6.4 Boleto

Para BOLETO, envie o objeto de configuração (boleto em POST /payments, boleto_config em POST /payment-links):

{
  "issue_date": "2026-10-10",
  "document_kind": "DM",
  "days_until_expiration": 3,
  "interest_percentage": "1.00",
  "fine": { "percentage": "2.00", "quantity_days": 1 },
  "messages": ["Não receber após o vencimento"]
}

GET /payments/{id}/boleto

{
  "payment_id": 30511,
  "digitable_line": "23793.38128 60000.000003 00000.000400 1 98765000015990",
  "barcode": "23791987650000159903812860000000000000000400",
  "pdf_url": "https://..."
}

6.5 Extrato, saldo e repasses

GET /statements/balance — valores em centavos:

{
  "total_balance_cents": 150000,
  "blocked_balance_cents": 5000,
  "available_balance_cents": 145000
}

GET /statements/entries?period=2026-10 — lançamentos do mês (AAAA-MM; sem o parâmetro, o mês atual):

{
  "period": "2026-10",
  "entries": [
    {
      "type": "CHARGE",
      "modality": "PIX",
      "occurred_at": "2026-10-03T10:00:00Z",
      "description": "Cobrança #30511",
      "amount_cents": 15990,
      "status": "PAID",
      "running_balance_cents": 146500
    }
  ]
}

GET /statements/settlements — repasses (liquidações):

{
  "total": 1,
  "items": [
    {
      "id": "s_1",
      "amount_cents": 25000,
      "transactions_count": 4,
      "status": "PAID",
      "settled_at": "2026-10-10T15:00:00Z",
      "created_at": "2026-10-09T12:00:00Z"
    }
  ]
}

GET /statements/future-releases — valores a receber nos próximos 7, 15 e 30 dias, e por mês.