You can add Pix to your existing integration. The following instructions show only what you must add to your integration specifically for Pix.
If an instruction on this page corresponds with a step in the main integration guide, it includes a link to the corresponding step of the main integration guide.
Requirements
| Requirement | Description | |
|---|---|---|
| Integration type | Make sure that you have an existing API-only integration. | |
| Action handling | Make sure that your existing integration is set up to handle the additional action. action.type: qrCode. |
|
| Setup steps | Before you begin, add Pix in your Customer Area. |
How it works
- The shopper selects Pix as the payment method.
- The shopper enters their details in the payment form that you build.
- When you make the payment request, you include additional information about the items that the shopper intends to purchase.
- Your existing integration setup enables you to present a QR code to the shopper to complete the payment.
- You capture the payment.
Build your payment form
Include fields to collect the following information from your shopper in the payment form.
| Field | Description |
|---|---|
| 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 CPF (Cadastro de Pessoas Físicas) number or their CNPJ (Cadastro Nacional da Pessoa Jurídica) number. |
Pass the collected data from the front end to your server because you 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.
You can download the logo for Pix to use in your form.
Get Pix as an available payment method
When you make the /paymentMethods request to get available payment methods, specify the following so that Pix is included in the response.
| Parameter | Values |
|---|---|
| countryCode | BR |
| amount.currency | BRL |
Add additional parameters to your /payments request
When you make a payment, add the following parameters:
| Parameter | Required | Description |
|---|---|---|
| paymentMethod |  |
The state.data.paymentMethod from the onSubmit event from your front end. |
| amount | |
The final price of the purchase. |
| shopperName | Shopper's first name and last name. | |
| socialSecurityNumber | The shopper's CPF or CNPJ number. This will be shown to the shopper on the Pix payment form. | |
| shopperStatement | Free-text field that will be shown to the shopper. By default this contains the message: $merchantName - Este pagamento PIX para $merchantName é processado por Adyen. If you provide any value, keep the length under 60 characters. | |
| sessionValidity | The expiration date of the Pix payment. Default: 1 hour (Checkout API v71 or earlier) or 24 hours (Checkout API v72 or later). Maximum: 5 days, in ISO 8601 format. Example: 2020-07-18T15:42:40.428+01:00 | |
| lineItems.id | The name of the purchased item. Maximum 50 characters. | |
| lineItems.amountIncludingTax | The price of the purchased item including tax. Maximum 200 characters. |
It is advisable to send both shopperName and socialSecurityNumber, because this information will be shown to the shopper to help identify the payment.
The response includes the action.type: qrCode.
Example webhook:
For more information, see Webhooks.
You can include the following fields in your payment confirmation:
pix.payer.bankNamepix.payer.isbppix.payer.namepix.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 the Refund 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.