Accept Pix payments using our APIs, and build your own payment form to have full control over the look and feel of your checkout page.
Before you begin
These instructions explain how to add Pix to your existing API-only integration. The API-only integration works the same way for all payment methods. If you haven't done this integration yet, refer to our API-only integration guide.
Before starting your Pix integration:
Build your payment form for Pix
Include Pix in the list of available payment methods. If you're using the /paymentMethods endpoint to show which payment methods are available to the shopper, specify in your request:
The response contains:
Collect additional parameters in your payment form
After the shopper selects Pix, collect the following optional details from the shopper:
- Name: The first and last name of the shopper.
- CPF/CNPJ: CPF/CNPJ is a unique identifier similar to a social security number. The shopper can provide their Cadastro de Pessoas Físicas (CPF) number or their Cadastro Nacional da Pessoa Jurídica (CNPJ) number.
Pass the collected data from the front end to your server because you will need to submit both Name and CPF/CNPJ in the /payments request. Show this information to the shopper together with the QR code to help identify the payment.
Make a payment
To make a Pix payment, pass the following data to your server:
- Payment method type: pix.
- Data collected from your shopper in the previous step, if any.
Then, from your server, make a /payments request with the following parameters:
||Set to pix.|
||The final price of the purchase.|
||The shopper's CPF or CNPJ number. If you don't have the shopper's CPF or CNPJ, you can skip
||Free-text field that will be shown to the shopper. Maximum length: 140 characters.|
||The expiration date of the Pix payment. The default value is 24 hours, the maximum value is 5 days, in ISO 8601 format.
For example: 2020-07-18T15:42:40.428+01:00
||Information about purchased items.|
||The name of the purchased item. Maximum 50 characters.|
||The price of the purchased item including tax. Maximum 200 characters.|
You need to send both
socialSecurityNumber because this information will be shown to the shopper to help identify the payment.
The response contains the following data:
action: Contains the QR code
Render the QR code or present QR code data
Use the information in the
action object of the /payments response to render the QR code or present the QR code data to the shopper.
action.qrCodeData: Use this to render the QR Code on your checkout page or present as-is to the shopper to copy it.
The shopper can either scan the QR code, or copy the QR code data to paste to their banking or wallet app.
After the shopper scans the QR code and completes the payment, you will receive the result of the payment asynchronously in a webhook.
Here's an example of a standard webhook you may receive.
For more information, see Webhooks.
You can include the following fields in your payment confirmation:
To add these fields to your notifications:
- Log in to your test Customer Area.
- Select Developers>Webhooks.
- Select the edit icon next to the name of the webhook.
- Under Additional settings>Payment, select Include Pix Payer info.
Test and go live
Pix is an asynchronous payment method. In the test environment, you can simulate a Pix payment by promoting the pending payment to a sale.
- Log in to your test Customer Area.
- Go to Transactions > Offers.
- Select the PSP reference of the pending Pix payment.
- Select the Promote this offer to a sale button.
Pix payments that have been paid (including test offers that you manually promoted to sale) are under Transactions > Payments.
Test the reconciliation process by promoting test payments from offer to sale in your test Customer Area.