1.2 Collection Order

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",
  "interestDate" : "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
InterestDate	Interest charge date	NO	NO	DATETIME	YYYY-MM-DD format
Discount	Object	-	-	OBJECT	None
Type	Discount Type	NO	NO	INT	Amount = 1
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
Mail	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
Mail	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

1.2 Collection Order - Boleto

Introduction

🚧
Version 1

How it works

Receive notifications on the status of each payment

Sending a collection order in Brazil

Description:

📘
Explanation

Collection order status:

Introduction

🚧Version 1

How it works

Receive notifications on the status of each payment

Sending a collection order in Brazil

Description:

📘Explanation

Collection order status:

🚧
Version 1

📘
Explanation