A PIX transaction, in the Brazilian instant payment ecosystem, is a fast and secure method to transfer funds between accounts in real-time, 24/7, including weekends and holidays. It's facilitated by the Central Bank of Brazil's innovative infrastructure, allowing for seamless transactions across different financial institutions.

It allows users to transfer money or make payments in several ways, using:

• DICT Keys: Unique identifiers such as email, phone number, CPF (Individual Taxpayer Registry Number), or CNPJ (National Registry of Legal Entities) linked to a bank account.
• QR Codes: Dynamically or statically generated codes that contain transaction information.
• Bank Instructions: Entering the recipient's bank account details manually if a DICT Key or QR Code is not available.

Understanding PIX Transaction States

In the PIX payment system, transactions undergo various states from initiation to completion. The DEBIT and CREDIT transactions each follow distinct paths:

DEBIT Transactions

Initiate in the CREATED state, from which they can either transition to PROCESSING, PENDING_SIGNATURES, or FAILED due to insufficient funds or network errors. From the PROCESSING state, the transaction can be processed successfully and the state will be changed to COMPLETED. Otherwise, it will be changed to FAILED. When transactions fail, a reason object is attached to the state, detailing the cause with a reasonCode. Possible reasonCodes include PROCESSING_ERROR("Transaction could not be processed."), UNFINISHED ("Transaction could not be finished.") and CANCELED ("Transaction was canceled.").

CREDIT Transactions

The transaction process begins in the CREATED state. If the transaction originates from a Dynamic QR Code payment and includes payer information, a validation check is conducted to confirm whether the tax ID provided matches the expected value. If this validation fails, the transaction will move to the REFUNDED state. Conversely, if the payer information is absent or the tax ID validation is successful, the transaction will progress to the COMPLETED state.

Sandbox Environment

To allow failure testing scenarios for our users, all the transactions created with amount ending with 9 will fail during the processing flow.