Guides

PIX and OpenFinance

Suggest Edits

PagFast provides two very effective ways to execute payments in Brazil, the PIX and the Payment Inititation via OpenFinance. If you are not used to these payment methods, we provide a comprehensive guide as follows.

As a payment gateway, PagFast mediates transactions between the end user and the banking entity that creates and processes the transactions as, for example, the Bank of Emission and the Bank of Payment.

These and other players in the Brazilian financial system, such as the Central Bank of Brazil, are deliberately excluded from the explanation below, in order to simplify understanding.

1. Payment with PIX

PIX is the most popular payment method in Brazil. This section is an overview of what an integrator should expect while integrating it.

If you are familiar with it, you might consider skipping this section, but if you are not, let's start with the Deposit (Cash in Flow) flow.

PIX Deposits (Cash Ins)

  1. The first step is a cash in request to PagFast. It should include the payer and the recipient info, as well as basic information about value.
    • In this request, the integrator must also provide a webhook notification URL, it will be used to inform each transaction status change.
  2. PagFast creates a transaction and provide payment codes for the end-user in two formats: a QRCode and a so called PIX Copy and Paste string. Both can be used by the end-user to execute the payment.
    • If the transaction can't be created by any reason, the payment is rejected.
  3. The integrator provides the QRCode and PIX Copy and Paste string to the end-user.
    • From this point on, the integrator should only wait for the payment to reach a final state.
  4. At some point in time, the user proceeds with his payment flow, executing or abandoning it.
  • Asynchronously, PagFast will send webhook notifications to the integrator, updating it about any transaction status change, including completing, error, cancelling etc.

PIX Withdraws (Cash outs)

For withdraws, the process is simpler. It's just about informing the destination account using a PIX Key as reference.

PIX Keys are in the core of the PIX payment system, they work as pointers to a real world bank account. End-users create PIX Keys using any of their bank apps, and can share these keys with anyone. So any payment made using that key, will be addressed to the destination bank account it points to.

PIX keys can have its format validated based on its type. As follows:

  • CPF - a unique identification number for individuals in Brazil of 11 digits, used for various purposes, including financial and government transactions.
    • Regular Expression: ^[0-9]{11}$
    • Example: 10777438666
    • Note: PagFast validates the CPF and denies requests for fake CPFs. While integration please use one of these real world CPFs for test: 14435549603, 13600642650, 10777438666.
  • PHONE - a valid phone number in Brazil.
    • Regular Expression: ^+[1-9][0-9]\d{1,14}$
    • Example: +5583986182244
    • Note: Brazilian phone number should start with +55, as showed in the above example.
  • EMAIL - a valid e-mail.
  • EVP - a type of PIX key that is generated using the OpenSSL EVP (Encryption Variable Provider) library.
    • Regular Expression: [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}
    • Example: b5195ee1-f054-47d1-9e90-ee57b74f60d9

In our API section, you will be presented to the PIX Cash In and PIX Cash Out endpoints, where you will be able to exercise these concepts.

2. Payment Inititation vai Open Finance

From the end-user perspective, the PIX payment depends on being familiar with bank apps and their typical PIX Area.

Here, we present the Open Finance payment inititation process, a method that helps users not to lose context when executing the payment, by making automatic redirects between the merchant website and the payment screens.

In order to familiarize you with this payment method, we provide a brief explanation of the steps involved in its integration and use, bellow:

  1. The first step is about requesting a Payment URL from PagFast, which will be provided to the paying user.
    In this request, the integrator must provide PagFast with the callback URL, to which the user will be redirected after completing or canceling the payment.
    • Integrators must also provide a webhook notification URL, what will be called to inform transaction status changes.
  2. PagFast returns the Payment URL to the integrator.
  3. The integrator decides how to open and display the provided URL to the end-user (e.g.: a modal over the current merchant page). From this point on, the integrator should only wait for the end-user action.
  4. In case of payment completion or failure, the interaction is finished, and the end-user is redirected by PagFast to the callback URL provided by the integrator.
  • Asynchronously, PagFast will send webhook notifications to the integrator, updating it about any transaction status change, including error, cancelling etc.

⏱️

Processing time

The average time that the finance system takes to process OpenFinance or PIX cashins is around 3 seconds, while cashouts will normally from 10 to 20 seconds.

OpenFinance Testing Environment

PagFast provides a graphical user interface to simulate OpenFinance end-user payment. We present some details of the payment below:

  • When the integrator receives the Payment URL and redirects the user, a loading screen will be displayed to initiate the banking interaction by the user.
  • In our environment, we allow simulating the action of the payer (user), confirming the payment or forcing its failure, as shown in the image below.

During the simulation flow, the integrator should receive transaction status changes via webhook, and the payer will be redirected to the callback URL provided in the origin request.

For both the PIX and Open Finance, any created transaction and their status are visible in the Administrative Portal, on the Sales (Cash In) and the Withdraws (Cash Out) menus.

📘

Want a deeper understanding?

Updated 11 months ago

What’s Next