Documentation
Feedback
Guides
API Reference

Guides
Integration Guides
Payments
Pix: Instant Payments in Brazil

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.

{"base64":"  ","img":{"width":1436,"height":938,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":611480,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/payments-integration-pix-instant-payments-in-brazil-0.png"}}

✔️ 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.

Integration conditions

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:

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

Provider FlowEndpointApplicable to Pix?
PaymentList Payment Provider Manifest✅ Yes
PaymentCreate Payment✅ Yes
PaymentCancel Payment✅ Yes
PaymentCapture Payment✅ Yes
PaymentRefund Payment✅ Yes
PaymentInbound Request (BETA)✅ Yes
PaymentCreate Authorization Token⛔ No
PaymentProvider Authentication⛔ No
PaymentGet 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.

Integration steps

Establish the payment methods available

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:


_56
{
_56
"paymentMethods": [
_56
{
_56
"name": "Visa",
_56
"allowsSplit": "onCapture"
_56
},
_56
{
_56
"name": "Pix",
_56
"allowsSplit": "disabled"
_56
},
_56
{
_56
"name": "Mastercard",
_56
"allowsSplit": "onCapture"
_56
},
_56
{
_56
"name": "American Express",
_56
"allowsSplit": "onCapture"
_56
},
_56
{
_56
"name": "BankInvoice",
_56
"allowsSplit": "onAuthorize"
_56
},
_56
{
_56
"name": "Privatelabels",
_56
"allowsSplit": "disabled"
_56
},
_56
{
_56
"name": "Promissories",
_56
"allowsSplit": "disabled"
_56
}
_56
],
_56
"customFields": [
_56
{
_56
"name": "Merchant's custom field",
_56
"type": "text"
_56
},
_56
{
_56
"name": "Merchant's custom select field",
_56
"type": "select",
_56
"options": [
_56
{
_56
"text": "Field option 1",
_56
"value": "1",
_56
},
_56
{
_56
"text": "Field option 2",
_56
"value": "2",
_56
},
_56
{
_56
"text": "Field option 3",
_56
"value": "3",
_56
}
_56
]
_56
}
_56
]
_56
}

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.

Create Pix Payment Method

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:


_74
{
_74
"reference": "32478982",
_74
"orderId": "v967373115140abc",
_74
"transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
_74
"paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
_74
"paymentMethod": "Pix",
_74
"paymentMethodCustomCode": null,
_74
"merchantName": "mystore",
_74
"value": 4307.23,
_74
"currency": "BRL",
_74
"installments": 31,
_74
"deviceFingerprint": "12ade389087fe",
_74
"card": {
_74
"holder": null,
_74
"number": null,
_74
"csc": null,
_74
"expiration": {
_74
"month": null,
_74
"year": null
_74
}
_74
},
_74
"miniCart": {
_74
"shippingValue": 11.44,
_74
"taxValue": 10.01,
_74
"buyer": {
_74
"id": "c1245228-1c68-11e6-94ac-0afa86a846a5",
_74
"firstName": "John",
_74
"lastName": "Doe",
_74
"document": "01234567890",
_74
"documentType": "CPF",
_74
"email": "john.doe@example.com",
_74
"phone": "+5521987654321"
_74
},
_74
"shippingAddress": {
_74
"country": "BRA",
_74
"street": "Praia de Botafogo St.",
_74
"number": "300",
_74
"complement": "3rd Floor",
_74
"neighborhood": "Botafogo",
_74
"postalCode": "22250040",
_74
"city": "Rio de Janeiro",
_74
"state": "RJ"
_74
},
_74
"billingAddress": {
_74
"country": "BRA",
_74
"street": "Brigadeiro Faria Lima Avenue",
_74
"number": "4440",
_74
"complement": "10th Floor",
_74
"neighborhood": "Itaim Bibi",
_74
"postalCode": "04538132",
_74
"city": "São Paulo",
_74
"state": "SP"
_74
},
_74
"items": [
_74
{
_74
"id": "132981",
_74
"name": "My First Product",
_74
"price": 2134.90,
_74
"quantity": 2,
_74
"discount": 5.00
_74
},
_74
{
_74
"id": "123242",
_74
"name": "My Second Product",
_74
"price": 21.98,
_74
"quantity": 1,
_74
"discount": 1.00
_74
}
_74
]
_74
},
_74
"url": "https://admin.mystore.example.com/orders/v32478982",
_74
"callbackUrl": "https://api.example.com/some-path/to-notify/status-changes?an=mystore",
_74
"returnUrl": "https://mystore.example.com/checkout/order/v32478982"
_74
}

As a result, we expect the following response:


