1.2 Collection Order - Boleto
Introduction
Billing by boleto is a widely used method in Brazil. It consists of a bank document that represents a charge, containing essential information such as the amount to be paid, the due date, the beneficiary's and payer's details, along with a barcode that facilitates reading and processing by banking systems.
Release Expectation in June 2024
This documentation is under construction and may be changed
How it works
Using our EndPoint GenerateCollectionOrder, indicating the CollectionOrderType = 1, you will be able to generate a Boleto.
Receive notifications on the status of each payment
As soon as the payment is made, either through the payment of the barcode, you will receive the receipt information. You can also monitor changes in the status of boletos by receiving our webhooks.
Sending a collection order in Brazil
The customer will send a Collection Order through an EndPoint in FitBank’s API, and the Collection Orders must have the required data to order generation, sending, and payment procedures.
API Method = GenerateCollectionOrder
This method allows sending collection orders. Upon receiving the data sent by the customer, our API creates a payer that will initially pass through a KYC process. After that, an order will be sent, and the operation will be concluded with the processing of the settlement by the payer.
{
"Method": "GenerateCollectionOrder",
"partnerId": 0,
"businessUnitId": 0,
"identifier": "string",
"collectionOrderType": 2,
"principalValue": 0,
"rebateValue": 0,
"interestValue": 0,
"fineValue": 0,
"finePercent": 0,
"interestPercent": 0,
"dueDate": "2024-04-15T18:47:44.190Z",
"expirationDate": "2024-04-15T18:47:44.190Z",
"fineDate": "2024-04-15T18:47:44.190Z",
"discount": {
"type": 1,
"discountRange": [
{
"discountDate": "2024-04-15T18:47:44.190Z",
"discountValue": 0
}
]
},
"payer": {
"name": "string",
"gender": 0,
"maritalStatus": 0,
"ocuppation": "string",
"motherName": "string",
"nationality": "string",
"country": "string",
"birthCity": "string",
"birthState": "string",
"city": "string",
"state": "string",
"zipCode": "string",
"birthDate": "string",
"companyType": 0,
"companyActivity": "string",
"constitutionDate": "2024-04-15T18:47:44.190Z",
"payerContactInfo": {
"mail": "string",
"phone": "string"
},
"payerAccountInfo": {
"pixKey": "string",
"pixKeyType": 0,
"taxNumber": "string",
"bank": "stri",
"bankBranch": "string",
"bankAccount": "string",
"bankAccountDigit": "s"
},
},
"customer": {
"name": "string",
"customerAccountInfo": {
"pixKey": "string",
"pixKeyType": 0,
"taxNumber": "string",
"bank": "stri",
"bankBranch": "string",
"bankAccount": "string",
"bankAccountDigit": "s"
}
},
"receivers": {
"collectionOrderProductType": 0,
"receiver": [
{
"splitValue": 0.01,
"name": "string",
"nickname": "string",
"birthDate": "string",
"tradingName": "string",
"legalName": "string",
"constitutionDate": "2024-04-15T18:47:44.190Z",
"receiverContactInfo": {
"mail": "string",
"phone": "string"
},
"receiverAccountInfo": {
"pixKey": "string",
"pixKeyType": 0,
"taxNumber": "string",
"bank": "stri",
"bankBranch": "string",
"bankAccount": "string",
"bankAccountDigit": "s"
}
}
]
}
}
Description:
| Parameter | Description | To Identify Payer | To Qualify Payer | Type | Comments |
|---|---|---|---|---|---|
| Mandatory | Mandatory | ||||
| Method | Name of the method to be used | YES | YES | STRING | None |
| PartnerId | Partner identifier provided by FitBank | YES | YES | BIGINT | None |
| BusinessUnitId | Business unit identifier provided by FitBank | YES | YES | BIGINT | None |
| Identifier | Unique ID provided by the customer to differentiate transactions | YES | YES | STRING | None |
| CollectionOrderType | Type of the charge | YES | YES | INT | PixQrCodeDinamicDueDate = 0 Boleto = 1 BoletoPixQRCode = 2 PixQRCodeDinamic = 3 |
| PrincipalValue | Value of the Collection Order | YES | YES | DECIMAL | None |
| RebateValue | Discount amount | NO | NO | DECIMAL | None |
| InterestValue | Interest amount | NO | NO | DECIMAL | None |
| FineValue | Fine amount | NO | NO | DECIMAL | None |
| FinePercent | Fine percentage | NO | NO | DECIMAL | None |
| InterestPercent | Interest percentage | NO | NO | DECIMAL | None |
| DueDate | Due date for collection | YES | YES | DATETIME | YYYY-MM-DD format |
| ExpirationDate | Expiration date of charge | YES | YES | DATETIME | YYYY-MM-DD format |
| FineDate | Fine date | NO | NO | DATETIME | YYYY-MM-DD format |
| Discount | Object | - | - | OBJECT | None |
| Type | Discount Type | NO | NO | INT | Amount = 1 Percentage = 2 |
| DiscountRange | Range | - | - | - | - |
| DiscountDate | Discount Date | NO | NO | DATETIME | YYYY-MM-DD format |
| DiscountValue | Discount Value | NO | NO | DECIMAL | None |
| Payer | Object concerning payer's info | - | - | OBJECT | None |
| Name | Payer’s name (NP or LP) | YES | YES | STRING | None |
| BirthDate | Payer's date of birth (NP only) | DERISABLE FOR NP | YES | DATETIME | YYYY-MM-DD format |
| ConstituitionDate | Company's date of incorporation (LP only) | DERISABLE FOR LP | YES FOR LP | DATETIME | YYYY-MM-DD format |
| Gender | Payer’s gender (NP only) | NO | YES | INT | Male = 0 Female = 1 Other = 2 |
| MaritalStatus | Payer’s marital status (NP only) | NO | YES | INT | NotMarried = 0 Married = 1 Divorced = 2 Separate = 3 Widower = 4 Single = 5 Other = 6 |
| Occupation | Payer’s occupation (NP only) | DERISABLE FOR NP | YES | STRING | None |
| MotherName | Payer's mother's name (NP only) | DERISABLE FOR NP | YES | STRING | None |
| Nationality | Payer’s nationality (NP only) | DERISABLE FOR NP | YES | STRING | None |
| Country | Payer’s native country | DERISABLE FOR NP | YES | STRING | None |
| BirthCity | Payer’s native city (NP only) | NO | YES | STRING | None |
| BirthState | Payer’s native state (NP only) | NO | YES | STRING | None |
| CompanyType | Company type (LP only) | DERISABLE FOR LP | YES FOR LP | INT | SA = 0 LTDA = 1 MEI = 2 ME = 3 EIRELI = 4 Condominium = 5 Closed SA = 6 Simple EIRELI = 7 Outros = 8 |
| CompanyActivity | Company activity (LP only) | DERISABLE FOR LP | YES FOR LP | STRING | None |
| City | Payer's City | YES | YES | STRING | None |
| State | Payer's State | YES | YES | STRING | (Ex: SP, RJ, BA, etc) |
| ZipCode | Payer's ZipCode | YES | YES | STRING | None |
| PayerContactInfo | Object concerning payer's contact info | - | - | OBJECT | None |
| Payer’s e-mail | NO | YES | STRING | None | |
| Phone | Payer’s phone | YES | YES | STRING | None |
| PayerAccountInfo | Object concerning payer's account info | - | - | OBJECT | None |
| PixKey | Payer’s PIX key | NO | NO | STRING | None |
| TaxNumber | Payer’s CPF/CNPJ | YES | YES | STRING | None |
| Bank | Payer’s bank code | NO | YES | STRING | None |
| BankBranch | Payer’s bank branch | NO | YES | STRING | None |
| BankAccount | Payer's account number without digit | NO | YES | STRING | None |
| BankAccountDigit | Payer’s account digit | NO | YES | STRING | None |
| Customer | Object concerning customer's info | - | - | OBJECT | None |
| Name | Customer’s name (NP or LP) | YES | YES | STRING | None |
| CustomerAccountInfo | Object concerning customer's account info | - | - | OBJECT | None |
| PixKey | Beneficiary’s (who will do the collection) PIX key | YES | YES | STRING | None |
| PixKeyType | Beneficiary’s (who will do the collection) PIX key type | YES | YES | STRING | SocialSecurity = 0 TaxNumber = 1 E-mail = 2 PhoneNumber = 3 RandomKeyCode = 4 |
| TaxNumber | Beneficiary’s (who will do the collection) CPF/CNPJ | YES | YES | STRING | None |
| Bank | Beneficiary’s (who will do the collection) bank code | YES | YES | STRING | None |
| BankBranch | Beneficiary’s (who will do the collection) bank branch | YES | YES | STRING | None |
| BankAccount | Beneficiary’s (who will do the collection) account number without digit | YES | YES | STRING | None |
| BankAccountDigit | Beneficiary’s (who will do the collection) account digit | YES | YES | STRING | None |
| Receivers | Object concerning receivers' info | - | - | OBJECT | None |
| Value | Amount to be split | NO | NO | DECIMAL | None |
| CollectionOrderProductType | Split type | NO | NO | INT | Amount = 0 Percentage = 1 |
| Receiver | Object concerning receiver's info | - | - | OBJECT | None |
| Name | Receiver’s name | NO | NO | STRING | None |
| BirthDate | Receiver’s birth date | NO | NO | DATETIME | YYYY-MM-DD format |
| ReceiverContactInfo | Object concerning receiver's contact info | - | - | OBJECT | None |
| Receiver’s e-mail | NO | NO | STRING | None | |
| Phone | Receiver’s e-mail phone | NO | NO | STRING | None |
| ReceiverAccountInfo | Object concerning receiver's account info | - | - | OBJECT | None |
| PixKey | Receiver’s PIX key | NO | NO | STRING | None |
| TaxNumber | Receiver’s CPF/CNPJ | NO | NO | STRING | None |
| Bank | Receiver’s bank code | NO | NO | STRING | None |
| BankBranch | Receiver’s bank branch | NO | NO | STRING | None |
| BankAccount | Receiver’s account number without digit | NO | NO | STRING | None |
| BankAccountDigit | Receiver’s account digit | NO | NO | STRING | None |
Explanation
NP = Natural Person
LP = Legal Person
Identified Payer = Identified Payer = Is the initial step, and will meet most cases, without the need for additional information (is the payer who only needs the information required to generate collection orders).
Qualified Payer = Qualification is a more in-depth step that demands more information about the beneficiary. This step will only be required when, after sending the initial request, the system returns a Canceled status with the following reason: Is a qualified person, you must send a Collection Order again, with the data { Name... }. In this situation, a new request must be sent, with the mandatory data for the qualification process (beneficiary who needs to present information previously considered optional for KYC validation).
Collection order status:
| Status | Status Description | Type | Description |
|---|---|---|---|
| 0 | Created | STRING (TEXT) | The Collection Order was created |
| 1 | PreAuthorized | STRING (TEXT) | The Collection Order was pre-authorized and the collection was generated |
| 2 | Analysing | STRING (TEXT) | Payer under review in KYC process |
| 3 | Authorized | STRING (TEXT) | Payer Approved in KYC |
| 6 | Registered | STRING (TEXT) | The Collection was registered |
| 8 | Canceled | STRING (TEXT) | EXC0004 - Payer failed during the KYC process EXC0005 - Invalid billing email address EXC0006 - Collection has expired and payment has not been made EXC0007 - Divergent data between Payer and Settlement EXC0011 - Balance insufficient for fee collection EXC0012 - Payer failed in the validation process EXC0013 - Manual Cancellation INF0008- Is a qualified person, you must send a Collection Order again, with the data { Name, Email, Phone, Country, Nationality, Occupation, ...} |
| 9 | Settled | STRING (TEXT) | Completed Billing Order (payment settled) |
| 11 | Awaiting Payment | STRING (TEXT) | Awaiting Payment |
| 12 | Error | STRING (TEXT) | EXC0008 - Internal Processing Error |
| 15 | Canceled-Refund | STRING (TEXT) | INF0010 - Amount refunded. Divergent data between Payer and Settlement INF0014 - Receiver Account Validation Failed INF0016 - Amount refunded. Payer is a qualified person. INF0017 - Amount refunded. Payer screening has failed during the KYC process |
Updated about 4 hours ago