Scenarios - BNPL Batch Renegotiation
Overview
This document presents the main batch renegotiation scenarios for BNPL operations. All scenarios use amortization_type: "present_amount" and allow applying individual discounts per installment through the discount field in each installment object.
You can apply different discounts to each installment individually. Simply add the discount field (absolute value in BRL) inside the desired installment object. Installments without the discount field will be charged at the full present value.
Scenario 1: 1 Installment Loan - Standard Payment
The borrower has a 1-installment BNPL loan and wants to settle it at the present value.
Payload Example
{
"payment_type": "pix",
"amortization_type": "present_amount",
"proposal_due_date": "2026-04-10",
"discount_percentage": 0,
"reference_date": "2026-04-10",
"request_control_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"operations": [
{
"debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
"installments": [
{
"installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d"
}
]
}
]
}
Scenario 2: 1 Installment Loan - Interest Free Payment
The borrower has a 1-installment BNPL loan and negotiates an interest-free payment. The discount applied corresponds to the interest amount of the installment.
Payload Example
{
"payment_type": "pix",
"amortization_type": "present_amount",
"proposal_due_date": "2026-04-10",
"discount_percentage": 0,
"reference_date": "2026-04-10",
"request_control_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"operations": [
{
"debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
"installments": [
{
"installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
"discount": 54.19
}
]
}
]
}
The discount value (54.19) corresponds to the interest amount (pre_fixed_amount) of the installment. This way, the borrower only pays the principal amount.
Scenario 3: 1 Installment Loan - Interest + IOF Free Payment
The borrower has a 1-installment BNPL loan and negotiates a payment without interest and without IOF. The discount applied corresponds to the sum of interest and IOF of the installment.
Payload Example
{
"payment_type": "pix",
"amortization_type": "present_amount",
"proposal_due_date": "2026-04-10",
"discount_percentage": 0,
"reference_date": "2026-04-10",
"request_control_key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"operations": [
{
"debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
"installments": [
{
"installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
"discount": 55.44
}
]
}
]
}
The discount value (55.44) corresponds to the sum of interest (pre_fixed_amount: 54.19) + IOF (tax_amount: 1.25) of the installment. This way, the borrower only pays the principal amortization amount.
Scenario 4: Multiple Installments with Individual Discount
The borrower has a BNPL loan with multiple installments and negotiates different discounts for specific installments. Installments without the discount field are charged at the full present value.
Payload Example
{
"payment_type": "pix",
"amortization_type": "present_amount",
"proposal_due_date": "2026-04-10",
"discount_percentage": 0,
"reference_date": "2026-04-10",
"request_control_key": "d4e5f6a7-b8c9-0123-defa-234567890123",
"operations": [
{
"debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
"installments": [
{
"installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
"discount": 20
},
{
"installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8"
},
{
"installment_key": "5be492bf-b637-4999-986d-ecf423cc5dd1"
},
{
"installment_key": "15abfbfd-8608-45e9-abbb-a04c021dcf7b",
"discount": 10
},
{
"installment_key": "c8eb83b3-5b0d-4326-947c-79279cdce2d6"
}
]
}
]
}
In this example:
- Installment 1: R$ 20.00 discount
- Installment 2: no discount (full present value)
- Installment 3: no discount (full present value)
- Installment 4: R$ 10.00 discount
- Installment 5: no discount (full present value)
Scenario 5: Overdue Installment Payment
The borrower has overdue installments and wants to settle them. Overdue installments already include automatically calculated fines and penalty interest. Individual discounts can be applied to reduce the amount.
Payload Example
{
"payment_type": "bank_slip",
"amortization_type": "present_amount",
"proposal_due_date": "2026-04-10",
"discount_percentage": 0,
"reference_date": "2026-04-10",
"request_control_key": "e5f6a7b8-c9d0-1234-efab-345678901234",
"operations": [
{
"debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
"installments": [
{
"installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
"discount": 15
},
{
"installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8",
"discount": 15
}
]
}
]
}
For overdue installments, the present value already includes fines (fine_amount) and penalty interest calculated automatically based on the contract's fine_configuration. The discount is applied on this total value.
Scenario 6: Multiple Operations with Individual Per-Installment Discount
The borrower has BNPL loans across different operations and wants to settle installments from all of them in a single payment, with individual discounts.
Payload Example
{
"payment_type": "pix",
"amortization_type": "present_amount",
"proposal_due_date": "2026-04-10",
"discount_percentage": 0,
"reference_date": "2026-04-10",
"request_control_key": "f6a7b8c9-d0e1-2345-fabc-456789012345",
"operations": [
{
"debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
"installments": [
{
"installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
"discount": 20
},
{
"installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8"
}
]
},
{
"debt_key": "a2c3d4e5-860f-4b7a-9c1d-2e3f4a5b6c7d",
"installments": [
{
"installment_key": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
"discount": 30
}
]
}
]
}
Installments Object - Discount Field
| Field | Type | Description | Required |
|---|---|---|---|
installment_key* | string | Key of the installment to be renegotiated | Yes |
discount | float | Discount amount in BRL (R$) applied individually to the installment | No |
- The
discountfield is optional and can be provided for any installment - The value is an absolute discount in BRL (not a percentage)
- Installments without the
discountfield are charged at the full present value - The discount is applied on the installment's present value at the
reference_date
Scenarios Summary Table
| Scenario | Description | Discount |
|---|---|---|
| 1 installment - standard | Payment at present value | No discount |
| 1 installment - interest free | Discount = interest amount | discount = pre_fixed_amount |
| 1 installment - interest + IOF free | Discount = interest + IOF | discount = pre_fixed_amount + tax_amount |
| Multiple installments | Individual discounts per installment | discount per installment |
| Overdue installments | Overdue installments with fines/penalties | Optional discount |
| Multiple operations | Different operations in one batch | discount per installment |
Important Rules
- All operations must belong to the same issuer and the same integration key
- Limit of 50 operations per batch
- A single payment method (bank slip/Pix) is generated for the total batch amount
- If an installment included in the batch is paid externally before confirmation, the batch is rejected
- If payment is not made by the
proposal_due_date, the batch is rejected - The
amortization_typeused is alwayspresent_amount - The
discountfield is applied individually per installment