3 - Payment


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


PIX payments flow.

Payment Method's Flow


Illustration of the transaction flow for payments.

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"


MethodMethod to be usedYESSTRING-
PartnerIdInformation provided by FitBankYESINT-
BusinessUnitIdInformation provided by FitBankYESINT-
PixKeyPix Key to be queriedYESSTRING-
PixKeyTypePIX key typeYESINTSocialSecurity = 0 TaxNumber = 1
E-mail = 2 PhoneNumber = 3 RandomKeyCode = 4
TaxNumberCPF/CNPJ of who has a FitBank account and is consulting the informationsYESSTRING-

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)





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

TypeRegular ExpressionExampleComments
E-MAILW3C 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-426655440000Payment 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"


MethodMethod to be usedYESSTRING
PartnerIdInformation provided by FitBankYESINT
BusinessUnitIdInformation provided by FitBankYESINT
TaxNumberCPF/CNPJ of who has the PIX key and FitBank account and is consulting the informationYESSTRING
HashQRCode image or copy and paste hash codesYESSTRING

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"


PartnerIdInformation provided by FitBankYESINT-
BusinessUnitIdInformation provided by FitBankYESINT-
BankPayer's Bank Code (Ex.: “450”)YESSTRING-
BankBranchPayer's Bank Agency Code (Ex.: “0001”)YESSTRING-
BankAccountPayer's Bank Account (Ex.: “146492”)YESSTRING-
BankAccountDigitPayer's Account Digit (Ex.: “1”)YESSTRING-
ToTaxNumberReceiver's CPF/CNPJYESSTRING-
ToNameReceiver's nameYESNUMBER-
ToBankReceiver's Bank Code (Ex.: “450”)NOSTRING-
ToISPBReceiver's ISPB Bank CodeNOSTRINGBanking code of indirect banking institutions
ToBankBranchReceiver's Bank Agency Code (Ex.: “0001”)NOSTRING-
ToBankAccountReceiver's Bank Account (Ex.: “146492”)YESSTRING-
ToBankAccountDigitReceiver's Account Digit (Ex.: “1”)YESSTRING-
ValuePayment valueYESSTRING-
PixKeyPIX key of the receiverNOSTRING-
PixKeyTypePIX key typeNOINTSocialSecurity = 0 TaxNumber = 1
E-mail = 2 PhoneNumber = 3 RandomKeyCode = 4
AccountTypeType of the AccountYESINT0 = Current
1 = Salary
2 = Saving
3 = Payment
RateValueRate valueNONUMBER-
RateValueTypeType of the rate value chargeNOSTRING0 = Sent (value sent in the request)
1 = Default (value applied in the Business Unit)
2 = None (no charge applied)
IdentifierPayment identifier assigned by the payerYESSTRING-
PaymentDatePayment dateYESSTRING-
DescriptionOperation descriptionNOSTRING-
TagsList of tagsNOSTRINGE.g.: Transfer, API Test
OnlineTransferParameter that indicates whether the PIX transaction is synchronous and asynchronousNOBOOLBy default, fill in true
SearchProtocolUnique protocol generated after query of a PIX key or a PixQrCodeDESIRABLEINT-
CustomerMessageMessage between customersNOSTRING-

PIX instant payment request (with bank details)

API Method = GeneratePixOut


Payment information retrieval flow.

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.