1.1 Collection Order - PIX
Introduction
The ability to generate invoices using the PIX QR Code offers a series of advantages for businesses, as it simplifies the billing process and enables instant settlement, ensuring that funds are available immediately after the transaction is completed. This is especially beneficial for companies that rely on fast cash flow.
In summary, billing with PIX QR Code offers a convenient, fast, economical, and secure payment experience for all parties involved, consolidating its position as one of the most effective and efficient ways to transact in the modern financial landscape.
How it works
Using our EndPoint GenerateCollectionOrder, indicating the CollectionOrderType = 3, you will be able to generate a QR Code.
Receive notifications on the status of each payment
As soon as the payment is made, either through the payment of the PIX, you will receive the receipt information. You can also monitor changes in the status of QR Codes by receiving our webhooks.
Sending a collection order
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": 65,
"BusinessUnitId": 63,
"Identifier": "2019380948908423807893247",
"CollectionOrderType": 0,
"PrincipalValue": 0.50,
"RebateValue": 0.00,
"InterestValue": 0.00,
"FineValue": 0.00,
"FinePercent": 0.00,
"InterestPercent": 0.00,
"FineDate": "2022-10-31",
"InterestDate": "2022-10-31",
"DueDate": "2022-11-10",
"ExpirationDate": "2022-11-29",
"InstructionsToPayer": "Pagamento referente a compra virtual",
"Payer": {
"Name": "Hellem Moura",
"BirthDate": "2002-09-21",
"ConstitutionDate": "2022-09-21",
"Gender": 0,
"MaritalStatus": 0,
"Ocuppation": "dev",
"MotherName": "Maria",
"Nationality": "Brasileiro",
"Country": "Brsil",
"BirthCity": "Crateús",
"BirthState": "Ceará",
"CompanyType": 0,
"CompanyActivity": "Dev",
"PayerContactInfo": {
"Mail": "[email protected]",
"Phone": "88999999999"
},
"PayerAccountInfo": {
"PixKey": "78690450041",
"TaxNumber": "696159660001",
"Bank": "",
"BankBranch": "",
"BankAccount": "",
"BankAccountDigit": ""
}
},
"Customer": {
"Name": "Jose Reinaldo Sales Soares",
"CustomerAccountInfo": {
"PixKey": "83964318094",
"PixKeyType":"0",
"TaxNumber": "69615966000130",
"Bank": "450",
"BankBranch": "0001",
"BankAccount": "5454573",
"BankAccountDigit": "4"
}
},
"Receivers": {
"CollectionOrderProductType": 1,
"Receiver": [
{
"SplitValue": 30,
"Name": "JORDY BARROSO",
"BirthDate": "2002-09-21",
"ReceiverContactInfo": {
"Mail": "[email protected]",
"Phone": "88999999999"
},
"ReceiverAccountInfo": {
"PixKey": "82781627194",
"TaxNumber": "736.333.810-82",
"Bank": "450",
"BankBranch": "0001",
"BankAccount": "198839682",
"BankAccountDigit": "4"
}
}
]
}
}
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 |
FineDate | Fine charging date | NO | NO | DATETIME | YYYY-MM-DD format |
InterestDate | Interest charging date | NO | NO | DATETIME | YYYY-MM-DD format |
DueDate | Due date for collection | YES | YES | DATETIME | YYYY-MM-DD format |
ExpirationDate | Expiration date of charge | YES | YES | DATETIME | YYYY-MM-DD format |
InstructionsToPayer | Message or description that can be added if desirable | NO | NO | STRING | Maximum number of accepted characters: 100 characters |
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 |
PayerContactInfo | Object concerning payer's contact info | - | - | OBJECT | None |
Payer’s e-mail | NO | YES | STRING | None | |
Phone | Payer’s phone | NO | 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 4 months ago