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 (equal values are allowed). A violation answers 400 with the attribute in parentheses:
- installments (financed): must be a subset of the default configuration’s installments (
installments_not_allowed). - max_installments (upfront credit card): must not be greater than the default value (
method_max_installments_greater_than_allowed). - max_installments (financed): must match the installment table computed from the minimum installment amount (
max_installments_inconsistent_with_min_installment_amount). - down_payment_value: the down payment without the registration fee must be at least the default value when translated to an absolute value (
down_payment_lower_than_allowed), and the down payment must not exceed the offer amount (down_payment_greater_than_offer_amount).
Calculating correct down payment for offer
We have a registration fee that is included in the down_payment. When fee_embedded_in_down_payment is false, the registration fee is added on top of the down payment, so for example if you want to create a first bill with a specific value, the calculation is as follows (when it is true, the first bill equals the down payment):
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
Creating and Updating Payment Configurations
When creating or updating an offer via the Create or Update endpoints, you must provide the payment_configurations array with the following fields. On update the array is optional; when it is sent, its items follow the create rules and it replaces all the offer’s current configurations.
All upfront items are merged into a single configuration: they share one id, and its expires_in_hours is the first item’s.
Payment Configuration Input Fields (Create/Update)
| Field | Description | Type | Required (Create) | Required (Update) |
|---|---|---|---|---|
| payment_type | Type of payment option. Can be upfront (full payment) or financed (installment plan) | String | Yes | No |
| payment_methods | Array of payment methods available for this configuration: pix, boleto or credit_card. Required for upfront; for financed it defaults to all three | Array | Upfront only | No |
| expires_in_hours | Number of hours until the payment expires (Maximum: 240). Defaults to the company default | Integer | No | No |
| financed_type | Type of financing. Can be bolepix (boleto/PIX payments) or card (credit card). Required if payment_type is financed | String | No | No |
| allowed_down_payment_methods | Array of payment methods allowed for the down payment (first installment). Required for financed, otherwise 400 allowed_down_payment_methods | Array | Financed only | No |
| down_payment_type | How down payment is calculated. Can be percentage or absolute. When not sent, the company default down payment is used | String | No | No |
| 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 | No | No |
| fee_embedded_in_down_payment | Whether the registration fee is embedded in the down payment amount | Boolean | No | No |
| max_installments | Maximum number of installments the customer can choose for the purchase | Integer | No | No |
| installments | Financed only. Array of allowed installment numbers. Defaults to 1 up to max_installments | Array | No | No |
| interest_rate | Monthly interest rate applied to financed installments (as decimal, e.g., 0.0199 for 1.99%) | Float | No | No |
| max_down_payment_installments | Maximum number of installments allowed for the down payment when using credit card | Integer | No | No |
| down_payment_interest_rate | Interest rate applied to down payment installments (only for credit card down payments) | Float | No | No |
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 | Array of allowed installment numbers. Returned in billings and payment info; offer and company default responses omit it | Array |
| 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: 240 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 |
| max_amount_cents | Highest offer amount this configuration applies to. null for offer configurations; on company default configurations, 2147483647 means no upper limit | Integer |
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 |