3.1 Generate PixOut
Pix Payment Information
There are 3 ways to make Pix payments:
- Bank Data - In this case, simply enter the recipient's bank details (Bank, Branch, Account and Account Digit).
- Pix Key - To make a payment via Pix Key, you must first consult the Pix Key information (API Method: GetInfosPixKey).
- Hash Code - To make a payment via Pix Copy and Paste, you need to retrieve the QRCode information (API Method: GetInfosPixHashCode).
The GeneratePixOut method is used for all payment methods and regardless of the method chosen, it is essential to inform the amount and date of payment.
Payment via Bank Data
In this case, the payer must provide the recipient's bank details, and it is compulsory to fill in the fields:
ToTaxNumber, ToName, ToBank, ToBankBranch, ToBankAccount and ToBankAccountDigit.
The PixKey and PixKeyType fields 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.
Payment via Pix Key
API Method = GetInfosPixKey
Before starting the payment in GeneratePixOut, the customer must access the GetInfosPixKey method. This method checks whether the Pix Key entered for the payment is valid and returns the beneficiary's bank details needed to make the Pix payment.
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.
Payment via Hash Code
API Method = GetInfosPixHashCode
Before starting the payment in GeneratePixOut, the customer needs to access the GetInfosPixHashCode method to obtain the SearchProtocol, the Pix key and the beneficiary's bank details, which are essential for making the payment.
Important: The field PixKeyType must be filled as null, because it is not necessary to inform the type of key in this operation.
For more information on the GetInfosPixKey and GetInfosPixHashCode methods, visit: Payments Pix
GeneratePixOut
API Method = GeneratePixOut
This method can be used for common payment transactions (throug PIX key and bank data), as well as QrCode payments.
{
"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"],
"SearchProtocol": null,
"CustomerMessage": "string"
}
{
"Method": "GeneratePixOut",
"PartnerId": 30519,
"BusinessUnitId": 51138,
"TaxNumber": "84928589076",
"Bank": "450",
"BankBranch": "0001",
"BankAccount": "440246",
"BankAccountDigit": "3",
"ToTaxNumber": "88042486000171",
"ToName": "Ariane Fitbank",
"PixKey": "17699384008",
"Value": 123.45,
"RateValue": 0,
"RateValueType": 0,
"Identifier": "ac1e955d-905d-436f-9881-f8dbdda58c73",
"PaymentDate": "2021/08/11",
"Description": "string",
"Tags": ["string", "string"],
"SearchProtocol": 856974,
"CustomerMessage": "string"
}
{
"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"],
"SearchProtocol": 856975,
"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 | - |
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 |
SearchProtocol | Unique protocol generated after query of a PIX key or a PixQrCode | DESIRABLE | INT | - |
CustomerMessage | Message between customers | NO | STRING | - |
PixOut Status sent in the API:
- Created: Transaction has been initiated and will be processed
- Registered: Transaction was registered in the SPI
- Paid or Settled: Settled transaction
- Cancel or Canceled: Canceled transaction
Important: Only the 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.
User Experience
In order to guarantee a satisfactory end-user experience, it is necessary to comply with the obligations and recommendations for the minimum user experience established by Bacen. This prototype demonstrates the minimum criteria required to guarantee an adequate experience in Pix transactions for payers. The screens shown are merely illustrative and are intended to facilitate understanding of the commands and guidelines established.
Banking journey for user experience
Main Rules:
- Quick Access: The Pix environment must be easy to access and visible immediately after logging in.
- Payment initiation methods:
- Via Key: Accept keys of the type CPF/CNPJ, cell phone number, e-mail and random key.
- QR Code scanning
- Manual Data Entry
- Pix Copy and Paste
- Shortcut to Service: Provide a shortcut (icon or button) to the PSP service channel for handling complaints involving Pix.
Updated 17 days ago