Transaction
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.
Updated 13 days ago