Payment-method icon

Pix Drop-in integration

Add Pix to an existing Drop-in integration.

If you are using Android Drop-in v5.0.0 or later:

This payment method requires no additional configuration.

Follow the Drop-in integration guide.

When a shopper is ready to pay with Pix on your Android app:

  1. The shopper chooses to pay with Pix on your Android app.
  2. Your Android app shows a QR code or QR code data for the shopper to copy.
  3. The shopper opens their banking or wallet app participating in Pix.
  4. The shopper selects Pix, scans the QR code or pastes QR code data, and then confirms the payment.

Select server-side flow

To enable Pix on your Android app, choose which server-side flow your integration uses.

Requirements

Requirement Description
Integration type Make sure that you have built a Sessions flow Android Drop-in integration.
Setup steps Before you begin, add Pix in your test Customer Area.

Create a session

No additional fields are required for Pix when you make the /sessions request. You can check if there are optional additional fields for Pix.

Show the payment result

1. Inform the shopper

From the onFinished function, you can get the resultCode to inform the shopper about the current payment status.

You can also get the result of the payment session on your backend server.

  1. Get the id from the /sessions response.
  2. Get sessionResult from the onFinished function.

  3. Make a GET /sessions/{id}?sessionResult={sessionResult} request including the id and sessionResult. For example:

    The response includes the result of the payment session (status). For example:

    Possible statuses:

    status Description
    completed The shopper completed the payment. This means that the payment was authorized.
    paymentPending The shopper is in the process of making the payment. This applies to payment methods with an asynchronous flow.
    canceled The shopper canceled the payment.
    expired The session expired (default: 1 hour after session creation). Shoppers can no longer complete the payment with this sessionId.

The status included in the response doesn't get updated. Do not make the request again to check for payment status updates. Instead, check webhooks or the Transactions list in your Customer Area.

2. Update your order management system

You get the outcome of each payment asynchronously, in an AUTHORISATION webhook. Use the merchantReference from the webhook to match it to your order reference.
For a successful payment, the event contains success: true.

For an unsuccessful payment, you get success: false, and the reason field has details about why the payment was unsuccessful.

Requirements

Requirement Description
Integration type Make sure that you have built an Advanced flow Android Drop-in integration.
Setup steps Before you begin, add Pix in your test Customer Area.

Show Pix in your payment form

Include Pix in the list of available payment methods.

  1. Specify in your /paymentMethods request:
  1. The response contains paymentMethod.type: pix.

Make a payment

When the shopper proceeds to pay, Drop-in returns the paymentComponentData.paymentMethod.

  1. Pass paymentComponentData.paymentMethod to your server.

  2. From your server, make a /payments request, specifying:

Parameter Required Description
paymentMethod -white_check_mark- The state.data.paymentMethod from the onSubmit event from your front end.
amount -white_check_mark- The amount information for the transaction (in minor units).
shopperName -white_check_mark- Shopper's first name and last name.
socialSecurityNumber -white_check_mark- The shopper's CPF or CNPJ number. This will be shown to the shopper on the Pix payment form.
shopperStatement -white_check_mark- The text to be shown on the shopper's bank statement. 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 because this will be appended to the default message.
sessionValidity -white_check_mark- 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.id -white_check_mark- The name of the purchased item. Maximum 50 characters.
lineItems.amountIncludingTax -white_check_mark- The price of the purchased item including tax. Maximum 200 characters.

The /payments response contains:

  • action: Object containing information about the payment.
  1. The action object of the response automatically indicates to the InstantPaymentComponent to call the QR code action.

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:

  1. Log in to your test Customer Area.
  2. Select Developers>Webhooks.
  3. Select the edit icon next to the name of the webhook.
  4. 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.

  1. Log in to your test Customer Area.
  2. Go to Transactions > Offers.
  3. Select the PSP reference of the pending Pix payment.
  4. 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.

See also