Pular para o conteúdo principal

Como pagar um empréstimo via API?

Para pagar uma parcela, um conjunto de parcelas ou o empréstimo inteiro, use o endpoint POST /api/v1/loan/operation/{id}/payoff. Requer o escopo LOAN_OPERATION_POST. Em {id} vai o operationId devolvido na originação.

A chamada emite uma cobrança Pix dinâmica pelo valor pedido e devolve o código copia e cola. Quem paga pode ser o tomador, ou a sua própria empresa, da conta dela. Nenhum endpoint marca parcela como paga: a baixa acontece quando o Pix é pago, da parcela mais antiga para a mais nova. Consulte a operação depois para ver paid virar true e outstanding cair.

Campos do corpo​

CampoTipoObrigatórioDescrição
scopestringSimNEXT cobra a próxima parcela em aberto, INSTALLMENTS cobra as parcelas em seqs, ALL cobra todo o saldo devedor.
seqsinteger[]Só em INSTALLMENTSNúmeros das parcelas (seq). Precisam ser contíguas e começar na primeira parcela não paga.
amountintegerNãoQuanto da dívida a cobrança abate, em centavos, de 1 até o que falta nas parcelas pedidas. Omitido, cobra tudo o que falta nelas.
datestringNãoDia (YYYY-MM-DD) para o qual a cobrança é calculada, hoje ou no futuro. Multa e juros de atraso são os desse dia. Omitido, é hoje.
customerobjectNãoQuem paga, para aparecer na cobrança: name (obrigatório), email e phone. O documento é sempre o do tomador.
extrasobject[]NãoAté 5 valores somados à cobrança e repassados a outras contas Woovi quando ela é paga. Veja Cobrar outros valores junto.

Regras​

  • Uma cobrança viva por parcela. Enquanto houver uma cobrança em aberto que cubra uma parcela, um novo pedido que a inclua é recusado com CHARGE_OVERLAPS. Pague ou espere a cobrança expirar.
  • Da mais antiga para a mais nova. Pedir as parcelas 2 e 3 com a 1 em aberto é recusado com PREVIOUS_INSTALLMENT_UNPAID.
  • O valor é o que falta. Uma parcela paga em parte entra pelo restante.
  • Só depois do dinheiro sair. Antes de disbursement.status chegar a CONFIRMED, a recusa é DISBURSEMENT_NOT_CONFIRMED.
  • Repetir o pedido com a mesma cobrança ainda aberta devolve a mesma cobrança, com o mesmo txid.

Exemplos em código​

# Próxima parcela
curl 'https://api.woovi.com/api/v1/loan/operation/6abd072eccca077d96ad9e20/payoff' -X POST \
-H "Content-Type: application/json" \
-H "Authorization: {SEU_APP_ID}" \
-d '{ "scope": "NEXT" }'

# Parcelas 1 e 2
curl 'https://api.woovi.com/api/v1/loan/operation/6abd072eccca077d96ad9e20/payoff' -X POST \
-H "Content-Type: application/json" \
-H "Authorization: {SEU_APP_ID}" \
-d '{ "scope": "INSTALLMENTS", "seqs": [1, 2] }'

# Tudo o que falta
curl 'https://api.woovi.com/api/v1/loan/operation/6abd072eccca077d96ad9e20/payoff' -X POST \
-H "Content-Type: application/json" \
-H "Authorization: {SEU_APP_ID}" \
-d '{ "scope": "ALL" }'

Exemplo de resposta (200)​

{
"payoff": {
"amount": 94500,
"lateFee": 0,
"value": 94500,
"extras": [],
"brCode": "00020126580014br.gov.bcb.pix...6304EF01",
"txid": "199b55fa022346fa8ca3681da3c5d5fc",
"expiresAt": "2026-11-02T23:59:59.000Z",
"installments": [1, 2],
"breakdown": [
{ "seq": 1, "dueDate": "2026-11-01", "remaining": 47250, "daysLate": 0, "fine": 0, "interest": 0, "amountDue": 47250 },
{ "seq": 2, "dueDate": "2026-12-01", "remaining": 47250, "daysLate": 0, "fine": 0, "interest": 0, "amountDue": 47250 }
]
}
}
CampoSignificado
amountQuanto a cobrança abate da dívida.
lateFeeMulta e juros de atraso somados, em centavos.
valueValor total do Pix: amount + lateFee + a soma dos extras.
extrasOs valores repassados a outras contas, como pedidos.
installmentsAs parcelas que a cobrança cobre.
breakdownPor parcela: o que falta (remaining), dias de atraso, multa (fine), juros (interest) e o total devido (amountDue).

txid é como a baixa é conciliada: ele aparece em repayments[] da operação e no webhook depois do pagamento.

Cobrar outros valores junto​

Use extras para cobrar no mesmo Pix um valor que não é do empréstimo, como o aluguel de uma locadora. Cada item tem value (centavos) e pixKey. Quando o Pix é pago, o empréstimo recebe amount + lateFee e cada value é transferido para a conta Woovi dona da pixKey.

curl 'https://api.woovi.com/api/v1/loan/operation/6abd072eccca077d96ad9e20/payoff' -X POST \
-H "Content-Type: application/json" \
-H "Authorization: {SEU_APP_ID}" \
-d '{
"scope": "NEXT",
"extras": [
{ "value": 20000, "pixKey": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }
]
}'
  • A pixKey precisa ser uma chave Woovi da sua empresa, da empresa parceira que cadastrou a sua ou de uma empresa afiliada à sua. Fora disso, a recusa é EXTRA_PIX_KEY_NOT_ALLOWED.
  • Até 5 itens, sem repetir pixKey.
  • Os extras não abatem a dívida: o webhook e repayments[] mostram só o que foi para o empréstimo.

Recusas​

Além da validação do corpo (400, por exemplo seqs não contíguas), toda recusa vem com um error e um message explicando o motivo:

StatuserrorSignificado
404OPERATION_NOT_FOUNDA operação não existe para a sua empresa.
422DISBURSEMENT_NOT_CONFIRMEDO Pix de desembolso ainda não foi confirmado.
422INSTALLMENT_PAIDNada é devido para o que foi pedido.
422INVALID_INSTALLMENTAs parcelas pedidas não existem neste empréstimo.
422PREVIOUS_INSTALLMENT_UNPAIDO intervalo não começa na primeira parcela em aberto.
422INVALID_AMOUNTamount é maior do que falta nas parcelas pedidas.
422INVALID_EXTRASextras com mais de 5 itens ou com item inválido.
422EXTRA_PIX_KEY_NOT_ALLOWEDUma pixKey de extras não é uma chave Woovi permitida. message diz qual.
422EXTRA_PIX_KEY_UNVERIFIABLENão foi possível verificar as chaves de extras agora. Tente de novo.
422CHARGE_OVERLAPSJá existe uma cobrança em aberto cobrindo uma dessas parcelas.
422CHARGE_AMOUNT_CHANGEDJá existe uma cobrança em aberto para as mesmas parcelas com outro valor.
422PAYMENT_PROCESSINGUm pagamento dessas parcelas está sendo aplicado. Consulte a operação em instantes.
422CHARGE_EXPIREDA cobrança dessas parcelas expirou. Peça de novo.
422CHARGE_PENDING, CHARGE_NOT_CONFIGURED, FUND_ACCOUNT_UNAVAILABLE, CHARGE_UNAVAILABLEA emissão da cobrança está indisponível no momento. Tente de novo mais tarde.