3 - Payment
Payments
There are several ways to make a PIX payment to transfer money quickly and seamlessly.
When requesting a payment (PixOut) the client application receives the user’s request and sends it to our API. FitBank communicates with the Central Bank (BC) and contacts the receiving institution, where the recipients account will be credited with the payment.
PIX Flow
Payment Method's Flow
PIX Key information request
API Method = GetInfosPixKey
This method consults and validates the PIX key for the specific payment that is to be made and returns the associated bank information of the recipient. It can consult any PIX key registered in any bank instituition.
The TaxNumber used in the request can be of anyone consulting the key, as long as the user performing the search has a FitBank account.
{
"Method": "GetInfosPixKey",
"PartnerId": 20446,
"BusinessUnitId": 40883,
"PixKey": "[email protected]",
"PixKeyType": 2,
"TaxNumber": "20696707000191"
}
Description:
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | Method to be used | YES | STRING | - |
PartnerId | Information provided by FitBank | YES | INT | - |
BusinessUnitId | Information provided by FitBank | YES | INT | - |
PixKey | Pix Key to be queried | YES | STRING | - |
PixKeyType | PIX key type | YES | INT | SocialSecurity = 0 TaxNumber = 1 E-mail = 2 PhoneNumber = 3 RandomKeyCode = 4 |
TaxNumber | CPF/CNPJ of who has a FitBank account and is consulting the informations | YES | STRING | - |
Valid ways to enter a PIX key in the GetInfosPixKey API method
CPF (11 numeric characters, no letters or special characters)
Valid | Invalid |
---|---|
12345678901 | 123.456.789-01 |
123AS678901 | |
123AS678901 |
CNPJ (14 numeric characters, no letters or special characters)
Valid | Invalid |
---|---|
98740555000174 | 98.740.555/0001-74 |
9874#0555000174 | |
9874PJ0555000174 |
PhoneNumber (+ sign and 14 numeric characters, no letters and/or special characters)
Valid | Invalid |
---|---|
+5585900000000 | +558500000000 |
+55(85)00000000 | |
+55(85)900000000 | |
+55(85)90000-0000 | |
+85900000000 | |
+8500000000 | |
+5585AA0000000 | |
-55(85)900000000 | |
-5585900000000 | |
-5585AA0000000 | |
+5585#00000000 | |
5585900000000 | |
85900000000 |
RandomKeyCode
Valid | Invalid |
---|---|
123e4567-e89b-12d3-a456-426655440000 | 123e4567e89b12d3a456426655440000 |
123@4567-e89b-12d3-a456-426655440000 | |
123e4567-g89b-12d3-a456-426655440000 | |
123e4567-e89b-12z3-a456-426655440000 | |
123e4567-e89b-12d3-a456-42665k44000 |
According to the DICT (Directory of Transactional Account Identifiers), the supported PIX key formats are as follows:
Type | Regular Expression | Example | Comments |
---|---|---|---|
CPF | ^[0-9]{11}$ | 12345678901 | |
CNPJ | ^[0-9]{14}$ | 12345678901234 | |
PHONE | ^+[1-9][0-9]\d{1,14}$ | +5510998765432 | |
W3C HTML5 Valid e-mails | [email protected] | E-mail should have 77 characters at most and must be in lowercase | |
EVP (Random Key) | [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} | 123e4567-e89b-12d3-a456-426655440000 | Payment Virtual Address (Random Key) is a kind of key generated by DICT |
PIX Hash (QrCode copy and paste “Copia e Cola”) information retrieval
API Method = GetInfosPixHashCode
This method validates the PIX QrCode copy and paste “Copia e Cola” hash code for the specific payment that is to be made and returns the associated bank information of the recipient.
Important: The hash code is generated in base64 format, but to be queried in this API method, it must be decoded.
{
"Method": "GetInfosPixHashCode",
"PartnerId": 125,
"BusinessUnitId": 136,
"TaxNumber": "12345678912",
"Hash": "String"
}
Description:
Parameter | Description | Mandatory | Type |
---|---|---|---|
Method | Method to be used | YES | STRING |
PartnerId | Information provided by FitBank | YES | INT |
BusinessUnitId | Information provided by FitBank | YES | INT |
TaxNumber | CPF/CNPJ of who has the PIX key and FitBank account and is consulting the information | YES | STRING |
Hash | QRCode image or copy and paste hash codes | YES | STRING |
PIX instant payment request
API Method = GeneratePixOut
After the GetInfosPixKey or GetInfosPixHashCode response with the PIX Key and receiver's data, in the payment request must informed the value of the transaction Value, the PaymentDate, receiver's and payer's bank data, and a Description, if desirable.
When querying the PIX key via GetInfosPixKey method, and when querying the hash code via GetInfosPixHashCode method, the beneficiary's bank details are returned, including the ISPB code of the destination banking institution. This code refers to the Brazilian Payment System Identifier (ISPB), unique for each direct or indirect banking institution, and allows the payment to be made by informing the bank code (ToBank) or the ISPB code (ToISPB).
This method can be used for common payment transactions (throug PIX key and bank data), as well as QrCode payments.
To pay a QrCode, it is needed to enter the payee's and payer's bank details, the PIX key, the amount of the charge, and the SearchProtocol generated in the Hash Code query via the GetInfosPixHashCode method.
In this case, the field PixKey must be filled with the PIX key of the who will receive the payment by QrCode. On the other hand, the field PixKeyType must be filled as null, because it is not necessary to inform the type of key in this operation, since the FitBank system recognizes and sends the payment properly using the other information provided.
Important: In cases of PIX payment via PIX key, it is highly recommended that after the key query (via the GetInfosPixKey method) the search protocol generated must be informed in the SearchProtocol field, so that the transaction has an extra layer of security, undergoes a more authentic reconciliation, and follows the standards recommended by the Central Bank.
{
"Method": "GeneratePixOut",
"PartnerId": 30519,
"BusinessUnitId": 51138,
"TaxNumber": "84928589076",
"Bank": "450",
"BankBranch": "0001",
"BankAccount": "440246",
"BankAccountDigit": "3",
"ToTaxNumber": "88042486000171",
"ToName": "Ariane Fitbank",
"ToBank": "450",
"ToISPB": "13203354",
"ToBankBranch": "12345",
"ToBankAccount": "12345677",
"ToBankAccountDigit": "32641",
"Value": 123.45,
"PixKey": "17699384008",
"PixKeyType": 0,
"AccountType": 0,
"RateValue": 0,
"RateValueType": 0,
"Identifier": "ac1e955d-905d-436f-9881-f8dbdda58c73",
"PaymentDate": "2021/08/11",
"Description": "string",
"Tags": ["string", "string"],
"OnlineTransfer": true,
"SearchProtocol": 856974,
"CustomerMessage": "string"
}
Description:
Parameter | Description | Mandatory | Type | Comments |
---|---|---|---|---|
Method | GeneratePixOut | YES | STRING | - |
PartnerId | Information provided by FitBank | YES | INT | - |
BusinessUnitId | Information provided by FitBank | YES | INT | - |
TaxNumber | Payer's CPF/CNPJ | YES | STRING | - |
Bank | Payer's Bank Code (Ex.: “450”) | YES | STRING | - |
BankBranch | Payer's Bank Agency Code (Ex.: “0001”) | YES | STRING | - |
BankAccount | Payer's Bank Account (Ex.: “146492”) | YES | STRING | - |
BankAccountDigit | Payer's Account Digit (Ex.: “1”) | YES | STRING | - |
ToTaxNumber | Receiver's CPF/CNPJ | YES | STRING | - |
ToName | Receiver's name | YES | NUMBER | - |
ToBank | Receiver's Bank Code (Ex.: “450”) | NO | STRING | - |
ToISPB | Receiver's ISPB Bank Code | NO | STRING | Banking code of indirect banking institutions |
ToBankBranch | Receiver's Bank Agency Code (Ex.: “0001”) | NO | STRING | - |
ToBankAccount | Receiver's Bank Account (Ex.: “146492”) | YES | STRING | - |
ToBankAccountDigit | Receiver's Account Digit (Ex.: “1”) | YES | STRING | - |
Value | Payment value | YES | STRING | - |
PixKey | PIX key of the receiver | NO | STRING | - |
PixKeyType | PIX key type | NO | INT | SocialSecurity = 0 TaxNumber = 1 E-mail = 2 PhoneNumber = 3 RandomKeyCode = 4 |
AccountType | Type of the Account | YES | INT | 0 = Current 1 = Salary 2 = Saving 3 = Payment |
RateValue | Rate value | NO | NUMBER | - |
RateValueType | Type of the rate value charge | NO | STRING | 0 = Sent (value sent in the request) 1 = Default (value applied in the Business Unit) 2 = None (no charge applied) |
Identifier | Payment identifier assigned by the payer | YES | STRING | - |
PaymentDate | Payment date | YES | STRING | - |
Description | Operation description | NO | STRING | - |
Tags | List of tags | NO | STRING | E.g.: Transfer, API Test |
OnlineTransfer | Parameter that indicates whether the PIX transaction is synchronous and asynchronous | NO | BOOL | By default, fill in true |
SearchProtocol | Unique protocol generated after query of a PIX key or a PixQrCode | DESIRABLE | INT | - |
CustomerMessage | Message between customers | NO | STRING | - |
PIX instant payment request (with bank details)
API Method = GeneratePixOut
The same method as above is used (GeneratePixOut), however, it is not necessary to query the PIX key or enter it in the PixKey and PixKeyType fields. In this case, besides the payment amount and the payment date, the destination account data must be rightfully informed in the request, in the fields seen below:
ToTaxNumber, ToName, ToBank, ToBankBranch, ToBankAccount and ToBankAccountDigit
The fields PixKey and PixKeyType must be filled in as null.
Important: If the PIX payment destination account has digit X, it is recommended that this digit must be replaced with 0. Thus, the BankAccountDigit field must be filled in as 0.
This is necessary because the FitBank API doesn't consider alphanumeric values, and to avoid errors and barring in the operation, the best course of action is to adapt the way the banking information is applied in the requests.
PixOut Status sent in the API:
- Created: Transaction has been initiated and will be processed
- CanBeRegister: The account has been charged and the transaction is being processed
- Registering: Transaction has been prepared and will be registered in the SPI
- Registered: Transaction was registered in the SPI
- Paid or Settled: Settled transaction
- Cancel or Canceled: Canceled transaction
Important: Only the Registering/Registered/Paid/ Canceled statuses are returned via webhooks and the customer can choose which status they want to receive. However, it's important to note that while Paid status is returned via webhooks, it will be returned as Settled via APIs. Their function and meaning are the same, as both indicate that the PIX payment has been settled.
On an other note, status Cancel will be returned in webhooks, and status Canceled will be returned through APIs. The meaning is the same in both situations, since they both refer to a canceled PIX payment.
Note: When the PixOut operation is scheduled, that is, it was generated to be settled only on a future day, the transaction is stored in FitBank's base under the Created status, and in this case, no notification webhook is received. Thus, to query the status of the PixOut, the method GetPixOutById must be used. When the scheduled payment day finally arrives, the customer will receive a webhook notifying that the payment has been settled, and it will be under Paid status.
Updated 4 months ago