Guides
About PismoContact Us

Pix instant payments (Brazil)

Pix (short for "Pagamentos Instantaneos" in Portuguese, or "Instant Payments" in English) is a popular Brazilian instant payment system introduced in November 2020. Pix allows individuals and businesses to make electronic money transfers 24/7, with funds immediately available to the recipient. Pix transactions are executed in real time from a linked bank account. To send an instant payment or transfer, a Pix user needs only the recipient's Pix key or a QR (Quick Response) Code.

Example Pix payment scenario

Maria wants to pay her friend Pedro for a dinner they had together. They both have bank accounts in Brazil, and both have registered for Pix with their respective banks.

  1. Payment initiation:

    • Maria opens her banking app on her smartphone.
    • She selects the option to make a Pix payment.
    • She chooses Pedro as the recipient by entering his Pix key (let's say it's his mobile phone number) or by scanning his QR Code, which contains his Pix information. Note that this could also be Pedro's bank account information.
    • She enters the payment amount, an optional description (e.g., "Dinner payment"), and confirms the payment.

  2. Transaction notification:

    • Pedro's banking app receives a notification of the incoming Pix payment from Maria.
    • Pedro's banking app reviews the details, including the payment amounts, and accepts the Pix notification.

  3. Transaction conifirmation:

    • Maria's banking app sends the payment, and the funds are immediately transferred from Maria's bank account to Pedro's bank account.
    • Pedro receives a notification of the incoming Pix payment from Maria in his banking app

  4. Immediate availability:

    • Pedro can see the funds in his bank account immediately, even if it's outside of regular banking hours. He can use the money right away for any other transactions or withdrawals.

🚧

Deprecated Pix management endpoints removal

A number of deprecated Pix management endpoints are scheduled for removal on November 11, 2024. Please see the Pismo API endpoint deprecation and removal schedulefor more information.

Pix participants

Pismo is a technological solution that integrates indirect participants with direct participants, and direct participants with PSTIs (Information Technology Service Providers licensed by the Central Bank of Brazil).

If your company is interested in becoming a Pix participant, consult the process detailed below. Your Pismo representative can help guide you through this.

Process to become a direct Pix participant

General steps a company might take to become a direct participant in the Pix system:

Eligibility check - Ensure your company meets the eligibility criteria set by the Central Bank of Brazil. These criteria may include financial stability, operational capacity, compliance with relevant regulations, and more.

Financial institutions - Generally, only financial institutions are allowed to become direct participants in the PIX system. This includes banks, credit unions, and other authorized payment institutions.

Contact Central Bank or operator - Reach out to the Central Bank of Brazil or the operator responsible for PIX to express your interest in becoming a direct participant. This could involve sending inquiries, attending workshops, or accessing application guidelines from official sources.

Application process - Submit an application to the Central Bank or the relevant authority. This application will likely include detailed information about your company, its financial stability, operational capabilities, risk management practices, compliance with anti-money laundering (AML) and Know Your Customer (KYC) regulations, and more.

Technical integration - If your application is approved, you'll need to integrate your systems with the Pix infrastructure. This might involve technical processes to ensure seamless connectivity and interoperability with the Pix system.

Security and compliance - As a direct participant, your company will need to adhere to strict security protocols and comply with regulations to ensure the safety and integrity of the PIX system and its transactions.

Testing and certification - Before going live, you'll likely need to undergo testing and certification processes to ensure that your systems and processes function correctly within the Pix ecosystem.

Go live - Once your technical integration, security measures, and compliance checks are in place, you'll be allowed to go live and start processing transactions through the Pix system.

It's important to note that the process and requirements can vary and are subject to change. To get the most accurate and up-to-date information on becoming a direct participant in Brazil's Pix system, Pismo recommends visiting the official website of the Central Bank of Brazil or contacting them directly.

Pix (DICT) keys

A Pix key is a unique identifier linked to a bank account that allows a user to receive payments without the need to share bank account details, such as their account number and branch code, which are traditionally required for transfers. You can generate an encrypted Pix key with one of the following:

  • Taxpayer ID number
    • CPF - Cadastro de Pessoas Fisicas (Brazil - Individual Taxpayer Registry) number. Similar to a Social Security number in the US.
    • CNPJ - Cadastro Nacional de Pessoa Juridica (Brazil - National Registry of Legal Entities) number. Unique ID for legal entities, such as companies and organizations, in Brazil.
  • Email address
  • Mobile phone number
  • EVP - Endereco de pagamento virtual (virtual payment address). A randomly-generated UUID number.

All Pix keys are registered with the BCB, which maintains the Diretório de Identificadores de Contas Transacionais (DICT) - a national Pix key registry and database. Individual users can have up to five keys for each account they own. Institutional users can have up to 20 keys. Each key must be associated with only one bank account.

Pismo provides a Pix DICT Key API with endpoints for creating and managing keys both locally and with the DICT database.

Pix key transfer (key claim)

You can use the Pix API to transfer key ownership using a key claim .

Pismo defines two key claim types with the following enums:

  • OWNERSHIP - Transfer key ownership between users in the same or another bank.
  • PORTABILITY - Transfer key ownership for the same user to another bank.
