Refund via Amortization — equal_amount and full_settle

Summary

In addition to the cancel-before-disbursement and 7-day Pix reversal flows (see BNPL Refund), BNPL Full offers two amortization-based refund modes that return funds by debiting an internal partner account directly:

equal_amount — partial refund. Distributes the informed amount proportionally across the operation's installments, reducing the outstanding balance. The operation remains active, with remaining installments still open.
full_settle — total refund. Settles the operation in full in a single transaction, calculating the present value of all installments as of reference_date. After settlement, the operation is marked as settled and no remaining installments exist.

Both modes use the POST /renegotiation/proposal endpoint with payment_type: "internal", which means the amount is moved directly from the account informed in account_key, without generating a bank slip or Pix.

When to use each mode

`equal_amount` — Partial Refund

Use when the borrower wants to reduce the outstanding balance without closing the operation. The payment_amount is distributed across installments, amortizing principal, interest, and any applicable fine. Installments that have not been fully amortized remain in remaining_installments to be collected on their upcoming due dates.

Typical cases:

Borrower overpaid and wants to offset part of the debt only.
Partial return of funds negotiated between partner and borrower.
Application of credits or one-off refunds on active operations.

`full_settle` — Total Refund

Use when the goal is to pay off the operation completely. The system calculates the present value of all open installments as of reference_date (principal + accrued interest + any applicable fine) and distributes the payment_amount to zero out the balance. The operation transitions to settled.

Typical cases:

Refund after the 7-day POST /debt/reversal window.
Early payoff requested by the borrower.
Administrative closure of the operation with full return of funds.

Sequencing

The two modes can be combined. For example: several equal_amount calls for partial amortizations, followed by a final full_settle to close out the remaining balance.

Request

ENDPOINT

/renegotiation/proposal

METHOD

POST

Try in Playground

Request Body

equal_amount (partial)
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

Field	Type	Description	Characters
`debt_key`*	string	Unique key of the credit operation to be refunded	UUID
`payment_type`*	string	Must be `internal` for refunds via internal account	8
`amortization_type`*	string	Refund mode	Amortization Type Enumerators
`reference_date`*	string	Reference date for present-value calculation (format `YYYY-MM-DD`)	10
`payment_amount`*	float	Refund amount in BRL (R$). In `equal_amount`, it is the partial amount to be offset. In `full_settle`, it must cover the total balance on `reference_date`	15,2
`account_key`*	string	Internal account key from which the amount will be debited	UUID
`request_control_key`*	string	Request control key (idempotency)	UUID

Amortization Type Enumerators

Value	Description
`equal_amount`	Partial refund. `payment_amount` is distributed proportionally across installments; the operation remains active with the remaining installments still open.
`full_settle`	Total refund. Fully settles the operation on `reference_date`. The operation transitions to `settled` and no remaining installments exist.

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"
}

Response Details

Field	Type	Description
`proposal_key`	string	Unique key of the refund proposal (UUID). Save it for queries and webhooks.
`amortization_type`	string	Mode used (`equal_amount` or `full_settle`).
`payment_amount`	float	Amount effectively applied in the refund.
`proposal_status`	string	Proposal state. Starts at `pending_payment` and transitions to `paid` after the internal debit.
`affected_installments`	array	Installments that received the refund amount. For each installment, shows the `paid_amount` split across principal, interest, and fine.
`remaining_installments`	array	Installments that remain open after the refund. Empty in `full_settle`.
`payment.payment_data.target_account_key`	string	Destination account of the internal debit.
`payment.payment_data.transaction_amount`	float	Amount effectively moved from `account_key`.
`devolution_amount`	float	Overpayment amount returned to the fund. Only non-zero when a prior payment already exists on the operation and the refund plus that payment together exceed the outstanding balance — the excess is returned via this field.
`request_control_key`	string	Echo of the idempotency key sent in the request.

Rules and notes

Attention

Operation state: the operation must be active and disbursed. Operations not yet disbursed must be cancelled via PATCH /debt/{debt_key}/cancel.
reference_date: drives interest and fine calculation. In full_settle, the entire balance is brought to present value on this date. Cannot be earlier than the operation's disbursement date — that is the minimum allowed value.
Overdue installments: when there are overdue installments, the paid_amount of the affected installment is split across principal_amortization_payment_amount, prefixed_interest_payment_amount, and fine_payment_amount. Check the breakdown in the affected_installments array.
Idempotency: request_control_key is mandatory. Use a unique UUID per attempt to avoid duplicates.
full_settle with insufficient amount: if payment_amount is lower than the calculated total balance, the debit is still processed and distributed proportionally — check the operation's final status to confirm settlement.

Combining modes

Several equal_amount proposals can be made in sequence, each offsetting part of the balance.
A full_settle can be made after one or more equal_amount proposals to close out the remaining balance.
Each proposal is independent and must use a distinct request_control_key.

Query proposal status

After creating the proposal, query its status by the request_control_key sent in the request.

ENDPOINT

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

METHOD

GET

Path Params

Field	Type	Description	Characters
`request_control_key`*	string	Control key sent on proposal creation	UUID

The response follows the same format as the POST return. The proposal_status field indicates progress:

Status	Description
`pending_payment`	Proposal created, awaiting internal debit processing.
`paid`	Debit processed. In `full_settle`, the operation is already `settled`.

Settlement Webhook

When a refund fully settles the operation — typically in full_settle, but also in cases where the cumulative equal_amount amortizations zero out the balance — the system sends a debt webhook with status settled.

WEBHOOK_TYPE

debt

STATUS

settled

Use this webhook to asynchronously confirm that the operation was closed after the internal debit is processed. The full payload and fields follow the pattern described in Webhooks - BNPL Refund.

Summary​

When to use each mode​

equal_amount — Partial Refund​

full_settle — Total Refund​

Request​

Body Params​

Amortization Type Enumerators​

Response​

Response Details​

Rules and notes​

Query proposal status​

Path Params​

Settlement Webhook​