Search

Are you looking for test card numbers?

Would you like to contact support?

Classic-integration icon

Pix (classic)

Add Pix to an existing classic Direct API-only integration.

This page is for our classic Direct API /authorise integration. If you are integrating using our Checkout APIs, refer to the Pix documentation instead.

  Read more

Learn about pricing and the shopper journey for Pix.

Pix is a payment method for instant direct bank transfers in Brazil, which is built and owned by the Central Bank (Banco Central) and operated by Brazilian banks, digital accounts, and wallets.

Shoppers can pay with Pix when shopping online. The money is sent directly from the shopper account to Adyen's account, and then transferred once a day to the merchant's bank account.

With Pix, the payment flow is as follows:

  1. The shopper chooses to pay with Pix on your website or app.
  2. Your website or 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 approving the payment, Pix checks if the transaction follows the regulations of the Central Bank. If approved, the amount is transferred in real-time from the shopper's account to Adyen.

Note that the merchant needs to have a local entity in Brazil to accept Pix payments.

Payment type Payment flow Countries Currencies Recurring Refunds Partial refunds Separate
captures
Chargebacks
Online banking Additional action BR BRL -x- -white_check_mark-
Note1
-x- -x- -x-

1 Refunds are only possible within 90 days after the payment.

Before you begin

These instructions explain how to add Pix to your classic Direct API-only integration. If you haven't done the classic Direct API integration yet, refer to our Direct API integration guide.

Before starting your Pix integration, add Pix in your test Customer Area.

Build your payment form

To show Pix in your payment form, you need to:

  1. Show Pix as an available payment method.

    We provide a Pix logo which you can use on your payment form. For more information, refer to Downloading logos.

  2. After the shopper selects Pix, collect the following details from the shopper:

  3. Pass the following data to your server:

    • Payment method type: pix.
    • Data collected from your shopper in the previous step, if any.

Make a payment

From your server, make an /authorise request with the following parameters:

Parameter Required Description
selectedBrand -white_check_mark- Set to pix.
amount -white_check_mark- The final price of the purchase.
shopperName -x- The shopper's firstName and lastName. Keep the length under 200 characters, otherwise it will be truncated.
socialSecurityNumber -white_check_mark- The shopper's CPF or CNPJ number.
shopperStatement -white_check_mark- 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 because this will be appended to the default message.
additionalData.pix.expirationDate -x- The expiration date and time of the Pix payment. The default value is 24 hours. The maximum value is 5 days. Format: ISO 8601; YYYY-MM-DDThh:mm:ssTZD.
additionalData.pix.numberOfInfos -x- The number of purchased items.
additionalData.pix.info1.name -x- The name of the purchased item. Maximum 50 characters.
additionalData.pix.info1.value -x- The price of the purchased item. 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.

/authorise request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "reference": "YOUR_ORDER_NUMBER",
    "amount": {
        "value": 1400,
        "currency": "BRL"
    },
    "selectedBrand": "pix",
    "shopperStatement": "Merchant message to the shopper.",
    "shopperName": {
        "firstName": "Jose",
        "lastName": "Silva"
    },
    "socialSecurityNumber": "01234567890",
    "additionalData": {
        "pix.expirationDate": "2021-12-21T00:00:00-03:00",
        "pix.numberOfInfos": "2",
        "pix.info1.name": "Item 1",
        "pix.info1.value": "R$ 100,00",
        "pix.info2.name": "Item 2",
        "pix.info2.value": "R$ 10,00"
    }
}

The response contains the following:

  • pspReference: Our unique reference for the payment.
  • resultCode: Received
  • additionalData: Contains the QR code and QR code data.
/authorise response
{
    "additionalData": {
        "pix.expirationDate": "2020-11-19T00:00:00-03:00",
        "pix.qrcodedata": "00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com/v1/p/v2/357839780dac4101be92d525ad9f2c29520400005303986540510.015802BR5914Adyen Merchant6015Cidade da Adyen61082000000062070503***6304B6FE",
        "pix.qrcode": "http://localhost:8080/hpp/generateQRCodeImage.shtml?url=00020101021226930014br.gov.bcb.pix2571api-h.developer.btgpactual.com%2Fv1%2Fp%2Fv2%2F357839780dac4101be92d525ad9f2c29520400005303986540510.015802BR5914Adyen+Merchant6015Cidade+da+Adyen61082000000062070503***6304B6FE"
    },
    "pspReference": "991607345940194B",
    "resultCode": "Received"
}

