Pix Drop-in integration

Add Pix to an existing Drop-in integration.

On this page, you can find additional configuration for adding Pix to your Drop-in integration.

Before you begin

This page assumes you've already:

Collect additional parameters in your payment form

Collect the following details from the shopper:

Name: The first and last name of the shopper.
CPF/CNPJ: CPF/CNPJ is a unique identifier similar to a social security number. The shopper can provide their Cadastro de Pessoas Físicas (CPF) number or their Cadastro Nacional da Pessoa Jurídica (CNPJ) number.

Pass the collected data to your server because you will need to submit both Name and CPF/CNPJ in the /payments request. This information will be shown to the shopper to help identify the payment.

API reference

Select which endpoint you're integrating:

This is the default with Components v5.0.0 or later.

Parameter	Required	Description
amount		The final price of the purchase.
shopperName		Shopper's first name and last name.
socialSecurityNumber		The shopper's CPF or CNPJ number. This will be shown to the shopper on the Pix payment form.
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.
sessionValidity		The expiration date of the Pix payment. The default value is 24 hours, the maximum value is 5 days, in ISO 8601 format. For example: 2020-07-18T15:42:40.428+01:00
lineItems.id		The name of the purchased item. Maximum 50 characters.
lineItems.amountIncludingTax		The price of the purchased item including tax. Maximum 200 characters.

curl https://checkout-test.adyen.com/v68/sessions \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "amount": {
        "currency": "BRL",
        "value": 100000
    },
    "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
    "shopperStatement": "Your message to the shopper.",
    "reference": "YOUR_ORDER_NUMBER",
    "shopperName": {
        "firstName": "Jose",
        "infix": "da",
        "lastName": "Silva"
    },
    "socialSecurityNumber": "01234567890",
    "lineItems": [{
            "id": "Item 1",
            "amountIncludingTax": "40000"
        },
        {
            "id": "Item 2",
            "amountIncludingTax": "60000"
        }
    ]
}'

https://docs.adyen.com/payment-methods/pix/web-component#pix-web-sessions

If you implemented an advanced use case, or integrated Components before v5.0.0.

Parameter	Required	Description
paymentMethod		The `state.data.paymentMethod` from the `onSubmit` event from your front end.
amount		The final price of the purchase.
shopperName		Shopper's first name and last name.
socialSecurityNumber		The shopper's CPF or CNPJ number. This will be shown to the shopper on the Pix payment form.
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.
sessionValidity		The expiration date of the Pix payment. The default value is 24 hours, the maximum value is 5 days, in ISO 8601 format. For example: 2020-07-18T15:42:40.428+01:00
lineItems.id		The name of the purchased item. Maximum 50 characters.
lineItems.amountIncludingTax		The price of the purchased item including tax. Maximum 200 characters.

curl https://checkout-test.adyen.com/v68/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "amount": {
        "currency": "BRL",
        "value": 100000
    },
    "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
    "shopperStatement": "Your message to the shopper.",
    "reference": "YOUR_ORDER_NUMBER",
    "paymentMethod": {
        "type": "pix"
    },
    "shopperName": {
        "firstName": "Jose",
        "infix": "da",
        "lastName": "Silva"
    },
    "socialSecurityNumber": "01234567890",
    "lineItems": [{
            "id": "Item 1",
            "amountIncludingTax": "40000"
        },
        {
            "id": "Item 2",
            "amountIncludingTax": "60000"
        }
    ]
}'

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR_X-API-KEY"

response = adyen.checkout.payments({
  :merchantAccount => "YOUR_MERCHANT_ACCOUNT",
  :amount => {
      :currency => "BRL",
      :value => 100000
  },
  :paymentMethod => {
      :type => "pix"
  },
  :sessionValidity => "2021-12-21T13:00:00-03:00",
  :shopperStatement => "Your message to the shopper.",
  :shopperName => {
      :firstName => "Jose",
      :infix => "da",
      :lastName => "Silva"
  },
  :socialSecurityNumber => "01234567890",
  :lineItems => [
      {
          :id => "Item 1",
          :amountIncludingTax => "40000"
      },
      {
          :id => "Item 2",
          :amountIncludingTax => "60000"
      }
  ]
  :reference => "YOUR_ORDER_NUMBER"
})

// Set YOUR_X-API-KEY with the API key from the Customer Area.
// Change to Environment.LIVE and add the Live URL prefix when you're ready to accept live payments.
Client client = new Client("YOUR_X-API-KEY", Environment.TEST);
Checkout checkout = new Checkout(client);

PaymentsRequest paymentsRequest = new PaymentsRequest();

String merchantAccount = "YOUR_MERCHANT_ACCOUNT";
paymentsRequest.setMerchantAccount(merchantAccount);

