Payment configuration overview
The payment configuration represents an abstract entity containing information that characterizes payment options. Each offer can have multiple payment configurations associated with it.
Company global configuration
Additionally, the company, which represents our partner, also has a global payment configurations associated with it. These payment configurations serve as defaults, defining maximum or minimum values for certain fields.
When configuring offers, pay attention to the following restricted fields:
- interest_rate: Must be lower than the default value.
- max_installments: Must be lower than the default value.
- down_payment_value: Must be higher than the default value when translated to an absolute value.
Calculating correct down payment for offer
We have a registration fee that is included in the down_payment, so for example if you want to create a first bill with a specific value, the calculation is as follows:
first_bill_amount = down_payment_value + (registration_fee * offer_amount)
Lets create an offer with a first bill of R$ 60,00. In this case the offer will have an amount_cents of 77400:
The registration fee is returned in the global config of your company, in this case lets use a value of 0.0197. So to create an offer with a total of R$ 60,00 in the first bill you will have to calculate the down_payment:
first_bill_amount = down_payment_value + (registration_fee * offer_amount)
down_payment_value = first_bill_amount - (registration_fee * offer_amount)
down_payment_value = 6000 - (0.0197 * 77400)
~4475
So if you create a payment_configuration with a down_payment_value: 4475 in this offer, the result will be a first bill of R$ 60,00
Payment Configuration Schema
| Field | Description | Type |
|---|---|---|
| id | Unique identifier (UUID) | String |
| payment_type | Type of payment option. Can be upfront (full payment) or financed (installment plan) | String |
| installments | Range or array of allowed installment numbers | Object |
| max_installments | Maximum number of installments the customer can choose for the purchase | Integer |
| down_payment_type | How down payment is calculated. Can be percentage or absolute | String |
| down_payment_value | Down payment value - in cents if type is absolute, or as decimal if type is percentage (e.g., 0.20 for 20%) | Float |
| fee_embedded_in_down_payment | Whether the registration fee is embedded in the down payment amount | Boolean |
| min_installment_amount_cents | Minimum amount in cents required for each installment | Integer |
| availability | Configuration availability status. Can be enabled or disabled | String |
| financed_type | Type of financing. Can be bolepix (boleto/PIX payments) or card (credit card) | String |
| expires_in | Number of hours until the down payment expires (Maximum: 72 hours) | Integer |
| interest_rate | Monthly interest rate applied to financed installments (as decimal, e.g., 0.0199 for 1.99%) | Float |
| registration_fee | Registration fee percentage charged on the down payment (as decimal, e.g., 0.0197 for 1.97%) | Float |
| allowed_down_payment_methods | Array of payment methods allowed for the down payment (first installment) | Array |
| payment_methods | Array of payment methods available for recurring installment bills | Array |
| max_down_payment_installments | Maximum number of installments allowed for the down payment when using credit card | Integer |
| down_payment_interest_rate | Interest rate applied to down payment installments (only for credit card down payments) | Float |
| take_rate_type | How the platform take rate is calculated. Can be absolute (fixed amount) or percentage (percentage of amount) | String |
| take_rate_value | Platform take rate value - either fixed amount in cents or percentage as decimal | Float |
| metadata | Additional custom metadata stored as key-value pairs | Object |
| payment_method_configurations | Array of payment method configuration objects defining specific settings for each payment method | Array |
Payment Type Values
| Value | Description |
|---|---|
| upfront | Full payment made at once, with no financing or installments |
| financed | Payment plan with installments, including a down payment and recurring monthly bills |
Down Payment Type Values
| Value | Description |
|---|---|
| absolute | The down_payment_value represents a fixed amount in cents |
| percentage | The down_payment_value represents a percentage of the total amount (as decimal, e.g., 0.25 = 25%) |
Financed Type Values
| Value | Description |
|---|---|
| bolepix | Financing using boleto (bank slip) or PIX payment methods |
| card | Financing using credit card payments |