Desenvolvedores · Documentação da API

Cobranças

Parcelas, dados para pagar, 2ª via e resumo financeiro do aluno pela API do EduPay.

As cobranças do EduPay são as parcelas de cada matrícula. Cada parcela tem valor, vencimento, forma de pagamento e, enquanto pode ser paga, os dados para pagar: linha digitável e link do boleto, PIX copia e cola ou link de pagamento do cartão.

Consultar parcelas

GET /installments (billing:read) aceita enrollment_id, student_id, status, período de vencimento (due_from, due_to) e período de pagamento (paid_from, paid_to), todos em AAAA-MM-DD, além de updated_since.

curl "https://edupay.estudiosite.com/api/v1/installments?status=overdue&due_to=2026-10-31&limit=100" \
  -H "Authorization: Bearer $EDUPAY_KEY"

GET /installments/{id} traz uma parcela e, no caso do PIX, também a imagem do QR Code em payment.pix_qr_code_base64 (só no detalhe, para a lista não ficar pesada).

Situações da parcela

status Quer dizer Tem payment?
open Em aberto, ainda não venceu Sim, se a cobrança já foi emitida
overdue Venceu sem pagamento Sim
outstanding Dívida que ficou de matrícula cancelada Sim
paid Paga (pelo banco, pelo cartório ou baixa manual da escola) Não
cancelled Cancelada (inclusive a que foi trocada por 2ª via) Não
waived Dispensada pela escola Não

O objeto payment só aparece enquanto a parcela pode ser paga:

"payment": {
  "barcode": "23793.38128 60000.000003 ...",
  "boleto_url": "https://...",
  "pix_copy_paste": "00020126...",
  "payment_url": "https://checkout.stripe.com/...",
  "expires_at": "2026-11-12T02:59:59Z"
}

Campo sem valor vem null: um boleto não tem payment_url, um link de cartão não tem barcode. Parcela em aberto ainda sem cobrança emitida (boleto e PIX saem poucos dias antes do vencimento) vem com os campos null — consulte de novo mais perto do vencimento ou espere o aviso installment.charge_issued.

Valores em centavos, com a moeda em currency. paid_amount é o valor que entrou de fato.

Resumo financeiro do aluno

GET /students/{id}/summary (billing:read) soma tudo o que o aluno ainda pode pagar, em todas as matrículas, inclusive dívida de matrícula cancelada:

{
  "data": {
    "student_id": 532, "currency": "BRL",
    "open_installments": 3, "overdue_installments": 1,
    "amount_due": 135000, "amount_overdue": 45000,
    "next_installment": { "id": 9813, "due_date": "2026-11-10", "amount": 45000 },
    "active_enrollments": 1, "contract_status": "signed"
  }
}

Bom para mostrar a situação do aluno em outro sistema (área do aluno, atendimento, CRM) sem baixar todas as parcelas.

2ª via

POST /installments/{id}/second-copy (billing:write) faz o mesmo que o botão do painel: cancela a parcela atual junto com a cobrança no banco e cria outra, com cobrança nova e e-mail ao aluno. A nova traz em replaces_installment_id o número da anterior.

curl -X POST https://edupay.estudiosite.com/api/v1/installments/9813/second-copy \
  -H "Authorization: Bearer $EDUPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2via-9813-2026-11-20" \
  -d '{"due_date": "2026-11-20"}'
  • Sem due_date, a 2ª via vence em 3 dias. A data vale de hoje em diante, no fuso da escola.
  • O valor não muda pela API.
  • Só parcela em aberto, vencida ou em dívida (409 com code installment_not_payable nas outras).
  • Boleto ainda dentro da validade não pode ser cancelado no banco: 409 com code boleto_still_valid, e o motivo em detail.
  • Escola sem conta de recebimento conectada: 409 com code gateway_not_connected.
  • Se o banco recusar, a resposta é 502 com code gateway_error. Se vier installment_id, a 2ª via foi criada e a cobrança dela é emitida de novo automaticamente.

Saber do pagamento na hora

Em vez de consultar as parcelas de tempos em tempos, cadastre um endereço para o aviso installment.paid. Ele chega segundos depois da confirmação, venha ela do banco, do cartório ou de uma baixa manual da escola. Veja Avisos automáticos.