---
title: "Pix (classic)"
description: "Add Pix to an existing older Classic API-only integration."
url: "https://docs.adyen.com/online-payments/classic-integrations/classic-api-integration/classic-pix"
source_url: "https://docs.adyen.com/online-payments/classic-integrations/classic-api-integration/classic-pix.md"
canonical: "https://docs.adyen.com/online-payments/classic-integrations/classic-api-integration/classic-pix"
last_modified: "2020-12-22T11:27:00+01:00"
language: "en"
---

# Pix (classic)

Add Pix to an existing older Classic API-only integration.

[View source](/online-payments/classic-integrations/classic-api-integration/classic-pix.md)

This page is for our old Classic API `/authorise` integration. If you are integrating using our Checkout APIs, refer to the [Pix](/payment-methods/pix) documentation instead.

![](/user/pages/docs/02.online-payments/60.classic-integrations/01.classic-api-integration/classic-pix/pix.svg?decoding=auto\&fetchpriority=auto)  **Read more**

Learn about pricing and the shopper journey for [Pix](https://www.bcb.gov.br/estabilidadefinanceira/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](#transaction-conditions) 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/regions | Currencies | [Recurring](/online-payments/tokenization)   | [Refunds](/online-payments/refund)                                                                            | [Partial refunds](/online-payments/refund#refund-a-payment) | [Separate captures](/online-payments/capture) | [Chargebacks](/risk-management/chargeback-guidelines) |
| -------------- | ----------------- | ----------------- | ---------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------- |
| Online banking | Additional action | **BR**            | **BRL**    | ![-x-](/user/data/smileys/emoji/x.png "-x-") | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") Note[1](#refunds) | ![-x-](/user/data/smileys/emoji/x.png "-x-")                | ![-x-](/user/data/smileys/emoji/x.png "-x-")  | ![-x-](/user/data/smileys/emoji/x.png "-x-")          |

[]()1 Refunds are only possible within 90 days after the payment.

## Requirements

These instructions explain how to add Pix to an old Classic API-only integration. If you haven't done the old Classic API integration yet, build one of our most recent [online payments integration](/online-payments).

Before starting your Pix integration, [add Pix in your test Customer Area](/payment-methods/add-payment-methods).

## 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](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only#downloading-logos).

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

   * Name: First and last name of the shopper.
   * CPF/CNPJ: The CPF/CNPJ is a unique identifier similar to the social security number. The shopper can provide their [Cadastro de Pessoas Físicas (CPF)](https://en.wikipedia.org/wiki/Cadastro_de_Pessoas_Físicas) number or their [Cadastro Nacional da Pessoa Jurídica (CNPJ)](https://en.wikipedia.org/wiki/CNPJ) number.

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](https://docs.adyen.com/api-explorer/#/Payment/authorise) request with the following parameters:

| Parameter                           | Required                                                                                    | Description                                                                                                                                                                                                                                                                                  |
| ----------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `selectedBrand`                     | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to **pix**.                                                                                                                                                                                                                                                                              |
| `amount`                            | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The final price of the purchase.                                                                                                                                                                                                                                                             |
| `shopperName`                       |                                                                                             | The shopper's `firstName` and `lastName`. Keep the length under 200 characters, otherwise it will be truncated.                                                                                                                                                                              |
| `socialSecurityNumber`              |                                                                                             | The shopper's CPF or CNPJ number.                                                                                                                                                                                                                                                            |
| `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 because this will be appended to the default message. |
| `additionalData.pix.expirationDate` |                                                                                             | The expiration date and time of the Pix payment. The default value is 24 hours. The maximum value is 5 days. Format: [ISO 8601](http://www.w3.org/TR/NOTE-datetime); YYYY-MM-DDThh:mm:ssTZD.                                                                                                 |
| `additionalData.pix.numberOfInfos`  |                                                                                             | The number of purchased items.                                                                                                                                                                                                                                                               |
| `additionalData.pix.info1.name`     |                                                                                             | The name of the purchased item. Maximum 50 characters.                                                                                                                                                                                                                                       |
| `additionalData.pix.info1.value`    |                                                                                             | 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**

```json
{
    "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**

```json
{
    "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](https://docs.adyen.com/api-explorer/#/Payment/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 [webhook event](/development-resources/webhooks).

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

#### JSON

```json
{
    "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",
                ...
            }
        }
    ]
}
```

#### Soap

```xml
<?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, refer to [Webhooks](/development-resources/webhooks/webhook-types).

## 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](/online-payments/cancel) and [make a refund](#refunds).

## Refunds

You can refund a payment within 90 days after the payment in the [Customer Area](/account/manage-payments#refund-a-payment) or via an [API](/online-payments/refund).

## 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](https://ca-test.adyen.com/).
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](/payment-methods/add-payment-methods) in your [live Customer Area](https://ca-live.adyen.com/).

## See also

* [Classic API integration guide](/online-payments/classic-integrations/classic-api-integration)
* [Webhooks](/development-resources/webhooks)
* [API Explorer](https://docs.adyen.com/api-explorer/#/Payment/latest/overview)
