Payment-method icon

Pix Component

Add Pix to an existing Components integration.

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.

Before you begin

v5.0.0 or later

Choose which server-side flow your integration uses.

Before starting your Pix integration:

  1. Make sure that you have done the Components integration for Android.

    • Ensure that InstantPaymentComponent is set up as the component to enable Pix integration to Android. The important statements for InstantPaymentComponent use instant:

  2. Add Pix in your test Customer Area.

v4.x.x

Before starting your Pix integration:

  1. Make sure that you have done the Components integration for Android.
  2. 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:

The response contains paymentMethod.type: pix.

Make a payment

  1. When the shopper selects the button to pay, 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.
    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.

  2. The action object of the response automatically indicates to the InstantPaymentComponent to call the QR code action.

Check the payment result

After the shopper completes the payment, make a POST /payments/details request from your server, providing:

  • details: The actionComponentData.details object from the QRCodeComponent

You receive a response containing:

  • resultCode: Use this to show the payment result to your shopper.

  • pspReference: Our unique identifier for the transaction.

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. Don't 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.

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