Skip to main content

Credit Split Update

This endpoint allows updating the credit split (split payment) of a previously issued bank slip. The new rules fully replace the existing ones and apply to the next settlement of the bank slip.

Attention!
  • The bank slip must be in registered status and not yet paid.
  • The sum of beneficiary_settlement_percentage and the percentages in each item of split_payment_rules must be exactly 100.
  • The payload replaces all existing split rules (it is not incremental).
  • The split applies to all settlement flows of the bank slip (SILOC, STR, notary office and Pix QR Code), including bank slips with QR Code already issued — in this case, the rules are also automatically updated on the QR Code.
  • The accounts in the split rules must be open and registered with QI Tech (QI Tech will look them up by the document_number, account_number and account_digit provided).

Request​

ENDPOINT
/v2/bank_slip/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/bank_slip/BANK_SLIP_KEY/split_payment
METHOD
PUT

Path parameters​

FieldTypeDescriptionCharacters
account_keyuuidv4Unique identification key of the account in which the bank slip was issued36
requester_profile_keyuuidv4Unique identification key of the wallet36
bank_slip_keyuuidv4Unique identification key of the bank slip36
Request Body
{
  "beneficiary_settlement_percentage": 70,
  "split_payment_rules": [
    {
      "percentage": 20,
      "document_number": "12345678901",
      "account_owner_name": "John Smith",
      "account_number": "1234567",
      "account_digit": "8"
    },
    {
      "percentage": 10,
      "document_number": "10987654321",
      "account_owner_name": "Mary Johnson",
      "account_number": "7654321",
      "account_digit": "0"
    }
  ]
}

Request Body Params​

FieldTypeDescriptionCharacters
beneficiary_settlement_percentage *floatPercentage of the settled amount allocated to the bank slip's beneficiary. Accepts values from 0 to 100.-
beneficiary_max_amountfloatMaximum amount the beneficiary receives at settlement. When the paid amount exceeds this limit, the surplus is fully directed to the first rule of the split_payment_rules array. Accepts values greater than 0 and less than or equal to the bank slip amount.-
split_payment_rules *object arrayList of split rules. Minimum 1, maximum 10 rules.split_payment_rule Object

Objeto split_payment_rule​

FieldTypeDescriptionCharacters
percentage *floatPercentage of the settled amount allocated to this account. Accepts values from 0 to 100. Use 0 when this rule is meant exclusively to receive the surplus from beneficiary_max_amount.-
document_number *stringCPF/CNPJ of the destination account holder.11 or 14
account_owner_name *stringName of the destination account holder.100
account_number *stringDestination account number.20
account_digit *stringDestination account check digit.2

Use case: directing late fees and interest to a separate account​

How can I configure the split so that interest and late fees that exceed the bank slip's face value are directed to a different account?

This scenario is common for platforms that issue bank slips on behalf of third parties (schools, condominiums, marketplaces), where the bank slip's owner should always receive the face value and the platform receives the additional interest/late fee in case of overdue payment.

It is configured by combining beneficiary_max_amount with a split rule with percentage = 0:

{
  "beneficiary_settlement_percentage": 100,
  "beneficiary_max_amount": 1000.00,
  "split_payment_rules": [
    {
      "percentage": 0,
      "document_number": "12345678000199",
      "account_owner_name": "Billing Platform",
      "account_number": "1234567",
      "account_digit": "8"
    }
  ]
}

How the calculation works considering a bank slip of R$ 1,000.00:

ScenarioPaid amountBeneficiary receivesPlatform receives
Paid on timeR$ 1,000.00R$ 1,000.00R$ 0.00 (no settlement generated)
Paid late (with R$ 100.00 interest/fee)R$ 1,100.00R$ 1,000.00R$ 100.00
Partial late paymentR$ 950.00R$ 950.00R$ 0.00

The rule is: the beneficiary receives at most beneficiary_max_amount; any amount paid above this is fully directed to the first rule in split_payment_rules.

Attention!
  • beneficiary_max_amount must be greater than 0 and less than or equal to the bank slip amount (amount).
  • When any rule has percentage = 0, the beneficiary_max_amount field is required.
  • Only one rule in split_payment_rules may have percentage = 0 per bank slip (the surplus recipient).

Response​

STATUS
204
Response Body
{}

Error Response​

STATUS
4xx
Response Body: Error
{
  "title": "title",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "code",
  "extra_fields": {}
}
HTTP Code
status		QI Code
code		Title
title		Description (eng)
description		Description (pt-br)
translation
400QIT000001Bad RequestSchema ErrorSchema Inválido
404BKS000029Not FoundBank slip not found for the given key ({bank_slip_key}).Boleto não encontrado para a chave fornecida ({bank_slip_key}).
400BKS000032Bad RequestBank slip must be in 'registered' status.O boleto deve possuir o status 'registered'.
422BKS000157Unprocessable EntityCould not find an account matching the provided split payment account data.Não foi possível encontrar uma conta com os dados informados na regra de split payment.
400BKS000158Bad RequestThe beneficiary_max_amount must be greater than 0 and not greater than the bank slip amount.O beneficiary_max_amount deve ser maior que 0 e não pode ser maior que o valor do boleto.
400BKS000159Bad RequestSplit payment rules with percentage equal to 0 require beneficiary_max_amount to be set.Regras de split payment com percentual igual a 0 exigem o campo beneficiary_max_amount preenchido.
400BKS000160Bad RequestOnly one split payment rule with percentage equal to 0 is allowed.É permitido apenas uma regra de split payment com percentual igual a 0.