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.
Requirements
| Requirement | Description |
|---|---|
| Integration type | Make sure that you have an existing API-only integration. |
| Setup steps | Before you begin, add Pix in your test Customer Area. |
Build your payment form for Pix
Include Pix in the list of available payment methods. If you are using the /paymentMethods endpoint to show which payment methods are available to the shopper, specify in your request:
- countryCode: BR.
- amount.currency: BRL.
The response contains:
paymentMethod.type: pix
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:
| Parameter | Required | Description |
|---|---|---|
paymentMethod.type |
 |
Set to pix. |
amount |
|
The final price of the purchase. |
shopperName |
The shopper's firstName and lastName. If you do not have the shopper's name, you can skip shopperName. Keep the length of each field under 200 characters, otherwise it will be truncated. This will be shown to the shopper in the payments form. |
|
socialSecurityNumber |
The shopper's CPF or CNPJ number. If you do not have the shopper's CPF or CNPJ, you can skip socialSecurityNumber. This will be shown to the shopper in the payments form. |
|
shopperStatement |
Free-text field that will be shown to the shopper. Maximum length: 140 characters. | |
sessionValidity |
The expiration date of the Pix payment. The default value is 1 hour (Checkout API v71 or earlier) or 24 hours (Checkout API v72 or later), the maximum value is 5 days, in ISO 8601 format. For example: 2020-07-18T15:42:40.428+01:00 | |
lineItems |
Information about purchased items. | |
lineItems.id |
The name of the purchased item. Maximum 50 characters. | |
lineItems.amountIncludingTax |
The price of the purchased item including tax. Maximum 200 characters. |
You need to send both shopperName and socialSecurityNumber because this information will be shown to the shopper to help identify the payment.
The response contains the following data:
resultCode: Pendingaction: Contains the QR codeurlandqrCodeData.
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.
Payment result
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:
pix.payer.bankName
pix.payer.isbp
pix.payer.name
pix.payer.taxId
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.
Refunds
You can refund a payment within 90 days after the payment in the Customer Area or via an API.
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.
Before you can accept live Pix payments, you need to submit a request for Pix in your live Customer Area.