Pix is the instant payments ecosystem implementation led by the Central Bank of Brazil (BCB) to enable online money transfers with reduced costs, increased safety and 24/7 availability. Transfers occur directly from the payer’s account to the payee’s account, without the need for intermediaries, resulting in lower transaction costs.

Pix is available to both physical and legal persons, and both need to have an identifier key registered with some financial entity (banks, fintechs or payment institutions) to proceed with the transaction.

According to the eligibility criteria set forth by the BCB, certain financial entities will be required to offer this payment method, while others may optionally offer it or not be eligible to participate.

In this article, we will explain how to extend your Payment Provider Protocol implementation to allow stores to offer Pix as an additional payment method to their clients.

✔️ If you want to know more about instant payments in Brazil, we have prepared a blog post with all the implications of this new payment method. You can also check out the FAQ provided by the BCB for more details.

This tutorial assumes you are already a VTEX Partner and understand how the Payment Provider Protocol works.

If you are ready to develop the middleware that implements our Payment Provider Protocol, you should be aware of these requirements:

• All endpoints must be served over HTTPS on port 443 with TLS 1.2 support. Connections over non-secured HTTP will not be accepted under any circumstances.

• The integrator must create a subdomain or a domain name for the provider endpoints. IP addresses will not be accepted as names under any circumstances.

• The middleware must consistently respond within established response times. We enforce a maximum response time of 5 seconds for homologation tests, as well as a maximum response time of 20 seconds to any other API request.

While our protocol describes nine endpoints for implementation, not all of them are applicable when integrating Pix instant payments. Regarding the two provider flows:

• Payment Flow: six endpoints that must be mandatory implemented.

• Configuration Flow endpoints: three endpoints whose implementation is optional and currently not available for Pix.

The table below gives further detail on the applicability of each endpoint to Pix instant payments.

Provider Flow	Endpoint	Applicable to Pix?
Payment	List Payment Provider Manifest	✅ Yes
Payment	Create Payment	✅ Yes
Payment	Cancel Payment	✅ Yes
Payment	Capture Payment	✅ Yes
Payment	Refund Payment	✅ Yes
Payment	Inbound Request (BETA)	✅ Yes
Payment	Create Authorization Token	⛔ No
Payment	Provider Authentication	⛔ No
Payment	Get Credentials	⛔ No

Pix is not available for marketplace clients that use the Checkout Split.

The following JSONs are just examples. Each partner must adapt the models to their own realities, with the data needed to realize the integration.

The first information your provider has to inform us is which are the payment methods that it handles. To do so, you can make an API request using the GET List Payment Provider Manifest route.

The expected response is:

Pix still does not handle payment split, but this feature may be released in the future. For more information on payment methods that currently accept split, check the List Payment Provider Manifest endpoint.

Now you have to create a new payment method. To do this, use the route POST Create Payment.

A lot of information is required from the cart data in the Smart Checkout, so be careful and validate all payload information.

See an example of the Create Payment request:

As a result, we expect the following response:

Have in mind that, by default, the QRCode must have five minutes (300 seconds) expiration time. Also, the partner must respect the callback time (20 seconds).

For more information, access the Create Payment endpoint.

To cancel a payment, you must already have created one. To do so, you will make an API request using the route POST Cancel Payment.

See an example of the Cancel Payment request:

After the provider realizes the payment cancelation, we expect a response like this:

For more information, access the Cancel Payment endpoint.

If your transaction was completed successfully, the provider can settle the payment.

Thus, in order to settle the payment, VTEX will send the information below through the POST Settle Payment.

See an example of the Settle Payment request:

The response should be similar to the following response body:

For more information, access the Settle Payment endpoint.

The provider should be ready to receive the following request through the POST Refund Payment.

See an example of the Refund Payment request:

The expected response is:

For more information, access the Refund Payment endpoint.

The last endpoint, the POST Inbound Request (BETA), implements a URL that facilitates a direct connection between our Gateway service and the Payment Provider.

See an example of the Inbound Request (BETA) request:

As a result, the client should send the following response:

The Inbound Request (BETA) is mandatory only for integrations via Payment Provider Protocol with an external Payment App. If the Pix payment method was implemented via VTEX Payment App, the Inbound Request is not necessary. For more information, access the Inbound Request (BETA).

For more information about the Pix, access its FAQ.

After completing all integration steps, you should complete our homologation process to allow VTEX stores to use your provider as a payment method.