Transaction conditions

Before approving the payment, Pix performs the following checks:

  • The shopper has sufficient funds in their transactional account.
  • The transaction time did not exceed the maximum time defined by the Central Bank.
  • There is no suspicion of fraud or breach of regulations to prevent money laundering and terrorist financing.
  • There is no authentication problems in the shopper's financial or payment institution transactional account.
  • The shopper has not been excluded from their institution participating in Pix.

Adyen or the acquirer bank can reject the transaction in the following cases:

  • Suspicion of fraud or breach of regulations to prevent money laundering and terrorist financing.
  • Technical issue in the Pix ecosystem.

Present the QR code or QR code data

Use the information in the additionalData object of the /authorise response to render the QR code or present the QR code data to the shopper.

  • pix.expirationDate: The date and time when the payment expires.
  • pix.qrcodedata: QR code contents. Use this to render the QR code or present as-is so they can copy it.
  • pix.qrcode: A link to render or download the QR Code.

The shopper can either scan the QR code, or copy it 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 notification webhook.

Here's an example of a standard notification you might receive.

{
    "live":"false",
    "notificationItems": [
        {
            "NotificationRequestItem": {
                "additionalData": {
                    ...
                    "pix.originalAmountValue":"1001",
                    "pix.originalAmountCurrency":"BRL"
                },
                "amount": {
                    "currency":"BRL",
                    "value":1001
                },
                "eventCode":"AUTHORISATION",
                "eventDate":"2021-12-21T20:49:23-03:00",
                "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
                "merchantReference":"YOUR_REFERENCE",
                "paymentMethod":"pix",
                "pspReference":"991607125682053H",
                "success":"true",
                ...
            }
        }
    ]
}
<?xml version="1.0"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"  xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <ns1:sendNotification xmlns:ns1="http://notification.services.adyen.com">
      <ns1:Notification>
        <live xmlns="http://notification.services.adyen.com">false</live>
        <notificationItems xmlns="http://notification.services.adyen.com">
          <NotificationRequestItem>
            <additionalData>
              <pix.originalAmountCurrency>BRL</pix.originalAmountCurrency>
              <pix.originalAmountValue>1001</pix.originalAmountValue>
            </additionalData>
            <amount>
              <currency xmlns="http://common.services.adyen.com">BRL</currency>
              <value xmlns="http://common.services.adyen.com">1001</value>
            </amount>
            <eventCode>AUTHORISATION</eventCode>
            <eventDate>2021-12-21T20:49:23-03:00</eventDate>
            <merchantAccountCode>YOUR_MERCHANT_ACCOUNT</merchantAccountCode>
            <merchantReference>YOUR_TRANSACTION_REFERENCE</merchantReference>
            <paymentMethod>pix</paymentMethod>
            <pspReference>991607125682053H</pspReference>
            <success>true</success>
          </NotificationRequestItem>
        </notificationItems>
      </ns1:Notification>
    </ns1:sendNotification>
  </soap:Body>
</soap:Envelope>

For more information about notifications, refer to Understanding notifications.

Match the original and the paid amount

With Pix, shoppers can manually modify the amount they pay in their banking or wallet app after scanning the QR code or pasting the QR code data. Make sure to implement some business logic that matches additionalData.pix.originalAmountValue and amount.value. If the actual paid amount doesn't match the original amount, we recommend that you cancel the payment and make a refund.

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. To be able to test this, make sure you have the following user roles in your test Customer Area:

  • Merchant view offers: This allows you to see Pix offers that are in the "Pending" state.
  • Promote offers to sale (test): This allows you to promote a Pix offer from "Pending" to "Authorised". This way you can test what happens when we process the payment. This permission is only available in TEST.

Check the status of Pix test payments in your Customer Area:

  • Pix payments that are pending or that have expired, are under TransactionsOffers.
  • 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