Estorno via Amortização — equal_amount e full_settle

Resumo

Além dos fluxos de cancelamento antes do desembolso e estorno via Pix nos primeiros 7 dias (ver Estorno BNPL), o BNPL Full oferece duas modalidades de estorno por amortização, que executam o retorno dos recursos debitando diretamente uma conta interna do parceiro:

equal_amount — estorno parcial. Distribui o valor informado proporcionalmente entre as parcelas da operação, reduzindo o saldo devedor. A operação continua ativa, com as parcelas restantes em aberto.
full_settle — estorno total. Quita integralmente a operação em uma única transação, calculando o valor presente de todas as parcelas na reference_date. Após a liquidação, a operação é marcada como settled e não há parcelas remanescentes.

Ambas as modalidades utilizam o endpoint POST /renegotiation/proposal com payment_type: "internal", o que significa que o valor é movimentado diretamente da conta informada em account_key, sem geração de boleto ou Pix.

Quando usar cada modalidade

`equal_amount` — Estorno Parcial

Use quando o tomador deseja reduzir o saldo devedor sem encerrar a operação. O valor enviado em payment_amount é distribuído entre as parcelas, abatendo principal, juros e eventual multa. As parcelas que ainda não foram totalmente amortizadas continuam em remaining_installments para cobrança nos próximos vencimentos.

Casos típicos:

Cliente pagou a mais e quer abater apenas parte da dívida.
Retorno parcial de recursos acordado entre parceiro e tomador.
Aplicação de créditos ou devoluções pontuais em operações ativas.

`full_settle` — Estorno Total

Use quando o objetivo é quitar a operação por completo. O sistema calcula o valor presente de todas as parcelas abertas na reference_date (principal + juros acumulados + eventual multa) e distribui o payment_amount até zerar o saldo. A operação passa ao status settled.

Casos típicos:

Estorno após o prazo de 7 dias do POST /debt/reversal.
Quitação antecipada solicitada pelo tomador.
Encerramento administrativo da operação com retorno integral dos recursos.

Sequenciamento

É possível combinar as duas modalidades. Por exemplo: várias chamadas equal_amount para amortizações parciais, seguidas de um full_settle final para quitar o saldo remanescente.

Request

ENDPOINT

/renegotiation/proposal

MÉTODO

POST

Testar no Playground

Request Body

equal_amount (parcial)
full_settle (total)

