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.

🚧

Version 1

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:

ParameterDescriptionTo Identify PayerTo Qualify PayerTypeComments
MandatoryMandatory
MethodName of the method to be usedYESYESSTRINGNone
PartnerIdPartner identifier provided by FitBankYESYESBIGINTNone
BusinessUnitIdBusiness unit identifier provided by FitBankYESYESBIGINTNone
IdentifierUnique ID provided by the customer to differentiate transactionsYESYESSTRINGNone
CollectionOrderTypeType of the chargeYESYESINTPixQrCodeDinamicDueDate = 0
Boleto = 1
BoletoPixQRCode = 2
PixQRCodeDinamic = 3
PrincipalValueValue of the Collection OrderYESYESDECIMALNone
RebateValueDiscount amountNONODECIMALNone
InterestValueInterest amountNONODECIMALNone
FineValueFine amountNONODECIMALNone
FinePercentFine percentageNONODECIMALNone
InterestPercentInterest percentageNONODECIMALNone
DueDateDue date for collectionYESYESDATETIMEYYYY-MM-DD format
ExpirationDateExpiration date of chargeYESYESDATETIMEYYYY-MM-DD format
FineDateFine dateNONODATETIMEYYYY-MM-DD format
DiscountObject--OBJECTNone
TypeDiscount TypeNONOINTAmount = 1
Percentage = 2
DiscountRangeRange----
DiscountDateDiscount DateNONODATETIMEYYYY-MM-DD format
DiscountValueDiscount ValueNONODECIMALNone
PayerObject concerning payer's info--OBJECTNone
NamePayer’s name (NP or LP)YESYESSTRINGNone
BirthDatePayer's date of birth (NP only)DERISABLE FOR NPYESDATETIMEYYYY-MM-DD format
ConstituitionDateCompany's date of incorporation (LP only)DERISABLE FOR LPYES FOR LPDATETIMEYYYY-MM-DD format
GenderPayer’s gender (NP only)NOYESINTMale = 0
Female = 1
Other = 2
MaritalStatusPayer’s marital status (NP only)NOYESINTNotMarried = 0
Married = 1
Divorced = 2
Separate = 3
Widower = 4
Single = 5
Other = 6
OccupationPayer’s occupation (NP only)DERISABLE FOR NPYESSTRINGNone
MotherNamePayer's mother's name (NP only)DERISABLE FOR NPYESSTRINGNone
NationalityPayer’s nationality (NP only)DERISABLE FOR NPYESSTRINGNone
CountryPayer’s native countryDERISABLE FOR NPYESSTRINGNone
BirthCityPayer’s native city (NP only)NOYESSTRINGNone
BirthStatePayer’s native state (NP only)NOYESSTRINGNone
CompanyTypeCompany type (LP only)DERISABLE FOR LPYES FOR LPINTSA = 0
LTDA = 1
MEI = 2
ME = 3
EIRELI = 4
Condominium = 5
Closed SA = 6
Simple EIRELI = 7
Outros = 8
CompanyActivityCompany activity (LP only)DERISABLE FOR LPYES FOR LPSTRINGNone
CityPayer's CityYESYESSTRINGNone
StatePayer's StateYESYESSTRING(Ex: SP, RJ, BA, etc)
ZipCodePayer's ZipCodeYESYESSTRINGNone
PayerContactInfoObject concerning payer's contact info--OBJECTNone
MailPayer’s e-mailNOYESSTRINGNone
PhonePayer’s phoneYESYESSTRINGNone
PayerAccountInfoObject concerning payer's account info--OBJECTNone
PixKeyPayer’s PIX keyNONOSTRINGNone
TaxNumberPayer’s CPF/CNPJYESYESSTRINGNone
BankPayer’s bank codeNOYESSTRINGNone
BankBranchPayer’s bank branchNOYESSTRINGNone
BankAccountPayer's account number without digitNOYESSTRINGNone
BankAccountDigitPayer’s account digitNOYESSTRINGNone
CustomerObject concerning customer's info--OBJECTNone
NameCustomer’s name (NP or LP)YESYESSTRINGNone
CustomerAccountInfoObject concerning customer's account info--OBJECTNone
PixKeyBeneficiary’s (who will do the collection) PIX keyYESYESSTRINGNone
PixKeyTypeBeneficiary’s (who will do the collection) PIX key typeYESYESSTRINGSocialSecurity = 0
TaxNumber = 1
E-mail = 2
PhoneNumber = 3 RandomKeyCode = 4
TaxNumberBeneficiary’s (who will do the collection) CPF/CNPJYESYESSTRINGNone
BankBeneficiary’s (who will do the collection) bank codeYESYESSTRINGNone
BankBranchBeneficiary’s (who will do the collection) bank branchYESYESSTRINGNone
BankAccountBeneficiary’s (who will do the collection) account number without digitYESYESSTRINGNone
BankAccountDigitBeneficiary’s (who will do the collection) account digitYESYESSTRINGNone
ReceiversObject concerning receivers' info--OBJECTNone
ValueAmount to be splitNONODECIMALNone
CollectionOrderProductTypeSplit typeNONOINTAmount = 0
Percentage = 1
ReceiverObject concerning receiver's info--OBJECTNone
NameReceiver’s nameNONOSTRINGNone
BirthDateReceiver’s birth dateNONODATETIMEYYYY-MM-DD format
ReceiverContactInfoObject concerning receiver's contact info--OBJECTNone
MailReceiver’s e-mailNONOSTRINGNone
PhoneReceiver’s e-mail phoneNONOSTRINGNone
ReceiverAccountInfoObject concerning receiver's account info--OBJECTNone
PixKeyReceiver’s PIX keyNONOSTRINGNone
TaxNumberReceiver’s CPF/CNPJNONOSTRINGNone
BankReceiver’s bank codeNONOSTRINGNone
BankBranchReceiver’s bank branchNONOSTRINGNone
BankAccountReceiver’s account number without digitNONOSTRINGNone
BankAccountDigitReceiver’s account digitNONOSTRINGNone

📘

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:

StatusStatus DescriptionTypeDescription
0CreatedSTRING (TEXT)The Collection Order was created
1PreAuthorizedSTRING (TEXT)The Collection Order was pre-authorized and the collection was generated
2AnalysingSTRING (TEXT)Payer under review in KYC process
3AuthorizedSTRING (TEXT)Payer Approved in KYC
6RegisteredSTRING (TEXT)The Collection was registered
8CanceledSTRING (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, ...}
9SettledSTRING (TEXT)Completed Billing Order (payment settled)
11Awaiting PaymentSTRING (TEXT)Awaiting Payment
12ErrorSTRING (TEXT)EXC0008 - Internal Processing Error
15Canceled-RefundSTRING (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