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.

Select server-side flow

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

Requirements

The requirements are different for v5.0.0 or later and v4.x.x.

v5.0.0 or later

Requirement Description
Integration type Make sure that you have built a Sessions flow Android Components integration.
Setup steps Before you begin:

Import the instant module

Import the instant module and ensure that InstantPaymentComponent is set up as the component.

Import Instant Payment Component module
Expand view
Copy link to code block
Copy code
Copy code
implementation "com.adyen.checkout:instant:YOUR_VERSION"

v4.x.x

Requirement Description
Integration type Make sure that you have built a Sessions flow Android Components 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:

    Request for result of payment session
    Expand view
    Copy link to code block
    Copy code
    Copy code
    curl -X GET https://checkout-test.adyen.com/v70/sessions/CS12345678?sessionResult=SOME_DATA

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

    Response with result of the payment session
    Expand view
    Copy link to code block
    Copy code
    Copy code
    {
    "id": "CS12345678",
    "status": "completed"
    }

    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.

Example webhook for a successful payment
Expand view
Copy link to code block
Copy code
Copy code
{
"live": "false",
"notificationItems":[
{
"NotificationRequestItem":{
"eventCode":"AUTHORISATION",
"merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
"reason":"033899:1111:03/2030",
"amount":{
"currency":"EUR",
"value":2500
},
"operations":["CANCEL","CAPTURE","REFUND"],
"success":"true",
"paymentMethod":"mc",
"additionalData":{
"expiryDate":"03/2030",
"authCode":"033899",
"cardBin":"411111",
"cardSummary":"1111",
"checkoutSessionId":"CSF46729982237A879"
},
"merchantReference":"YOUR_REFERENCE",
"pspReference":"NC6HT9CRT65ZGN82",
"eventDate":"2021-09-13T14:10:22+02:00"
}
}
]
}

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

Example webhook for an unsuccessful payment
Expand view
Copy link to code block
Copy code
Copy code
{
"live": "false",
"notificationItems":[
{
"NotificationRequestItem":{
"eventCode":"AUTHORISATION",
"merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
"reason":"validation 101 Invalid card number",
"amount":{
"currency":"EUR",
"value":2500
},
"success":"false",
"paymentMethod":"unknowncard",
"additionalData":{
"expiryDate":"03/2030",
"cardBin":"411111",
"cardSummary":"1112",
"checkoutSessionId":"861631540104159H"
},
"merchantReference":"YOUR_REFERENCE",
"pspReference":"KHQC5N7G84BLNK43",
"eventDate":"2021-09-13T14:14:05+02:00"
}
}
]
}

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