Account Rates

This page explains how the BU changes the rates (fixed fees) and percentages charged on an account. The AccountRate method updates the rates of one account at a time. The AccountRateBatch method does the same for several accounts in a single call, which saves time when a change affects many accounts.

When to use

Use AccountRate to adjust the rate of a specific account. Use AccountRateBatch when you need to apply the same rate or percentage to several accounts at once.

Operations that can be changed

The OperationType field indicates the operation whose rate or percentage will be changed and accepts any value in the list of the Code Mapping, in the section Operation type (for example, 40, outgoing PIX; 3, outgoing TED; 30, card withdrawal; 52, fee per payment order). A value that is not in the list is rejected. The field is sent as text (example: "40").

In the flows analyzed, only codes 2, 3, 6, 7, 23, 30 and 40 charge the account rate, according to the conditions of each operation. Code 56 (AllOperations) is not a wildcard: it does not apply the rate to all operations.

AccountRate: Request fields

Request examples are in the API Reference. The Method, PartnerId and BusinessUnitId fields are common to all methods and are described in Getting Started.

In the Requirement column, Mandatory means the field must be sent, Optional means it can be omitted, and Conditional means it depends on another field, as stated in the Description.

FieldRequirementDescription
MethodMandatoryMethod to be used (AccountRate).
PartnerIdMandatoryInformation provided by Fits.
BusinessUnitIdMandatoryInformation provided by Fits.
TaxNumberConditionalCPF/CNPJ of the account holder whose rate will be changed. Required if the AccountKey is not sent.
AccountKeyConditionalAccount identifier. If it is not sent, the TaxNumber is required.
OperationTypeMandatoryOperation whose rate or percentage will be changed, sent as text (example: "40"). The values are listed in the Code Mapping, in the section Operation type.
RatePercentageOptionalRate percentage, as decimal text with a dot (example: "0.01" means 0.01%).
RateValueOptionalRate amount in reais, as decimal text with a dot.
BankOptionalBank code (example: "450").
BankBranchOptionalBranch code (example: "0001").
BankAccountOptionalAccount number (example: "146492").
BankAccountDigitOptionalAccount digit (example: "1").

AccountRateBatch: Request fields

FieldRequirementDescription
MethodMandatoryMethod to be used (AccountRateBatch).
PartnerIdMandatoryInformation provided by Fits.
BusinessUnitIdMandatoryInformation provided by Fits.
OperationTypeMandatoryOperation whose rate or percentage will be changed, sent as text (example: "40"). The values are listed in the Code Mapping, in the section Operation type.
RatePercentageMandatoryRate percentage, as decimal text with a dot (example: "0.01" means 0.01%).
RateValueMandatoryRate amount in reais, as decimal text with a dot.
AccountsMandatoryList of accounts whose rate will be changed.
Accounts.AccountKeyMandatoryAccount identifier.
Accounts.TaxNumberMandatoryCPF/CNPJ of the account holder.

Response

In both methods, Success is returned as text ("true" or "false", not a boolean) and Message carries the return message. The success messages of AccountRate and AccountRateBatch are listed in the Success Catalogue. AccountRate returns no other fields.

AccountRateBatch: Response fields

Besides Success and Message, the batch call response includes the FailedAccounts list when the request fails.

FieldDescription
Success"true" or "false" (text, not a boolean).
MessageReturn message. On failure, it gives the reason.
FailedAccountsList of the accounts that were not updated. Returned on failure.
FailedAccounts.TaxNumberTaxNumber of the account that was not updated.
FailedAccounts.AccountKeyAccountKey of the account that was not updated.

The errors returned by these methods are listed in the Error Catalogue, in the section AccountRate and AccountRateBatch.

AccountRateBatch validations

The flow below shows the AccountRateBatch validations, in sequence, and the result of the call.

flowchart TD
  A["AccountRateBatch"] --> B{"Accounts filled in and within the limit?"}
  B -->|No| F["Failure with FailedAccounts in the response"]
  B -->|Yes| C{"RatePercentage or RateValue follow the rules?"}
  C -->|No| F
  C -->|Yes| D{"OperationType valid?"}
  D -->|No| F
  D -->|Yes| S["Success"]

Rules

  • AccountRateBatch accepts up to 100 accounts per request (fixed ceiling);
  • within that ceiling, the batch limit is set by the BU parameter "Alteração de Taxa em Lote"; if it is not configured, the default is 10 accounts. The BU cannot change this value through the API: Fits makes the change;
  • in AccountRateBatch, the Accounts field is mandatory and cannot be empty; if the number of accounts exceeds the limit, the request is rejected;
  • RatePercentage and RateValue are sent as text and must be decimals, with a dot as the separator (example: "0.01"); a comma is not accepted;
  • only one of RatePercentage and RateValue can be greater than zero; if both are greater than zero, the request is rejected;
  • RatePercentage cannot be greater than 100, and a RateValue greater than zero cannot be less than 0.01;
  • negative values are not accepted;
  • we recommend sending both fields, with "0" in the one that is not used; both at zero mean an exemption;
  • in AccountRate, an omitted field is treated as zero; in AccountRateBatch, both fields are required;
  • in the batch call, the TaxNumber of each account being changed must be provided.

Did this page help you?