Transfer key process

  1. Call Create key claim to notify the original bank that you want to transfer a key.

  2. Original bank sends an acknowledgement which Pismo processes and uses to generate a Pix key claim status changed event. To proceed to the next step, the status should be WAITING_RESOLUTION

  3. You have seven days to call Confirm key claim and confirm the claim. If no confirmation is received after 7 days the following happens, depending on key claim type:

    1. OWNERSHIP - The original bank proceeds with the transfer automatically. Proceed to step 4.
    2. PORTABILITY - The original bank automatically cancels the key claim. BCB receives the cancellation and contacts the receiving bank. End of process.

  4. BCB receives this confirmation and contacts the receiving bank.

    1. OWNERSHIP - Receiving bank confirms the claim with the end user [EMAIL or SMS]
      1. Receiving bank calls Complete key claim to complete the claim
    2. PORTABILITY - Receiving bank completes the claim automatically which Pismo processes. Key is created in the database. If no completion is received in 30 days, the original bank proceeds with the cancel automatically.

Pix transactions

There are 4 types of Pix transactions, as indicated with the following enums:

  • PIX_OUT - This occurs via the Pix-out transfer endpoint. Upon fund transfer completion, the platform generates a Pix-out notification received event - thestatus field indicates whether the transaction failed or succeeded.
  • PIX_IN - This also occurs via the Pix-out notification received endpoint when the funds are deposited in the payee's account. This could be a Pismo account or an external account. Upon completion, the platform generates a Pix-in notification received event - thestatus field indicates whether the transaction failed or succeeded.
  • PIX_OUT_REVERSAL - This occurs via the Pix reversal endpoint and reverses a PIX_OUT transfer. Upon completion, the platform generates a Pix-out reversed event with a status field indicating success or failure.
  • PIX_IN_REVERSAL - This also occurs via the Pix reversal endpoint and reverses a PIX_IN transfer from a payee's account, which can be a Pismo account or an external account. Upon completion, the platform generates a Pix-in reversed event with a status field indicating success or failure.

📘

Anti-fraud webhook for Pix transactions

Clients have the option to implement an anti-fraud webhook for Pix transactions to supplement the anti-fraud checking and validation Pismo does.

Generating dynamic QR Codes and BR Codes for Pix transactions

Pismo has a QR Code API for generating dynamic QR Codes. A dynamic QR Code is a type of QR Code that can be edited or modified after it has been created. Unlike static QR Codes, dynamic QR Codes allow for flexibility in the types of information they convey. They are particularly useful when there is a need to update QR Code information, such as changing a URL, updating contact details, or modifying product information.

You can generate two kinds of dynamic QR Codes: COB and COBV. COB is short for cobranca, which means charge in Portuguese. A COB QR Code has an expiration date while a COBV QR Code has a due date, fine, interest, and rebates.

Pismo also has a BR Code API for generating Brazilian Barcodes (BR Codes) - a standard barcode format used in Brazil for electronic payments. It is part of the Brazilian Payment System (SPB) and is regulated by the Central Bank of Brazil. The BR Code contains information about the payee, transaction details, and other data.

Scheduled transactions

You can schedule a Pix transaction for a future date. Basically, you specify a future date to make the payment, along with the transaction details, such as the payee (branch and account) and transaction amount. Pismo executes the transfer on the scheduled date.

Infraction reports

Infraction reports are used to tag transactions that a Pix user believes are fraudulent or otherwise invalid. In this situation, they can tag an infraction (report it to their bank or PSP), which then shares relevant transaction details with the other party’s bank or PSP. Either a payee or payer can make an infraction report. The Pix API provides endpoints for creating and resolving infraction reports.

There are 3 types of infraction reports:

  • FRAUD - Payer or payee requested.
  • REFUND_REQUEST - Initiated only by payer's payment service provider (PSP). Used to mark a key as fraudulent and asks for a refund.
  • REFUND_CANCELLED - Initiated only by payee's PSP. To indicate that a refund done by an infraction process was a fraud and needs to be returned,

Infraction report process

  1. Payment service provider (PSP) calls Create infraction report to open an infraction. This generates an Pix infraction status changed event with status OPEN.
  2. PSP can accept or reject infraction using endpoint Close infraction report. This generates a status event with status CLOSED. The analysis_results field can be either AGREED or DISAGREED

During the above steps, the PSP has the option to call Cancel infraction report to cancel the infraction. This generates a status event with status CANCELLED.

Refund requests

The Pix API provides endpoints for creating and managing transaction refund requests.

Refund request process

  1. Payment service provider (PSP) calls Create refund request to open a refund request . This generates a Pix reversal (refund) status changed with status OPEN.
  2. PSP can accept or reject refund request using endpoint Close refund. This generates a status event with status CLOSEDThe analysis_resultsfield can be either TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED or REJECTED

During the above steps, the PSP has the option to call Cancel refund to cancel the infraction. This generates a status event with status CANCELLED.

Pix events

See the Pix data events guide.

Updated 2 days ago