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:

Valid ways to enter a PIX key in the GetInfosPixKey API method

CPF (11 numeric characters, no letters or special characters)

CNPJ (14 numeric characters, no letters or special characters)

PhoneNumber (+ sign and 14 numeric characters, no letters and/or special characters)

E-mail

RandomKeyCode

According to the DICT (Directory of Transactional Account Identifiers), the supported PIX key formats are as follows:

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:

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:

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.