_15
{
_15
"paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
_15
"status": "undefined",
_15
"tid": "TID1578324421",
_15
"authorizationId": null,
_15
"nsu": null,
_15
"code": "APP123",
_15
"paymentAppData": {
_15
"payload": "{\"code\":\"https://bacen.pix/pix/code\",\"qrCodeBase64Image\":\"iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAABQGlDQ1BJQ0MgUHJvZmlsZQAAKJFjYGDiSSwoyGFhYGDIzSspCnJ3UoiIjFJgf8LAxSDMwMkgwiCZmFxc4BgQ4ANUwgCjUcG3awyMIPqyLsgspwWXFu+Xeyundb6w0WL33C5M9SiAKyW1OBlI/wHihOSCohIGBsYYIFu5vKQAxG4AskWKgI4CsqeA2OkQ9goQOwnC3gNWExLkDGRfALIFkjMSU4DsB0C2ThKSeDoSG2ovCLAZGZkbhBNwKKmgJLWiBEQ75xdUFmWmZ5QoOAJDJ1XBMy9ZT0fByMDIgIEBFNYQ1Z9vgMOQUYwDIZapzMBgmQEUfIQQSxNmYNiZzsDAU4UQU5/PwMBrxMBw5GJBYlEi3AGM31iK04yNIGzu7QwMrNP+//8M9Ca7JgPD3+v////e/v//32UMDMy3GBgOfAMA4+RdqZ9YRkcAAABWZVhJZk1NACoAAAAIAAGHaQAEAAAAAQAAABoAAAAAAAOShgAHAAAAEgAAAESgAgAEAAAAAQAAAAKgAwAEAAAAAQAAAAIAAAAAQVNDSUkAAABTY3JlZW5zaG900Fpo3gAAAdJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDUuNC4wIj4KICAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgICAgICAgeG1sbnM6ZXhpZj0iaHR0cDovL25zLmFkb2JlLmNvbS9leGlmLzEuMC8iPgogICAgICAgICA8ZXhpZjpQaXhlbFhEaW1lbnNpb24+MjwvZXhpZjpQaXhlbFhEaW1lbnNpb24+CiAgICAgICAgIDxleGlmOlVzZXJDb21tZW50PlNjcmVlbnNob3Q8L2V4aWY6VXNlckNvbW1lbnQ+CiAgICAgICAgIDxleGlmOlBpeGVsWURpbWVuc2lvbj4yPC9leGlmOlBpeGVsWURpbWVuc2lvbj4KICAgICAgPC9yZGY6RGVzY3JpcHRpb24+CiAgIDwvcmRmOlJERj4KPC94OnhtcG1ldGE+Cl89Cn4AAAASSURBVAgdY/wPBAxAwAQiQAAAPfgEAIAu9DkAAAAASUVORK5CYII=\"}"
_15
},
_15
"message": "The customer needs to finish the payment flow",
_15
"delayToAutoSettle": 1209600,
_15
"delayToAutoSettleAfterAntifraud": 120,
_15
"delayToCancel": 300
_15
}

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.

Cancel a Payment

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:


_10
{
_10
"paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
_10
"requestId": "1234"
_10
}

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


_10
{
_10
"paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
_10
"message": "Successfully cancelled",
_10
"code": null,
_10
"cancellationId": "1457BD07E6",
_10
"requestId": "1234"
_10
}

For more information, access the Cancel Payment endpoint.

Settle Payment (capture)

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:


_10
{
_10
"paymentId": "5B127F1E0C944EF9ACE264FEC1FC0E91",
_10
"transactionId": "611966",
_10
"value": 20.0,
_10
"requestId": "5678"
_10
}

The response should be similar to the following response body:


_10
{
_10
"paymentId": "5B127F1E0C944EF9ACE264FEC1FC0E91",
_10
"settleId": "CEE16492C6",
_10
"value": 20.0,
_10
"code": null,
_10
"message": null,
_10
"requestId": "5678"
_10
}

For more information, access the Settle Payment endpoint.

Refund Payment

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

See an example of the Refund Payment request:


_10
{
_10
"paymentId": "VQKIIBUVOFDBIDLKZPOWSKETDYWCMJSACDVXWFCJVSKXGYVBBVISZRJLLQEKERJEMDYEINOUMFAZZGNEDVBQBABLUKLFBSEEIGLCAQTOGOGURKLFCAHJQTDMBNKYBIST",
_10
"transactionId": "611966",
_10
"settleId": "31018A3281",
_10
"value": 10.0,
_10
"requestId": "5678"
_10
}

The expected response is:


_10
{
_10
"paymentId": "VQKIIBUVOFDBIDLKZPOWSKETDYWCMJSACDVXWFCJVSKXGYVBBVISZRJLLQEKERJEMDYEINOUMFAZZGNEDVBQBABLUKLFBSEEIGLCAQTOGOGURKLFCAHJQTDMBNKYBIST",
_10
"refundId": null,
_10
"value": 0.0,
_10
"code": "refund-manually",
_10
"message": "Refund should be done manually",
_10
"requestId": "5678"
_10
}

For more information, access the Refund Payment endpoint.

Communicate with the Gateway

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

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


_10
{
_10
"requestId": "LA4E20D3B4E07B7E871F5B5BC9F91",
_10
"transactionId": "D3AA1FC8372E430E8236649DB5EBD08E",
_10
"paymentId": "F5C1A4E20D3B4E07B7E871F5B5BC9F91",
_10
"authorizationId": "{{authorizationId}}",
_10
"tid": "{{tid}}",
_10
"requestData": {
_10
"body": "{{originalRequestBody}}"
_10
}
_10
}

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


_10
{
_10
"requestId": "{{requestId}}",
_10
"transactionId": "{{transactionId}}",
_10
"paymentId": "{{paymentId}}",
_10
"authorizationId": "{{authorizationId}}",
_10
"tid": "{{tid}}",
_10
"requestData": {
_10
"body": "{{originalRequestBody}}"
_10
}
_10
}

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.

Contributors
4
Photo of the contributor
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 4 contributors
Was this helpful?
Yes
No
Suggest edits (Github)
Contributors
4
Photo of the contributor
Photo of the contributor
Photo of the contributor
Photo of the contributor
+ 4 contributors
On this page