{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "payment_type": "internal",
    "amortization_type": "equal_amount",
    "reference_date": "2026-04-13",
    "payment_amount": 50.00,
    "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}

{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "payment_type": "internal",
    "amortization_type": "full_settle",
    "reference_date": "2026-04-13",
    "payment_amount": 1043.55,
    "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
    "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890"
}

Body Params

Campo	Tipo	Descrição	Caracteres
`debt_key`*	string	Chave única da operação de crédito a ser estornada	UUID
`payment_type`*	string	Deve ser `internal` para estorno via conta interna	8
`amortization_type`*	string	Modalidade do estorno	Enumeradores Amortization Type
`reference_date`*	string	Data de referência para cálculo do valor presente (formato `YYYY-MM-DD`)	10
`payment_amount`*	float	Valor do estorno em reais (R$). Em `equal_amount`, é o valor parcial a ser abatido. Em `full_settle`, deve cobrir o saldo total na `reference_date`	15,2
`account_key`*	string	Chave da conta interna de onde o valor será debitado	UUID
`request_control_key`*	string	Chave de controle da requisição (idempotência)	UUID

Enumeradores Amortization Type

Valor	Descrição
`equal_amount`	Estorno parcial. `payment_amount` é distribuído proporcionalmente entre as parcelas; a operação permanece ativa com as parcelas remanescentes em aberto.
`full_settle`	Estorno total. Quita integralmente a operação na `reference_date`. A operação passa a `settled` e não há parcelas remanescentes.

Response

STATUS

201

Response Body

{
    "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
    "contract_number": "DWF1761222116",
    "amortization_type": "equal_amount",
    "payment_amount": 50.00,
    "discount_percentage": 0,
    "discount_amount": 0,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "origin_key": null,
    "issuer_name": "Dante Ferrarini",
    "issuer_document_number": "31057466093",
    "affected_installments": [
        {
            "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
            "due_date": "2026-05-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78,
            "present_amount": 18.00,
            "paid_amount": 18.00,
            "principal_amortization_payment_amount": 18.00,
            "prefixed_interest_payment_amount": 0,
            "fine_payment_amount": 0
        }
    ],
    "remaining_installments": [
        {
            "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
            "due_date": "2026-06-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78
        }
    ],
    "proposal_status": "pending_payment",
    "payment_type": "internal",
    "payment": {
        "digitable_line": null,
        "qr_code_url": null,
        "qr_code_key": null,
        "bank_slip_key": null,
        "paid_method_type": "internal",
        "source_account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
        "payment_data": {
            "target_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "transaction_amount": 50.00
        }
    },
    "proposal_due_date": "2026-04-13",
    "reference_date": "2026-04-13",
    "devolution_amount": 0,
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}

Detalhes do Response

Campo	Tipo	Descrição
`proposal_key`	string	Chave única da proposta de estorno (UUID). Guarde para consultas e webhooks.
`amortization_type`	string	Modalidade utilizada (`equal_amount` ou `full_settle`).
`payment_amount`	float	Valor efetivamente aplicado no estorno.
`proposal_status`	string	Estado da proposta. Inicia em `pending_payment` e transiciona para `paid` após o débito interno.
`affected_installments`	array	Parcelas que receberam o valor do estorno. Para cada parcela, mostra a composição do `paid_amount` entre principal, juros e multa.
`remaining_installments`	array	Parcelas que permanecem em aberto após o estorno. Em `full_settle`, vem vazio.
`payment.payment_data.target_account_key`	string	Conta de destino do débito interno.
`payment.payment_data.transaction_amount`	float	Valor efetivamente movimentado da `account_key`.
`devolution_amount`	float	Valor de sobrepagamento devolvido ao fundo. Só é diferente de zero quando já existe um pagamento prévio na operação e o estorno somado a esse pagamento excede o saldo devedor — o excedente é retornado via este campo.
`request_control_key`	string	Eco da chave de idempotência enviada no request.

Regras e observações

Atenção

Estado da operação: a operação deve estar ativa e desembolsada. Operações ainda não desembolsadas devem ser canceladas via PATCH /debt/{debt_key}/cancel.
reference_date: determina o cálculo de juros e multa. Em full_settle, todo o saldo é trazido a valor presente nesta data. Não pode ser anterior à data de desembolso da operação — esse é o limite mínimo permitido.
Parcelas em atraso: quando há parcelas vencidas, o paid_amount da parcela afetada é distribuído entre principal_amortization_payment_amount, prefixed_interest_payment_amount e fine_payment_amount. Verifique o detalhamento no array affected_installments.
Idempotência: request_control_key é obrigatório. Use um UUID único por tentativa para evitar duplicações.
full_settle com valor insuficiente: se payment_amount for menor que o saldo total calculado, o débito ainda é processado e distribuído proporcionalmente — verifique o status final da operação para confirmar a quitação.

Combinando modalidades

Várias propostas equal_amount podem ser feitas em sequência, cada uma abatendo uma parte do saldo.
Um full_settle pode ser feito após uma ou mais propostas equal_amount para encerrar o saldo remanescente.
Cada proposta é independente e deve usar um request_control_key distinto.

Consultar status da proposta

Após criar a proposta, consulte seu status pelo request_control_key informado no request.

ENDPOINT

/renegotiation/proposal/request_control_key/REQUEST-CONTROL-KEY

MÉTODO

GET

Path Params

Campo	Tipo	Descrição	Caracteres
`request_control_key`*	string	Chave de controle enviada na criação da proposta	UUID

O response segue o mesmo formato do retorno do POST. O campo proposal_status indica o andamento:

Status	Descrição
`pending_payment`	Proposta criada, aguardando o processamento do débito interno.
`paid`	Débito processado. Em `full_settle`, a operação já está em `settled`.

Webhook de Quitação

Quando um estorno resulta na quitação integral da operação — tipicamente em full_settle, mas também em casos de equal_amount cujo somatório zera o saldo devedor — o sistema envia um webhook do tipo debt com status settled.

WEBHOOK_TYPE

debt

STATUS

settled

Use este webhook para confirmar, de forma assíncrona, que a operação foi encerrada após o processamento do débito interno. O payload completo e os campos seguem o padrão descrito em Webhooks - Estorno BNPL.

Resumo​

Quando usar cada modalidade​

equal_amount — Estorno Parcial​

full_settle — Estorno Total​

Request​

Body Params​

Enumeradores Amortization Type​

Response​

Detalhes do Response​

Regras e observações​

Consultar status da proposta​

Path Params​

Webhook de Quitação​