1.3 Collection Order - Hybrid (Boleto with PIX QR Code)

Introduction

This offers the possibility of having hybrid billing, where it is possible, for the same biller, to choose the payment method that will be used offering an evolution of traditional billing and payment methods.

Instead of just having the conventional barcode, users will now have a QR Code to scan and make instant payments through Pix. This method offers significant advantages, especially for companies, who have lots to gain by using a more agile payment method.

The idea is to combine the practicality of Pix with the full functionality of bank slips, providing an efficient and comprehensive payment solution.

🚧

Version 1

This documentation is under construction and may be changed

How it works

Using our EndPoint GenerateCollectionOrder, indicating the CollectionOrderType = 2, you will be able to generate a Boleto with QR Code and give your customers the option of how to pay, either through Pix or barcode.

Receive notifications on the status of each payment

As soon as the payment is made, either through the payment of the barcode or PIX, you will receive the receipt information. You can also monitor changes in the status of boletos by receiving our webhooks.

Sending a hybrid 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:

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
InterestDateInterest charge dateNONODATETIMEYYYY-MM-DD format
DiscountObject--OBJECTNone
TypeDiscount TypeNONOINTAmount = 1
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