Setting up the type of interest rate

When a payment condition allows installments with interest, the VTEX Payment Gateway uses the interestRateMethod field to calculate the amount of each installment. This field belongs to the installmentOptions object of the payment condition, which the Payments Gateway API refers to as a rule.

The field accepts the following values:

Compound interest is the most common model in Brazil, while countries such as Argentina prefer simple interest. For a comparison between both models, see How to choose the type of interest for a payment condition.

When using simple interest with tax (1), set the interestTax value for each installment in the installmentOptions.installments array. This guide covers changing the interestRateMethod field; include the desired interestTax values in the same payment rule request.

The interest type selector in the VTEX Admin offers only compound interest (0) and simple interest (2). To set either of these values, follow How to choose the type of interest for a payment condition. Use the following steps to set simple interest with tax (1), which is only available through the API.

To complete the steps in this guide, you need the following:

• The name of your VTEX account, used in the request URL.
• An API key with the License Manager resources required by each endpoint:

No predefined role grants these resources. Create a custom role with the resources in the preceding table, and follow the best practices for managing API keys to avoid granting excessive permissions.

1. In the VTEX Admin, go to Store Settings > Payment > Settings, or type Settings in the search bar at the top of the page.
2. Click the Payment Conditions tab.
3. Select the payment condition you want to configure.
4. Copy the last parameter of the page URL, which is the ID of the payment condition, as shown in the following image.

This value corresponds to the ruleId path parameter in the following requests.

The ruleId identifies the payment condition, not the payment method. A payment method such as Visa can have several payment conditions, each with its own ruleId and interest settings. Setting the interest rate type affects only the payment condition you send in the request.

Send a Get payment rule by ID request to retrieve the current configuration of the payment condition:

Replace {accountName} with your account name, {ruleId} with the ID from the previous step, and {appKey} and {appToken} with your API key credentials.

A successful request returns the status code 200 OK and the complete payment condition. The interest settings are inside the installmentOptions object. The following excerpt shows the relevant fields from the response:

Save the entire response body, including the other payment condition fields, as you need it to build the request in the next step.

Send an Update payment rule by ID request using the response from the previous step as the request body, changing only the value of interestRateMethod:

This request replaces the entire payment condition. Any field omitted from the request body is overwritten with its default value, which can disable the payment condition or remove its installment settings. Always build the request body from the response you retrieved in the previous step, rather than from the preceding example.

A successful request returns the status code 200 OK and the updated payment condition.

1. Send a new Get payment rule by ID request and confirm that interestRateMethod returns the expected value.
2. Place a test order in your store and confirm that the installment amounts displayed at checkout match the interest model you configured.

The interest type selector in the VTEX Admin doesn't display simple interest with tax, and it hides the option to change the interest type when the payment condition uses this value. If you edit and save this payment condition in the VTEX Admin, check interestRateMethod again with Get payment rule by ID and repeat step 3 if the value changed.