Amount amount = new Amount();
amount.setCurrency("BRL");
amount.setValue(100000L);
paymentsRequest.setAmount(amount);

DefaultPaymentMethodDetails paymentMethodDetails = new DefaultPaymentMethodDetails();
paymentMethodDetails.setType("pix");
paymentsRequest.setPaymentMethod(paymentMethodDetails);

String sessionValidity = "2021-12-21T13:00:00-03:00";
String shopperStatement = "Your message to the shopper.";

ShopperName shopperName = new ShopperName();
shopperName.setFirstName("Jose");
shopperName.setInfix("da");
shopperName.setLastName("Silva");
paymentsRequest.setShopperName(shopperName);

String socialSecurityNumber = "01234567890";

List<LineItem> lineItems = new ArrayList<>();
lineItems.add(
        new LineItem()
                .id("Item 1")
                .amountIncludingTax(40000L)
);
lineItems.add(
        new LineItem()
                .id("Item 2")
                .amountIncludingTax(60000L)
);

paymentsRequest.setReference("YOUR_ORDER_NUMBER");

PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = [
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT",
  "amount" => [
    "currency" => "BRL",
    "value" => 100000
  ],
  "paymentMethod" => [
    "type" => "pix"
  ],
  "sessionValidity" => "2021-12-21T13:00:00-03:00",
  "shopperStatement" => "Your message to the shopper.",
  "shopperName" => [
      "firstName" => "Jose",
      "infix" => "da",
      "lastName" => "Silva"
  ],
  "socialSecurityNumber" => "01234567890",
  "lineItems": [
    [
        "id" => "Item 1",
        "amountIncludingTax" => "40000"
    ],
    [
        "id" => "Item 2",
        "amountIncludingTax" => "60000"
    ]
  ],
  "reference" => "YOUR_ORDER_NUMBER"
];
$result = $service->payments($params);

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

result = adyen.checkout.payments({
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod": {
    "type": "pix"
  },
  "amount": {
    "currency": "BRL",
    "value": 100000
  },
  "sessionValidity":"2021-12-21T13:00:00-03:00",
  "shopperStatement": "Your message to the shopper.",
  "shopperName": {
    "firstName": "Jose",
    "infix": "da",
    "lastName": "Silva"
  },
  "socialSecurityNumber": "01234567890",
  "lineItems": [
    {
      "id": "Item 1",
      "amountIncludingTax": "40000"
    },
    {
      "id": "Item 2",
      "amountIncludingTax": "60000"
    }
  ]
})

// Set your X-API-KEY with the API key from the Customer Area.
var client = new Client ("YOUR_X-API-KEY", Environment.Test);
var checkout = new Checkout(client);

var paymentRequest = new Adyen.Model.Checkout.PaymentRequest
{
   MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
   Reference = "YOUR_ORDER_NUMBER",
   PaymentMethod = new DefaultPaymentMethodDetails { Type = "pix" },
   Amount = new Model.Checkout.Amount(Currency: "BRL", Value: 100000),
   SessionValidity = "2021-12-21T13:00:00-03:00",
   ShopperStatement = "Your message to the shopper.",
   ShopperName = new Model.Checkout.Name
   {
       FirstName = "Jose",
       Infix = "da"
       LastName = "Silva"
   },
   SocialSecurityNumber = "01234567890",
   LineItems = new List<LineItem>
{
   new LineItem(Id:"Item 1", AmountIncludingTax:40000),
   new LineItem(Id:"Item 2", AmountIncludingTax:60000)
}
return paymentRequest;
}

// Set your X-API-KEY with the API key from the Customer Area.
const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[API_KEY]';
config.merchantAccount = '[MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
  merchantAccount: "YOUR_MERCHANT_ACCOUNT",
  reference: "YOUR_ORDER_NUMBER",
  paymentMethod: {
     type: "pix"
  },
  amount: {
     currency: "BRL",
     value: "100000"
  },
  sessionValidity: "2021-12-21T13:00:00-03:00",
  shopperStatement: "Your message to the shopper.",
  shopperName: {
     firstName": "Jose",
     infix": "da",
     lastName": "Silva"
  },
  socialSecurityNumber: "01234567890",
  lineItems: [
     {
        id: "item1",
        amountIncludingTax: "5000"
     },
     {
        id: "item2",
        amountIncludingTax: "10000"
     }
  ]
}).then(res => res);

https://docs.adyen.com/payment-methods/pix/web-component#pix-web-payments

Drop-in configuration

There is no Pix specific configuration for Drop-in.

Refunds

You can refund a payment within 90 days after the payment in the Customer Area or using 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.

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

Are you looking for test card numbers?

Would you like to contact support?