---
title: "PayPal Drop-in integration"
description: "Add PayPal to an existing Drop-in integration."
url: "https://docs.adyen.com/payment-methods/paypal/web-drop-in"
source_url: "https://docs.adyen.com/payment-methods/paypal/web-drop-in.md"
canonical: "https://docs.adyen.com/payment-methods/paypal/web-drop-in"
last_modified: "2026-05-07T17:20:52+02:00"
language: "en"
---

# PayPal Drop-in integration

Add PayPal to an existing Drop-in integration.

This page explains how to add PayPal to your existing Web Drop-in integration.

The PayPal Smart Payment Buttons are available from Drop-in

v 3.7.0

and later.

## Requirements

| Requirement          | Description                                                                                                                                                             |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type** | Make sure that you have built your [Drop-in integration](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Drop-in%2F%3Ftarget%3D_blank). |
| **Setup steps**      | Before you begin, complete the [PayPal setup steps](/payment-methods/paypal/setup-paypal-direct-merchants).                                                             |

## API reference

Select which endpoint you are using:

### Tab: `/sessions`

This is the default with [Drop-in v5.0.0](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Drop-in) or later.

| Parameter name                                                                                   | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [lineItems](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems) |          | Price and product information about the purchased items. For each item, you only need to send `quantity`, `description`, `itemCategory`, `sku`, `amountExcludingTax`, and `taxAmount`. The allowed values for `itemCategory` are:- **DIGITAL\_GOODS**: goods that are stored, delivered, and used in electronic format.
- **PHYSICAL\_GOODS**: tangible goods that can be shipped with proof of delivery.
- **DONATION**: a contribution or gift for which no goods or services are exchanged, usually to a not-for-profit organization.  |
| `additionalData.paypalPairingId`                                                                 |          | **Only for customer-initiated transactions where you use the Fraudnet SDK and pass the same pairing ID to Fraudnet and Adyen.** A unique ID determined by you, to link a transaction to a Fraudnet PayPal risk session.PayPal refers to this ID as *pairing ID*, *CMID*, or *tracking ID*.                                                                                                                                                                                                                                                |
| `additionalData.paypalRisk`                                                                      |          | **Only for marketplaces and for merchants in specific verticals.** The [PayPal risk fields](#paypal-risk-fields) that PayPal told you to send. You must include these fields in an `additional_data` array and send this in [stringified format](#risk-fields-formatting).Contact your PayPal account manager to learn which `paypalRisk` fields apply in your case and what happens if you do not populate a specific field. For a list of example fields, refer to the [common risk fields for marketplaces](#risk-field-marketplaces). |

The following example shows a payment request with the `lineItems` fields you can use for PayPal, and a few `paypalRisk` keys and values in `additionalData`.

#### curl

```bash
curl https://checkout-test.adyen.com/v71/sessions \
-H 'x-API-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
  "amount": {
    "currency": "USD",
    "value": 1000
  },
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "reference": "YOUR_ORDER_NUMBER",
  "returnUrl": "https://your-company.example.com/checkout?shopperOrder=12xy..",
  "lineItems": [
    {
      "quantity": 1,
      "description": "Red Shoes",
      "itemCategory": "PHYSICAL_GOODS",
      "sku": "ABC123",
      "amountExcludingTax": 590,
      "taxAmount": 10
    },
    {
      "quantity": 3,
      "description": "Polkadot Socks",
      "itemCategory": "PHYSICAL_GOODS",
      "sku": "DEF234",
      "amountExcludingTax": 90,
      "taxAmount": 10
    }
  ],
  "additionalData": {
    "paypalRisk": "{\"additional_data\":[{\"key\":\"sender_first_name\",\"value\":\"Simon\"},{\"key\":\"sender_last_name\",\"value\":\"Hopper\"},{\"key\":\"receiver_account_id\",\"value\":\"AH00000000000000000000001\"}]}"
  }
}'
```

#### Java

```java
// Adyen Java API Library v27.0.0
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.model.checkout.*;
import java.time.OffsetDateTime;
import java.util.*;
import com.adyen.model.RequestOptions;
import com.adyen.service.checkout.*;

// For the live environment, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
LineItem lineItem1 = new LineItem()
  .quantity(1L)
  .itemCategory("PHYSICAL_GOODS")
  .amountExcludingTax(590L)
  .description("Red Shoes")
  .sku("ABC123")
  .taxAmount(10L);

LineItem lineItem2 = new LineItem()
  .quantity(3L)
  .itemCategory("PHYSICAL_GOODS")
  .amountExcludingTax(90L)
  .description("Polkadot Socks")
  .sku("DEF234")
  .taxAmount(10L);

Amount amount = new Amount()
  .currency("USD")
  .value(1000L);

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest()
  .reference("YOUR_ORDER_NUMBER")
  .lineItems(Arrays.asList(lineItem1, lineItem2))
  .amount(amount)
  .merchantAccount("ADYEN_MERCHANT_ACCOUNT")
  .additionalData(new HashMap<String, String>(Map.of(
    "paypalRisk", "STRINGIFIED_ADDITIONAL_DATA_ARRAY"
  )))
  .returnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..")
  .shopperReference("YOUR_UNIQUE_SHOPPER_ID");

// Send the request
PaymentsApi service = new PaymentsApi(client);
CreateCheckoutSessionResponse response = service.sessions(createCheckoutSessionRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\LineItem;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CreateCheckoutSessionRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$lineItem1 = new LineItem();
$lineItem1
  ->setQuantity(1)
  ->setItemCategory("PHYSICAL_GOODS")
  ->setAmountExcludingTax(590)
  ->setDescription("Red Shoes")
  ->setSku("ABC123")
  ->setTaxAmount(10);

$lineItem2 = new LineItem();
$lineItem2
  ->setQuantity(3)
  ->setItemCategory("PHYSICAL_GOODS")
  ->setAmountExcludingTax(90)
  ->setDescription("Polkadot Socks")
  ->setSku("DEF234")
  ->setTaxAmount(10);

$amount = new Amount();
$amount
  ->setCurrency("USD")
  ->setValue(1000);

$createCheckoutSessionRequest = new CreateCheckoutSessionRequest();
$createCheckoutSessionRequest
  ->setReference("YOUR_ORDER_NUMBER")
  ->setLineItems(array($lineItem1, $lineItem2))
  ->setAmount($amount)
  ->setMerchantAccount("ADYEN_MERCHANT_ACCOUNT")
  ->setAdditionalData(
    array(
      "paypalRisk" => "STRINGIFIED_ADDITIONAL_DATA_ARRAY"
    )
  )
  ->setReturnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..")
  ->setShopperReference("YOUR_UNIQUE_SHOPPER_ID");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->sessions($createCheckoutSessionRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
LineItem lineItem1 = new LineItem
{
  Quantity = 1,
  ItemCategory = "PHYSICAL_GOODS",
  AmountExcludingTax = 590,
  Description = "Red Shoes",
  Sku = "ABC123",
  TaxAmount = 10
};

LineItem lineItem2 = new LineItem
{
  Quantity = 3,
  ItemCategory = "PHYSICAL_GOODS",
  AmountExcludingTax = 90,
  Description = "Polkadot Socks",
  Sku = "DEF234",
  TaxAmount = 10
};

Amount amount = new Amount
{
  Currency = "USD",
  Value = 1000
};

CreateCheckoutSessionRequest createCheckoutSessionRequest = new CreateCheckoutSessionRequest
{
  Reference = "YOUR_ORDER_NUMBER",
  LineItems = new List<LineItem>{ lineItem1, lineItem2 },
  Amount = amount,
  MerchantAccount = "ADYEN_MERCHANT_ACCOUNT",
  AdditionalData = new Dictionary<string, string>
  {

    { "paypalRisk", "STRINGIFIED_ADDITIONAL_DATA_ARRAY" }
  },
  ReturnUrl = "https://your-company.example.com/checkout?shopperOrder=12xy..",
  ShopperReference = "YOUR_UNIQUE_SHOPPER_ID"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Sessions(createCheckoutSessionRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const createCheckoutSessionRequest = {
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  amount: {
    currency: "USD",
    value: 1000
  },
  shopperReference: "YOUR_UNIQUE_SHOPPER_ID",
  reference: "YOUR_ORDER_NUMBER",
  returnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy..",
  lineItems: [ {
    quantity: 1,
    description: "Red Shoes",
    itemCategory: "PHYSICAL_GOODS",
    sku: "ABC123",
    amountExcludingTax: 590,
    taxAmount: 10
  }, {
    quantity: 3,
    description: "Polkadot Socks",
    itemCategory: "PHYSICAL_GOODS",
    sku: "DEF234",
    amountExcludingTax: 90,
    taxAmount: 10
  } ],
  additionalData: {
    paypalRisk: "STRINGIFIED_ADDITIONAL_DATA_ARRAY"
  }
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.0
import (
  "context"
  "github.com/adyen/adyen-go-api-library/v9/src/common"
  "github.com/adyen/adyen-go-api-library/v9/src/adyen"
  "github.com/adyen/adyen-go-api-library/v9/src/checkout"
)
// For the live environment, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
lineItem1 := checkout.LineItem{
  Quantity: common.PtrInt64(1),
  ItemCategory: common.PtrString("PHYSICAL_GOODS"),
  AmountExcludingTax: common.PtrInt64(590),
  Description: common.PtrString("Red Shoes"),
  Sku: common.PtrString("ABC123"),
  TaxAmount: common.PtrInt64(10),
}

lineItem2 := checkout.LineItem{
  Quantity: common.PtrInt64(3),
  ItemCategory: common.PtrString("PHYSICAL_GOODS"),
  AmountExcludingTax: common.PtrInt64(90),
  Description: common.PtrString("Polkadot Socks"),
  Sku: common.PtrString("DEF234"),
  TaxAmount: common.PtrInt64(10),
}

amount := checkout.Amount{
  Currency: "USD",
  Value: 1000,
}

createCheckoutSessionRequest := checkout.CreateCheckoutSessionRequest{
  Reference: "YOUR_ORDER_NUMBER",
  LineItems: []checkout.LineItem{
      lineItem1, lineItem2,
  },
  Amount: amount,
  MerchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  AdditionalData: &map[string]string{
    "paypalRisk": "STRINGIFIED_ADDITIONAL_DATA_ARRAY",
  },
  ReturnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy..",
  ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"),
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.SessionsInput().IdempotencyKey("UUID").CreateCheckoutSessionRequest(createCheckoutSessionRequest)
res, httpRes, err := service.PaymentsApi.Sessions(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
  "amount": {
    "currency": "USD",
    "value": 1000
  },
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "reference": "YOUR_ORDER_NUMBER",
  "returnUrl": "https://your-company.example.com/checkout?shopperOrder=12xy..",
  "lineItems": [ {
    "quantity": 1,
    "description": "Red Shoes",
    "itemCategory": "PHYSICAL_GOODS",
    "sku": "ABC123",
    "amountExcludingTax": 590,
    "taxAmount": 10
  }, {
    "quantity": 3,
    "description": "Polkadot Socks",
    "itemCategory": "PHYSICAL_GOODS",
    "sku": "DEF234",
    "amountExcludingTax": 90,
    "taxAmount": 10
  } ],
  "additionalData": {
    "paypalRisk": "{"additional_data":[{"key":"sender_first_name","value":"Simon"},{"key":"sender_last_name","value":"Hopper"},{"key":"receiver_account_id","value":"AH00000000000000000000001"}]}"
  }
}

# Send the request
result = adyen.checkout.payments_api.sessions(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'ADYEN_MERCHANT_ACCOUNT',
  :amount => {
    :currency => 'USD',
    :value => 1000
  },
  :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID',
  :reference => 'YOUR_ORDER_NUMBER',
  :returnUrl => 'https://your-company.example.com/checkout?shopperOrder=12xy..',
  :lineItems => [ {
    :quantity => 1,
    :description => 'Red Shoes',
    :itemCategory => 'PHYSICAL_GOODS',
    :sku => 'ABC123',
    :amountExcludingTax => 590,
    :taxAmount => 10
  }, {
    :quantity => 3,
    :description => 'Polkadot Socks',
    :itemCategory => 'PHYSICAL_GOODS',
    :sku => 'DEF234',
    :amountExcludingTax => 90,
    :taxAmount => 10
  } ],
  :additionalData => {
    :paypalRisk => '{:additional_data => [{:key => 'sender_first_name',:value => 'Simon'},{:key => 'sender_last_name',:value => 'Hopper'},{:key => 'receiver_account_id',:value => 'AH00000000000000000000001'}]}'
  }
}

# Send the request
result = adyen.checkout.payments_api.sessions(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const lineItem1: Types.checkout.LineItem = {
  quantity: 1,
  itemCategory: "PHYSICAL_GOODS",
  amountExcludingTax: 590,
  description: "Red Shoes",
  sku: "ABC123",
  taxAmount: 10
};

const lineItem2: Types.checkout.LineItem = {
  quantity: 3,
  itemCategory: "PHYSICAL_GOODS",
  amountExcludingTax: 90,
  description: "Polkadot Socks",
  sku: "DEF234",
  taxAmount: 10
};

const amount: Types.checkout.Amount = {
  currency: "USD",
  value: 1000
};

const createCheckoutSessionRequest: Types.checkout.CreateCheckoutSessionRequest = {
  reference: "YOUR_ORDER_NUMBER",
  lineItems: [lineItem1, lineItem2],
  amount: amount,
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  additionalData: {
    "paypalRisk": "STRINGIFIED_ADDITIONAL_DATA_ARRAY"
  },
  returnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy..",
  shopperReference: "YOUR_UNIQUE_SHOPPER_ID"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.sessions(createCheckoutSessionRequest, { idempotencyKey: "UUID" });
```

### Tab: `/payments`

If you implemented an [additional use case](/online-payments/build-your-integration).

| Parameter name                                                                                   | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [lineItems](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-lineItems) |          | Price and product information about the purchased items. For each item, you only need to send `quantity`, `description`, `itemCategory`, `sku`, `amountExcludingTax`, and `taxAmount`. The allowed values for `itemCategory` are:- **DIGITAL\_GOODS**: goods that are stored, delivered, and used in electronic format.
- **PHYSICAL\_GOODS**: tangible goods that can be shipped with proof of delivery.
- **DONATION**: a contribution or gift for which no goods or services are exchanged, usually to a not-for-profit organization.     |
| `additionalData.paypalPairingId`                                                                 |          | **Only for customer-initiated transactions where you use the Fraudnet SDK and pass the same pairing ID to Fraudnet and Adyen.** A unique ID determined by you, to link a transaction to a Fraudnet PayPal risk session.PayPal refers to this ID as *pairing ID*, *CMID*, or *tracking ID*.                                                                                                                                                                                                                                                   |
| `additionalData.paypalRisk`                                                                      |          | **Only for marketplaces as well as merchants in specific verticals.** The [PayPal risk fields](#paypal-risk-fields) that PayPal told you to send. You must include these fields in an `additional_data` array and send this in [stringified format](#risk-fields-formatting).Contact your PayPal account manager to learn which `paypalRisk` fields apply in your case and what happens if you do not populate a specific field. For a list of example fields, refer to the [common risk fields for marketplaces](#risk-field-marketplaces). |

The following example shows a payment request with the `lineItems` fields you can use for PayPal, and a few `paypalRisk` keys and values in `additionalData`.

#### curl

```bash
curl https://checkout-test.adyen.com/v72/payments \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
  "amount": {
    "currency": "USD",
    "value": 1000
  },
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod": {
    "type": "paypal",
    "subtype": "sdk"
  },
  "returnUrl": "https://your-company.example.com/checkout?shopperOrder=12xy..",
  "lineItems": [
    {
      "quantity": 1,
      "description": "Red Shoes",
      "itemCategory": "PHYSICAL_GOODS",
      "sku": "ABC123",
      "amountExcludingTax": 590,
      "taxAmount": 10
    },
    {
      "quantity": 3,
      "description": "Polkadot Socks",
      "itemCategory": "PHYSICAL_GOODS",
      "sku": "DEF234",
      "amountExcludingTax": 90,
      "taxAmount": 10
    }
  ],
  "additionalData": {
    "paypalRisk": "{\"additional_data\":[{\"key\":\"sender_first_name\",\"value\":\"Simon\"},{\"key\":\"sender_last_name\",\"value\":\"Hopper\"},{\"key\":\"receiver_account_id\",\"value\":\"AH00000000000000000000001\"}]}"
  }
}'
```

#### Java

```java
// Adyen Java API Library v27.0.0
import com.adyen.Client;
import com.adyen.enums.Environment;
import com.adyen.model.checkout.*;
import java.time.OffsetDateTime;
import java.util.*;
import com.adyen.model.RequestOptions;
import com.adyen.service.checkout.*;

// For the live environment, additionally include your liveEndpointUrlPrefix.
Client client = new Client("ADYEN_API_KEY", Environment.TEST);

// Create the request object(s)
LineItem lineItem1 = new LineItem()
  .quantity(1L)
  .itemCategory("PHYSICAL_GOODS")
  .amountExcludingTax(590L)
  .description("Red Shoes")
  .sku("ABC123")
  .taxAmount(10L);

LineItem lineItem2 = new LineItem()
  .quantity(3L)
  .itemCategory("PHYSICAL_GOODS")
  .amountExcludingTax(90L)
  .description("Polkadot Socks")
  .sku("DEF234")
  .taxAmount(10L);

Amount amount = new Amount()
  .currency("USD")
  .value(1000L);

PayPalDetails payPalDetails = new PayPalDetails()
  .subtype(PayPalDetails.SubtypeEnum.SDK)
  .type(PayPalDetails.TypeEnum.PAYPAL);

PaymentRequest paymentRequest = new PaymentRequest()
  .reference("YOUR_ORDER_NUMBER")
  .lineItems(Arrays.asList(lineItem1, lineItem2))
  .amount(amount)
  .merchantAccount("ADYEN_MERCHANT_ACCOUNT")
  .paymentMethod(new CheckoutPaymentMethod(payPalDetails))
  .additionalData(new HashMap<String, String>(Map.of(
    "paypalRisk", "STRINGIFIED_ADDITIONAL_DATA_ARRAY"
  )))
  .returnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..")
  .shopperReference("YOUR_UNIQUE_SHOPPER_ID");

// Send the request
PaymentsApi service = new PaymentsApi(client);
PaymentResponse response = service.payments(paymentRequest, new RequestOptions().idempotencyKey("UUID"));
```

#### PHP

```php
// Adyen PHP API Library v19.0.0
use Adyen\Client;
use Adyen\Environment;
use Adyen\Model\Checkout\LineItem;
use Adyen\Model\Checkout\Amount;
use Adyen\Model\Checkout\CheckoutPaymentMethod;
use Adyen\Model\Checkout\PaymentRequest;
use Adyen\Service\Checkout\PaymentsApi;

$client = new Client();
$client->setXApiKey("ADYEN_API_KEY");
// For the live environment, additionally include your liveEndpointUrlPrefix.
$client->setEnvironment(Environment::TEST);


// Create the request object(s)
$lineItem1 = new LineItem();
$lineItem1
  ->setQuantity(1)
  ->setItemCategory("PHYSICAL_GOODS")
  ->setAmountExcludingTax(590)
  ->setDescription("Red Shoes")
  ->setSku("ABC123")
  ->setTaxAmount(10);

$lineItem2 = new LineItem();
$lineItem2
  ->setQuantity(3)
  ->setItemCategory("PHYSICAL_GOODS")
  ->setAmountExcludingTax(90)
  ->setDescription("Polkadot Socks")
  ->setSku("DEF234")
  ->setTaxAmount(10);

$amount = new Amount();
$amount
  ->setCurrency("USD")
  ->setValue(1000);

$checkoutPaymentMethod = new CheckoutPaymentMethod();
$checkoutPaymentMethod
  ->setSubtype("sdk")
  ->setType("paypal");

$paymentRequest = new PaymentRequest();
$paymentRequest
  ->setReference("YOUR_ORDER_NUMBER")
  ->setLineItems(array($lineItem1, $lineItem2))
  ->setAmount($amount)
  ->setMerchantAccount("ADYEN_MERCHANT_ACCOUNT")
  ->setPaymentMethod($checkoutPaymentMethod)
  ->setAdditionalData(
    array(
      "paypalRisk" => "STATE_DATA"
    )
  )
  ->setReturnUrl("https://your-company.example.com/checkout?shopperOrder=12xy..")
  ->setShopperReference("STRINGIFIED_ADDITIONAL_DATA_ARRAY");

$requestOptions['idempotencyKey'] = 'UUID';

// Send the request
$service = new PaymentsApi($client);
$response = $service->payments($paymentRequest, $requestOptions);
```

#### C\#

```cs
// Adyen .net API Library v17.0.0
using Adyen;
using Environment = Adyen.Model.Environment;
using Adyen.Model;
using Adyen.Model.Checkout;
using Adyen.Service.Checkout;

// For the live environment, additionally include your liveEndpointUrlPrefix.
var config = new Config()
{
    XApiKey = "ADYEN_API_KEY",
    Environment = Environment.Test
};
var client = new Client(config);

// Create the request object(s)
LineItem lineItem1 = new LineItem
{
  Quantity = 1,
  ItemCategory = "PHYSICAL_GOODS",
  AmountExcludingTax = 590,
  Description = "Red Shoes",
  Sku = "ABC123",
  TaxAmount = 10
};

LineItem lineItem2 = new LineItem
{
  Quantity = 3,
  ItemCategory = "PHYSICAL_GOODS",
  AmountExcludingTax = 90,
  Description = "Polkadot Socks",
  Sku = "DEF234",
  TaxAmount = 10
};

Amount amount = new Amount
{
  Currency = "USD",
  Value = 1000
};

PayPalDetails payPalDetails = new PayPalDetails
{
  Subtype = PayPalDetails.SubtypeEnum.Sdk,
  Type = PayPalDetails.TypeEnum.Paypal
};

PaymentRequest paymentRequest = new PaymentRequest
{
  Reference = "YOUR_ORDER_NUMBER",
  LineItems = new List<LineItem>{ lineItem1, lineItem2 },
  Amount = amount,
  MerchantAccount = "ADYEN_MERCHANT_ACCOUNT",
  PaymentMethod = new CheckoutPaymentMethod(payPalDetails),
  AdditionalData = new Dictionary<string, string>
  {

    { "paypalRisk", "STRINGIFIED_ADDITIONAL_DATA_ARRAY" }
  },
  ReturnUrl = "https://your-company.example.com/checkout?shopperOrder=12xy..",
  ShopperReference = "YOUR_UNIQUE_SHOPPER_ID"
};

// Send the request
var service = new PaymentsService(client);
var response = service.Payments(paymentRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"});
```

#### NodeJS (JavaScript)

```js
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
const { Client, CheckoutAPI } = require('@adyen/api-library');
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const paymentRequest = {
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  amount: {
    currency: "USD",
    value: 1000
  },
  shopperReference: "YOUR_UNIQUE_SHOPPER_ID",
  reference: "YOUR_ORDER_NUMBER",
  paymentMethod: {
    type: "paypal",
    subtype: "sdk"
  },
  returnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy..",
  lineItems: [ {
    quantity: 1,
    description: "Red Shoes",
    itemCategory: "PHYSICAL_GOODS",
    sku: "ABC123",
    amountExcludingTax: 590,
    taxAmount: 10
  }, {
    quantity: 3,
    description: "Polkadot Socks",
    itemCategory: "PHYSICAL_GOODS",
    sku: "DEF234",
    amountExcludingTax: 90,
    taxAmount: 10
  } ],
  additionalData: {
    paypalRisk: "STRINGIFIED_ADDITIONAL_DATA_ARRAY"
  }
}

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" });
```

#### Go

```go
// Adyen Go API Library v10.4.0
import (
  "context"
  "github.com/adyen/adyen-go-api-library/v9/src/common"
  "github.com/adyen/adyen-go-api-library/v9/src/adyen"
  "github.com/adyen/adyen-go-api-library/v9/src/checkout"
)
// For the live environment, additionally include your liveEndpointUrlPrefix.
client := adyen.NewClient(&common.Config{
  ApiKey:      "ADYEN_API_KEY",
  Environment: common.TestEnv,
})

// Create the request object(s)
lineItem1 := checkout.LineItem{
  Quantity: common.PtrInt64(1),
  ItemCategory: common.PtrString("PHYSICAL_GOODS"),
  AmountExcludingTax: common.PtrInt64(590),
  Description: common.PtrString("Red Shoes"),
  Sku: common.PtrString("ABC123"),
  TaxAmount: common.PtrInt64(10),
}

lineItem2 := checkout.LineItem{
  Quantity: common.PtrInt64(3),
  ItemCategory: common.PtrString("PHYSICAL_GOODS"),
  AmountExcludingTax: common.PtrInt64(90),
  Description: common.PtrString("Polkadot Socks"),
  Sku: common.PtrString("DEF234"),
  TaxAmount: common.PtrInt64(10),
}

amount := checkout.Amount{
  Currency: "USD",
  Value: 1000,
}

payPalDetails := checkout.PayPalDetails{
  Subtype: common.PtrString("sdk"),
  Type: "paypal",
}

paymentRequest := checkout.PaymentRequest{
  Reference: "YOUR_ORDER_NUMBER",
  LineItems: []checkout.LineItem{
      lineItem1, lineItem2,
  },
  Amount: amount,
  MerchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  PaymentMethod: checkout.PayPalDetailsAsCheckoutPaymentMethod(&payPalDetails),
  AdditionalData: &map[string]string{
    "paypalRisk": "STRINGIFIED_ADDITIONAL_DATA_ARRAY",
  },
  ReturnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy..",
  ShopperReference: common.PtrString("YOUR_UNIQUE_SHOPPER_ID"),
}

// Send the request
service := client.Checkout()
req := service.PaymentsApi.PaymentsInput().IdempotencyKey("UUID").PaymentRequest(paymentRequest)
res, httpRes, err := service.PaymentsApi.Payments(context.Background(), req)
```

#### Python

```py
# Adyen Python API Library v12.5.1
import Adyen

adyen = Adyen.Adyen()
adyen.client.xapikey = "ADYEN_API_KEY"
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.client.platform = "test" # The environment to use library in.

# Create the request object(s)
json_request = {
  "merchantAccount": "ADYEN_MERCHANT_ACCOUNT",
  "amount": {
    "currency": "USD",
    "value": 1000
  },
  "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod": {
    "type": "paypal",
    "subtype": "sdk"
  },
  "returnUrl": "https://your-company.example.com/checkout?shopperOrder=12xy..",
  "lineItems": [ {
    "quantity": 1,
    "description": "Red Shoes",
    "itemCategory": "PHYSICAL_GOODS",
    "sku": "ABC123",
    "amountExcludingTax": 590,
    "taxAmount": 10
  }, {
    "quantity": 3,
    "description": "Polkadot Socks",
    "itemCategory": "PHYSICAL_GOODS",
    "sku": "DEF234",
    "amountExcludingTax": 90,
    "taxAmount": 10
  } ],
  "additionalData": {
    "paypalRisk": "{"additional_data":[{"key":"sender_first_name","value":"Simon"},{"key":"sender_last_name","value":"Hopper"},{"key":"receiver_account_id","value":"AH00000000000000000000001"}]}"
  }
}

# Send the request
result = adyen.checkout.payments_api.payments(request=json_request, idempotency_key="UUID")
```

#### Ruby

```rb
# Adyen Ruby API Library v9.5.1
require "adyen-ruby-api-library"

adyen = Adyen::Client.new
adyen.api_key = 'ADYEN_API_KEY'
# For the live environment, additionally include your liveEndpointUrlPrefix.
adyen.env = :test # Set to "live" for live environment

# Create the request object(s)
request_body = {
  :merchantAccount => 'ADYEN_MERCHANT_ACCOUNT',
  :amount => {
    :currency => 'USD',
    :value => 1000
  },
  :shopperReference => 'YOUR_UNIQUE_SHOPPER_ID',
  :reference => 'YOUR_ORDER_NUMBER',
  :paymentMethod => {
    :type => 'paypal',
    :subtype => 'sdk'
  },
  :returnUrl => 'https://your-company.example.com/checkout?shopperOrder=12xy..',
  :lineItems => [ {
    :quantity => 1,
    :description => 'Red Shoes',
    :itemCategory => 'PHYSICAL_GOODS',
    :sku => 'ABC123',
    :amountExcludingTax => 590,
    :taxAmount => 10
  }, {
    :quantity => 3,
    :description => 'Polkadot Socks',
    :itemCategory => 'PHYSICAL_GOODS',
    :sku => 'DEF234',
    :amountExcludingTax => 90,
    :taxAmount => 10
  } ],
  :additionalData => {
    :paypalRisk => '{:additional_data => [{:key => 'sender_first_name',:value => 'Simon'},{:key => 'sender_last_name',:value => 'Hopper'},{:key => 'receiver_account_id',:value => 'AH00000000000000000000001'}]}'
  }
}

# Send the request
result = adyen.checkout.payments_api.payments(request_body, headers: { 'Idempotency-Key' => 'UUID' })
```

#### NodeJS (TypeScript)

```ts
// Adyen Node API Library v18.0.0
// Require the parts of the module you want to use
import { Client, CheckoutAPI, Types } from "@adyen/api-library";
// Initialize the client object
// For the live environment, additionally include your liveEndpointUrlPrefix.
const client = new Client({apiKey: "ADYEN_API_KEY", environment: "TEST"});

// Create the request object(s)
const lineItem1: Types.checkout.LineItem = {
  quantity: 1,
  itemCategory: "PHYSICAL_GOODS",
  amountExcludingTax: 590,
  description: "Red Shoes",
  sku: "ABC123",
  taxAmount: 10
};

const lineItem2: Types.checkout.LineItem = {
  quantity: 3,
  itemCategory: "PHYSICAL_GOODS",
  amountExcludingTax: 90,
  description: "Polkadot Socks",
  sku: "DEF234",
  taxAmount: 10
};

const amount: Types.checkout.Amount = {
  currency: "USD",
  value: 1000
};

const payPalDetails: Types.checkout.PayPalDetails = {
  subtype: Types.checkout.PayPalDetails.SubtypeEnum.Sdk,
  type: Types.checkout.PayPalDetails.TypeEnum.Paypal
};

const paymentRequest: Types.checkout.PaymentRequest = {
  reference: "YOUR_ORDER_NUMBER",
  lineItems: [lineItem1, lineItem2],
  amount: amount,
  merchantAccount: "ADYEN_MERCHANT_ACCOUNT",
  paymentMethod: payPalDetails,
  additionalData: {
      paypalRisk: "STRINGIFIED_ADDITIONAL_DATA_ARRAY"
  },
  returnUrl: "https://your-company.example.com/checkout?shopperOrder=12xy..",
  shopperReference: "YOUR_UNIQUE_SHOPPER_ID"
};

// Send the request
const checkoutAPI = new CheckoutAPI(client);
const response = checkoutAPI.PaymentsApi.payments(paymentRequest, { idempotencyKey: "UUID" });
```

### Amounts in Hungarian Forints (HUF)

In case of a transaction in HUF, PayPal expects the transaction amount and the line item amounts to be rounded to the nearest whole amount. For example, an amount of HUF 74499 must be rounded to HUF 74500. PayPal also expects the rounded line item amounts to add up to the rounded transaction amount.

If you do not round the amounts, Adyen will do that. However, a discrepancy can occur between the transaction amount and the total of the line item amounts. When this happens, PayPal doesn't accept the transaction. To avoid that problem, we recommend that you round all HUF amounts yourself and check that they add up.

### PayPal risk fields

PayPal requires *marketplaces* and also merchants in *specific verticals* to send information about the context of the transaction, for risk mitigation purposes.

Not all businesses need to send risk fields. Contact your PayPal account manager to verify.

#### Common PayPal risk fields for marketplaces

As an example, the following table shows the most common `paypalRisk` fields that marketplaces need to send. It is possible that PayPal requires you to send more, less, or other fields.

| PayPal risk field                | Description                                                                                                                                                                                               | Data type/format                                                                                                                                | Example                      |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| **Sender profile** fields:       |                                                                                                                                                                                                           |                                                                                                                                                 |                              |
| sender\_account\_id              | The unique identifier of the buyer's account on the marketplace platform.                                                                                                                                 | String, alphanumeric                                                                                                                            | A12345N343                   |
| sender\_first\_name              | The buyer's first name registered with their marketplace account.                                                                                                                                         | String, alphanumeric                                                                                                                            | John                         |
| sender\_last\_name               | The buyer's last name registered with their marketplace account.                                                                                                                                          | String, alphanumeric                                                                                                                            | Smith                        |
| sender\_email                    | The buyer's email address registered with their marketplace account.                                                                                                                                      | String in [E.123](https://en.wikipedia.org/wiki/E.123) email address format                                                                     | john.smith\@email.com        |
| sender\_phone                    | The buyer's phone number registered with their marketplace account.                                                                                                                                       | String in [E.123](https://en.wikipedia.org/wiki/E.123) telephone number format, national notation                                               | 0687164125                   |
| sender\_address\_zip             | **US only**. The buyer's postal code registered with their marketplace account.                                                                                                                           | String, alphanumeric                                                                                                                            | 60661                        |
| sender\_country\_code            | The buyer's country registered with their marketplace account.                                                                                                                                            | String in two-character [ISO-3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) alpha-2 country code format. Exception: *QZ* (Kosovo).   | US                           |
| sender\_create\_date             | The date that the buyer's marketplace account was created.                                                                                                                                                | String in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format                                                                        | 2012-12-09T19:14:55.277-0:00 |
| sender\_signup\_ip               | The IP address that the buyer used when signing up on the marketplace platform.                                                                                                                           | String in IPv4 or IPv6 format                                                                                                                   | 213.52.172.120               |
| sender\_popularity\_score        | If you need to provide this field, ask your PayPal account manager for instructions.                                                                                                                      | String, possible values: **high**, **medium**, **low**                                                                                          | high                         |
| **Receiver profile** fields:     |                                                                                                                                                                                                           |                                                                                                                                                 |                              |
| receiver\_account\_id            | The unique identifier of the seller's account on the marketplace platform.                                                                                                                                | String, alphanumeric                                                                                                                            | AH00000000000000000000001    |
| receiver\_create\_date           | The date that the seller's marketplace account was created.                                                                                                                                               | String in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format                                                                        | 2012-12-09T19:14:55.277-0:00 |
| receiver\_email                  | The seller's email address registered with their marketplace account.                                                                                                                                     | String in [E.123](https://en.wikipedia.org/wiki/E.123) email address format                                                                     | john.smith\@email.com        |
| receiver\_address\_country\_code | The seller's country registered with their marketplace account.                                                                                                                                           | String in two-character [ISO-3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) alpha-2 country code format. Exception: **QZ** (Kosovo). | US                           |
| business\_name                   | The seller's business name registered with their marketplace account.                                                                                                                                     | String, alphanumeric                                                                                                                            |                              |
| recipient\_popularity\_score     | If you need to provide this field, ask your PayPal account manager for instructions.                                                                                                                      | String, possible values: **high**, **medium**, **low**                                                                                          | high                         |
| **Sender-Receiver interaction**: |                                                                                                                                                                                                           |                                                                                                                                                 |                              |
| first\_interaction\_date         | The date of the first interaction between the buyer and the seller. The marketplace defines what an *interaction* is. For example, a payment transaction, a buyer choosing to follow a seller, and so on. | String in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date format                                                                        | 2012-12-09T19:14:55.277-0:00 |
| **Transaction information**:     |                                                                                                                                                                                                           |                                                                                                                                                 |                              |
| txn\_count\_total                | The total number of transactions that the buyer has made on the platform. These can be PayPal payments, or payments using a different payment method.                                                     | Number                                                                                                                                          |                              |
| **Payment Flow/Model/Type**:     |                                                                                                                                                                                                           |                                                                                                                                                 |                              |
| vertical                         | If the seller is active in more than one business vertical, this field indicates the vertical that applies to the transaction.                                                                            | String, alphanumeric                                                                                                                            | Household goods              |
| transaction\_is\_tangible        | Indicates if the transaction is for tangible goods.                                                                                                                                                       | Boolean in string format. Possible values: **0** (false), or **1** (true)                                                                       | 0                            |

#### Formatting

To send PayPal risk fields, you must use the `additionalData.paypalRisk` field, and specify the risk fields as a stringified `additional_data` array. Each array item consists of:

* `key`: the name of the PayPal risk field.
* `value`: the value of the PayPal risk field for the current transaction.

Here is an example of the original array and the array in stringified format.

**additional\_data array**

```json
{
  "additional_data": [
    {
      "key": "sender_first_name",
      "value": "Simon"
    },
    {
      "key": "sender_last_name",
      "value": "Hopper"
    },
    {
      "key": "receiver_account_id",
      "value": "AH00000000000000000000001"
    }
  ]
}
```

**Stringified array**

```sh
"{\"additional_data\":[{\"key\":\"sender_first_name\",\"value\":\"Simon\"},{\"key\":\"sender_last_name\",\"value\":\"Hopper\"},{\"key\":\"receiver_account_id\",\"value\":\"AH00000000000000000000001\"}]}"
```

## Drop-in configuration

### Required configuration

Select which endpoint you are using:

### Tab: `/sessions`

This is the default with [Drop-in v5.0.0](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Drop-in) or later.

There is no additional configuration you need to include for PayPal.

### Tab: `/payments`

If you implemented an [additional use case](/online-payments/build-your-integration).

| Parameter name | Required                                                                                    | Description                                                                                                                                                                                                                                         |   |
| -------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - |
| `amount`       | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The `currency` and `value` of the transaction.                                                                                                                                                                                                      |   |
| `countryCode`  | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The shopper's country/region. This is used to filter the list of available payment methods to your shopper. Format: the two-letter [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. Exception: **QZ** (Kosovo). |   |

Include the parameters when creating an object for the global configuration of your Drop-in integration.

**\<code>AdyenCheckout\</code> configuration**

```js
const configuration = {
    // ...  other required configuration
    environment: "test", // Change this to "live" when you are ready to accept live PayPal payments.
    amount: {
        currency: "EUR",
        value: 1000
    },
    countryCode: "NL" // Only needed for test. When live, this is retrieved automatically.
};
```

### Drop-in v3.13.0 or earlier

For Drop-in v3.13.0 or earlier, you must also provide the following parameters in the payment method configuration.

| Parameter name             | Required                                                                                    | Description                                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `configuration.merchantId` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your PayPal Merchant ID.                                                                                  |
| `configuration.intent`     | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Set to `authorize` if you do not want to immediately capture the funds. The default value is **capture**. |

The following example shows additional required configuration Drop-in if you are using v3.13.0 or earlier.

```js
const paypalConfiguration = {
    configuration: {
        merchantId: "YOUR_PAYPAL_MERCHANT_ID",
        //Your PayPal Merchant ID. To find your ID, see the page about setting up PayPal.
        intent: "authorize"
    }
};
```

Include the `paypalConfiguration` object when [creating a configuration object](/online-payments/build-your-integration/sessions-flow?platform=Web\&integration=Drop-in#configure):

**AdyenCheckout configuration**

```js
const configuration = {
  // ...  other required configuration
  paymentMethodsConfiguration: {
    paypal: paypalConfiguration
  }
};
```

Pass the Drop-in configuration object when creating your instance of `AdyenCheckout`:

```js
const checkout = await AdyenCheckout(configuration);
```

Set `SECURE_CROSS_ORIGIN_OPENER_POLICY = 'same-origin-allow-popups'` in the [header of your web page](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cross-Origin-Opener-Policy) to ensure that important PayPal popups open.

### Optional configuration

When creating an instance of Drop-in, you can also:

* [Add a Content Security Policy (CSP) nonce](#csp).
* [Customize the layout](#layout) of the PayPal Smart Payment Buttons.
* [Handle shipping changes](#shipping-changes).
* [Validate user input](#validate-user-input).
* [Disable the PayPal Credit button](#paypal-credit).
* [Add PayPal Pay Later messages and buttons](#add-paylater).
* [Disable PayPal Pay Later](#disable-paylater).
* [Set the intent for individual payments](#intent).
* [Hide Venmo](#hide-venmo).

#### Content Security Policy (CSP) nonce

You can include a `cspNonce` to add a [CSP nonce](https://developer.paypal.com/sdk/js/configuration/#link-cspnonce) if you use this on your site. This was added in [v5.2.0](/online-payments/release-notes/?title%5B0%5D=Web%2BComponents%2FDrop-in#releaseNote=2021-11-01-web-componentsdrop-in-5.2.0).

#### Layout

You can configure the layout of the PayPal Smart Payment Buttons. To do that, configure the `style` element in the PayPal payment method configuration. Use the [available style options](https://developer.paypal.com/docs/checkout/standard/customize/buttons-style-guide/).

#### Shipping changes

You can use [PayPal's callback method `onShippingChange`](https://developer.paypal.com/docs/checkout/standard/customize/shipping-options/#link-shippingcallbackwithshippingoptions) to listen to shipping address changes and validate that you support the shipping address.

#### Validate user input

You can [validate user input](https://developer.paypal.com/docs/checkout/standard/customize/validate-user-input/) with the following parameters:

* `onInit`: Called when the button renders.
* `onClick`: Called when one of the PayPal buttons is clicked.

#### Disable PayPal Credit

You can use `blockPayPalCreditButton` to control rendering the PayPal Credit button. Set this parameter to `true` if you do not want the PayPal Credit button to be rendered. The default value is `false`.

#### Add PayPal Pay Later messages and buttons

PayPal Pay Later is supported in the following countries/regions: AU, FR, DE, IT, ES, UK, US, with local currencies. Certain limitations apply to cross-border payments, when a shopper pays in a country/region other than where you are registered.

To present this option:

1. Set `enableMessages` to **true**, to enable Pay Later messaging on your website.
2. Render Pay Later messages and buttons by adding code to your page as described in [PayPal's instructions](https://developer.paypal.com/docs/checkout/pay-later/integrate/).

#### Disable PayPal Pay Later

You can use `blockPayPalPayLaterButton` to control rendering the PayPal PayLater button. Set this parameter to `true` if you do not want the PayPal PayLater button to be rendered. The default value is `false`.

#### Example

```js
const paypalConfiguration = {
  style: { // Optional configuration for PayPal payment buttons.
      layout: "vertical",
      color: "blue"
  },
  cspNonce: "MY_CSP_NONCE",
  onShippingChange: function(data, actions) {
      // Listen to shipping changes.
  },
  onInit: (data, actions) => {
      // onInit is called when the button first renders.
      // Call actions.enable() to enable the button.
      actions.enable();
      // Or actions.disable() to disable it.
  },
  onClick: () => {
      // onClick is called when the button is clicked.
  },
  blockPayPalCreditButton: true,
  blockPayPalPayLaterButton: true
};
```

#### Set the `intent` for individual payments

From v5.34.0 onwards, you can use `intent` to determine when the funds are captured and whether the payment details are tokenized:

* `capture`: authorizes and capture immediately.
* `authorize`: authorizes immediately and captures later.
* `subscription`: specifies this is a subscription payment.
* `tokenize`: specifies this is a billing payment.

#### Example

```js
const paypalConfiguration = {
    intent: "authorize"
};
```

#### Hide Venmo

If you and your shopper are both located in the US, [Venmo](/payment-methods/paypal#venmo) is shown in the PayPal Component by default. To hide Venmo in the PayPal Component, set `blockPayPalVenmoButton` to **true**.

## Get the payment outcome

You can use the `resultCode` from the API response to show the shopper the [current payment status](/account/payments-lifecycle/). The `resultCode` values you can receive for PayPal are:

| resultCode                  | Description                                                                  | Action to take                                                                                                                                                                                                                                                                                             |
| --------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authorised**              | The payment was successful.                                                  | Inform the shopper that the payment was successful. Note that the transaction may still fail, for example due to risk rules that are applied after authorisation. Wait for the [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION) webhook to learn the final outcome. |
| **Pending** or **Received** | The shopper has completed the payment but the final result is not yet known. | Inform the shopper that you received their order, and are waiting for the payment to be completed. Wait for the [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION) webhook to learn the final outcome.                                                                |
| **Error**                   | There was an error when the payment was being processed.                     | Inform the shopper that there was an error processing their payment. Wait for the [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION) webhook. This will contain a `refusalReason` that indicates the cause of the error.                                              |
| **Refused**                 | The payment was refused by the shopper's bank.                               | Ask the shopper to try the payment again using a different payment method.                                                                                                                                                                                                                                 |
| **Cancelled**               | The shopper canceled the PayPal payment.                                     | Ask the shopper to select a different payment method.                                                                                                                                                                                                                                                      |

However, the synchronous API response doesn't give you the final outcome. To learn the final status of a payment and determine how to proceed with the order, you should wait for webhooks. This is especially important if you use any [standard risk rules](/risk-management/configure-standard-risk-rules) or [custom risk rules](/risk-management/configure-custom-risk-rules) that trigger **after** authorisation.

The webhooks you can receive for PayPal are:

| eventCode                                                                               | success field | Description                                     | Action to take                                                                                                                                                                  |
| --------------------------------------------------------------------------------------- | ------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION) | **false**     | The transaction failed.                         | Cancel the order and inform the shopper that the payment failed.                                                                                                                |
| [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION) | **true**      | The shopper successfully completed the payment. | Inform the shopper that the payment has been successful and proceed with the order.                                                                                             |
| [OFFER\_CLOSED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/OFFER_CLOSED)  | **true**      | The shopper did not complete the payment.       | Cancel the order and inform the shopper that the payment timed out. Note that you only receive this information if you [enable the OFFER\_CLOSED event code](#add-to-webhooks). |

### Include more information in webhooks

For PayPal, we recommend adding the following information to your [standard webhooks](/development-resources/webhooks/webhook-types):

* [OFFER\_CLOSED](https://docs.adyen.com/api-explorer/Webhooks/latest/post/OFFER_CLOSED) event code: informs you if the shopper failed to complete the payment. To enable receiving this event code, follow the [instructions for non-default event codes](/development-resources/webhooks/webhook-types/#non-default-event-codes).

* PayPal specific details. When enabled, your standard webhooks return the following details as `additionalData`:

  * `paypalEmail`: the email address of the shopper's PayPal account.
  * `paypalPayerId`: the shopper's PayPal Payer ID.
  * `paypalPayerStatus`: indicates if the shopper's account has been verified by PayPal.
  * `paypalAddressStatus`: indicates if the shopper's address has been confirmed by PayPal.
  * `paypalProtectionEligibility`: indicates if the payment is eligible for PayPal Seller Protection.
  * `paypalPayerResidenceCountry`: the shopper's country or region of residence.

  To enable receiving these details, follow the [instructions for additional settings](/development-resources/webhooks/webhook-types/additional-settings/), making sure to select **Include PayPal Details**.

## Recurring payments

PayPal supports [tokenization](/online-payments/tokenization) for recurring payments.

We strongly recommend that you ask explicit permission from the shopper if you intend to make future recurring payments. Being transparent about the payment schedule and the charged amount reduces the risk of chargebacks.

### Prepare for tokenization

1. Note the PayPal setup requirements:

   * If you are not a marketplace and do not have a so-called indirect settlement arrangement, **Vault (recurring) permissions** must be enabled in your [PayPal setup](/payment-methods/paypal/setup-paypal-direct-merchants#add-paypal). If you completed the setup without enabling recurring transactions, restart the setup flow and this time select the relevant option.
   * If you are a marketplace or have an indirect settlement arrangement, inform our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) that you want to make recurring PayPal payments. They will then take care of the correct setup.
   * If you intend to share tokens across PayPal accounts, make sure your PayPal accounts are configured to do so. You may need to contact your PayPal account manager or support team.

2. To be able to create tokens through initial zero-value authorization requests:

   * If you use the `/sessions` endpoint, make sure you are on **v5.3.0** or later.
   * If you use the `/payments` endpoint, update your configuration as described in the next step.

3. If you want to use the `/payments` endpoint for creating a token through an initial zero-value authorization request, update your Drop-in configuration in one of the following ways:

   * Add `intent: "tokenize"` to the [PayPal configuration object](#optional-config). This requires **v5.34.0** or later.
   * Add the `amount` object to the global Drop-in configuration. This requires **v5.3.0** or later.

   Skip this step if you are not going to create tokens through zero-value authorization requests to the `/payments` endpoint.

   ### Tab: Using the tokenize intent

   **PayPal configuration object with the tokenize intent**

   ```js
   const paypalConfiguration = {
     // ... other optional configuration
     intent: "tokenize"
   };
   ```

   ### Tab: Using the amount object

   **Global configuration object with the amount object**

   ```js
   const configuration = {
     // ...  other configuration
     amount: {
       currency: "USD",
       value: 0
     }
   };
   ```

   No token is created if you send a zero-value authorization request to the `/payments` endpoint without having updated the configuration as described above.

### Create and use tokens

When the [preparation](#prepare-recurring) is completed, creating and using tokens for PayPal payments is the same as described for tokenization in general, except for the following:

1. To create a token through a zero-value authorization request, in your initial [/sessions](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions) or [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) payment request include:

   | Parameter      | Description                                                                                                                                                               |
   | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `shopperEmail` | The shopper's email address. Required when making a zero-value authorization request. Do not include this parameter if the request is not for a zero-value authorization. |
   | `amount.value` | Set to **0** when making a zero-value authorization request.                                                                                                              |

2. Proceed as described for tokenization in general: get the shopper reference and the token from the [recurring.token.created](https://docs.adyen.com/api-explorer/Tokenization-webhooks/latest/post/recurring.token.created) webhook, and use this data in future payments for the shopper.

For instructions, see:

* [CardOnFile](/online-payments/tokenization/create-and-use-tokens/?tab=one_off_payments_1)
* [Subscription](/online-payments/tokenization/create-and-use-tokens/?tab=subscriptions_2)
* [UnscheduledCardOnFile](/online-payments/tokenization/create-and-use-tokens/?tab=automatic_top_ups_3)
* [Recurring tokens life cycle events webhook](/online-payments/tokenization/create-and-use-tokens/#enable-the-webhook)

## Refunds

If you have not captured a PayPal payment, you can [cancel](/online-payments/cancel) it. If you have captured the payment and you want to return the funds to the shopper, you need to [refund](/online-payments/refund/) it.

For partial refunds, the instructions differ depending on your capture settings:

* If [payments are captured immediately after authorization](#captured-immediately) you need to include `lineItems` in your partial refund request.
* If [payments are captured later](#captured-later) you need to include a `capturePspReference` in your partial refund request.

### Partial refund when payments are captured immediately

If you are using the default setup where PayPal payments are captured immediately after authorization, partially refund a PayPal payment as follows:

1. In your [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request, specify:

   | Parameter   | Required                                                                                    | Description                                                                                                                                                                                                                   |
   | ----------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `amount`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The amount that is refunded to the shopper.                                                                                                                                                                                   |
   | `lineItems` |                                                                                             | Price and product information for the items that the shopper should pay for. The sum of the `lineItems` must match the `amount`. If they do not match, Adyen will add a dummy `lineItem` entry to account for the difference. |

   Only specify the items that you are refunding the money for.

   The following example shows how to make a partial refund for item #1 of the above order.

   **Example /refunds request for partial refund**

   ```java
   curl https://checkout-test.adyen.com/v65/payments/TCG5XS42X8NKGK82/refunds \
   -H 'x-api-key: ADYEN_API_KEY' \
   -H 'content-type: application/json' \
   -d '{
       "reference": "YOUR_UNIQUE_REFERENCE",
       "amount": {
           "value": 1200,
           "currency": "EUR"
       },
       "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
       "lineItems": [
           {
               "quantity": "1",
               "taxPercentage": "2000",
               "description": "Polo shirt",
               "id": "Item #1",
               "itemCategory": "Shirts",
               "amountIncludingTax": "1200",
               "taxAmount": "200",
               "amountExcludingTax": "1000",
               "productUrl": "https://www.mystoredemo.io/#/product/01",
               "imageUrl": "https://www.mystoredemo.io/1689f3f40b292d1de2c6.png"
           }
       ]
   }
   ```

2. Note that in the response, the `pspReference` is specifically for the refund transaction, not for the original payment.

   **Example /refunds response**

   ```java
   {
       "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
       "pspReference": "IHG5XS4FGKVLGK82",
       "reference": "YOUR_UNIQUE_REFERENCE",
       "status": "received",
       "amount": {
           "currency": "EUR",
           "value": 1200
       },
       "lineItems": [
           {
               "quantity": "1",
               "taxPercentage": "2000",
               "description": "Polo shirt",
               "id": "Item #1",
               "itemCategory": "Shirts",
               "amountIncludingTax": "1200",
               "taxAmount": "200",
               "amountExcludingTax": "1000",
               "productUrl": "https://www.mystoredemo.io/#/product/01",
               "imageUrl": "https://www.mystoredemo.io/1689f3f40b292d1de2c6.png"
           }
       ]
   }
   ```

### Partial refund when payments are captured later

Your request for a partial refund must include a `capturePspReference` if all of the following is true:

* You configured capturing payments later, instead of immediately after authorization.
* Multiple partial captures are enabled for your account.
* You are going to do more than one partial capture.

PayPal uses this unique capture reference to locate the transaction in their systems. Without it, the refund can fail.

To partially refund a PayPal payment if payments are captured later:

1. Get the `pspReference` from the [/payments/{paymentPspReference}/captures](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures) response for the payment that you want to partially refund. This is the reference to the capture that PayPal needs.

2. In your [/payments/{paymentPspReference}/refunds](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/refunds) request, specify:

   | Parameter             | Required | Description                                                                                                                                                                                                                |
   | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `capturePspReference` |          | The `pspReference` from the [/payments/{paymentPspReference}/captures](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments/\(paymentPspReference\)/captures) response. Do not use the `paymentPspReference`. |

   **Example /refunds request for partial refund when payments are captured later**

   ```java
   curl https://checkout-test.adyen.com/v72/payments/TCG5XS42X8NKGK82/refunds \
   -H 'x-api-key: ADYEN_API_KEY' \
   -H 'content-type: application/json' \
   -d '{
       "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
       "reference": "YOUR_UNIQUE_REFERENCE",
       "capturePspReference": "QSKF8GZ2KX998X72",
       "amount": {
           "value": 1200,
           "currency": "EUR"
       }
   }
   ```

## Set up PayPal Seller Protection

PayPal Seller Protection only applies to physical goods.

If you participate in the [PayPal Seller Protection](https://www.paypal.com/us/webapps/mpp/security/seller-protection) program, make sure that you submit the following fields in your payment requests:

* [deliveryAddress](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-deliveryAddress)
* [shopperName](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments#request-shopperName)
* [lineItems](https://docs.adyen.com/api-explorer/Checkout/latest/post/sessions#request-lineItems)

The details provided in these fields will populate the **Ship to** section of the PayPal checkout.

We recommend that you check that your setup is working correctly with a test payment. Make sure that you submit the correct fields, and that the test payment is marked as eligible for PayPal Seller Protection in the transaction details.

## Test and go live

### Test your integration

When you are done setting up your integration, use your PayPal sandbox accounts to test the PayPal payment flow. Your **business** sandbox account lets you simulate your role as a merchant when testing payments. With your **personal** sandbox account you can simulate the role of a customer.

Refer to the following resources:

* For instructions to create sandbox accounts, see [Set up PayPal](/payment-methods/paypal/setup-paypal-direct-merchants#dev-sandbox-accounts).

* For testing instructions, see the [PayPal sandbox testing guide](https://developer.paypal.com/api/rest/sandbox/).

You can check the status of a PayPal test payment in your [Customer Area](https://ca-test.adyen.com/) > **Transactions** > **Payments**.

### Before you go live

For live operations, you need to get a live PayPal business account and configure your live environment. See [Set up PayPal](/payment-methods/paypal/setup-paypal-direct-merchants#go-live).

Note that in the live environment, PayPal will only be available if:

* The shopper is logged in to their PayPal account.
* The shopper has at least one valid payment method on their PayPal account.

## See also

* [Web Drop-in integration guide](/online-payments/drop-in-web)
* [PayPal API](https://developer.paypal.com/docs/api/overview/)
* [PayPal raw responses](/development-resources/raw-acquirer-responses#paypal-raw-responses)
* [Troubleshooting PayPal errors](/payment-methods/paypal/paypal-troubleshooting)
* [API Explorer](https://docs.adyen.com/api-explorer/#/CheckoutService/latest/overview)