PayPal Drop-in integration

Add PayPal to an existing Android Drop-in integration.

Our Android Drop-in renders PayPal in your payment form, and redirects the shopper to complete the payment. As with other redirect payment methods, you need to check the payment result after the shopper returns to your app.

Requirements

Requirement	Description
Integration type	Make sure that you have an existing Drop-in integration.
Setup steps	Before you begin, complete the PayPal setup steps.

Show PayPal in your payment form

Drop-in uses the countryCode and the amount.currency from your /paymentMethods request to show the available payment methods to your shopper.

To show PayPal in your payment form, specify in your /paymentMethods request:

countryCode: Any supported country/region. For example, NL
amount.currency: Any supported currency. For example, .
amount.value: The value of the payment, in minor units.

When the shopper proceeds to pay, Drop-in returns the paymentComponentData.paymentMethod. Pass the paymentComponentData.paymentMethod to your server — these are the shopper details that you need to make the payment.

Make a payment

The main optional payment request parameters to consider are lineItems and paypalRisk fields.

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 email address format	john.smith@email.com
sender_phone	The buyer's phone number registered with their marketplace account.	String in 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 alpha-2 country code format	US
sender_create_date	The date that the buyer's marketplace account was created.	String in 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 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 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 alpha-2 country code format	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 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

Make a payment request

From your server, make a POST /payments request, specifying:

Parameter name	Required	Description
`paymentMethod`		The `paymentComponentData.paymentMethod` from your client app.
channel		The platform where a payment transaction takes place. Set this to Android.
returnUrl		The URL to where the shopper should be redirected back to after they complete the payment. Get this URL from the Component in the `RedirectComponent.getReturnUrl(context)`.
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 if you use the Magnes SDK and pass the same pairing ID to Magnes and Adyen. A unique ID determined by you, to link a transaction to a Magnes 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. A stringified `additional_data` array with the PayPal risk fields that PayPal told you to send. 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. Contact your PayPal account manager to learn which PayPal risk 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.

The /payments response contains:

action: Object containing information about the redirect.

Pass the action object to your client app.

Check the payment result

Drop-in redirects the shopper to complete the payment. When the shopper returns back to your app, Drop-in provides the actionComponentData object.

From your server, make a POST /payments/details request providing:

details: The actionComponentData.details object from Drop-in.

You receive a response containing:

resultCode: Use this to present the payment result to your shopper.
pspReference: Our unique identifier for the transaction.

Get the payment outcome

You can use the resultCode from the API response to show the shopper the current payment status. 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 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 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 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 or custom risk rules that trigger after authorisation.

The webhooks you can receive for PayPal are:

eventCode	success field	Description	Action to take
AUTHORISATION	false	The transaction failed.	Cancel the order and inform the shopper that the payment failed.
AUTHORISATION	true	The shopper successfully completed the payment.	Inform the shopper that the payment has been successful and proceed with the order.
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.

Include more information in webhooks

For PayPal, we recommend adding the following information to your standard webhooks:

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.
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, making sure to select Include PayPal Details.

Recurring payments

To prepare for making recurring payments:

Enable recurring payments.
Configure webhooks to ensure they include details about recurring payments.

Then you can make recurring payments:

In the initial payment request, include specific parameters to create a token.
This token represents the shopper's stored payment details.
In the later recurring payment requests, use the token.

Enable recurring payments

To enable recurring payments for PayPal, follow these steps:

Contact PayPal Support to enable Reference Transactions on your seller account. For this, you need your Merchant ID.
Enable the recurring permissions on your PayPal account. Follow the steps described in the section Give Adyen access to your PayPal account, and also grant the permissions Charge an existing customer based on a prior transaction and Create and manage Recurring Payments.

Configure webhooks

Add the following information to your standard webhooks:

recurring.recurringDetailReference and recurring.shopperReference. To enable receiving these details as additionalData in the AUTHORISATION webhook:
1. Log in to your Customer Area.
2. Go to Developers > Additional data.
3. Under Payment, select Recurring details.
RECURRING_CONTRACT event code: informs you that a recurring contract has been created. To enable receiving this event code, follow the instructions for non-default event codes.

Create a token

To create a token, include the following parameters in your initial /sessions or /paymentspayment request:

recurringProcessingModel: Subscription or UnscheduledCardOnFile
shopperInteraction: Ecommerce
shopperReference: Your unique identifier for the shopper
storePaymentMethod: true
shopperEmail: Required when making a zero-value authorization request with amount.value: 0. Do not include this parameter if the request is not for a zero-value authorization.

When the payment has been settled, you receive a webhook containing:

eventCode: RECURRING_CONTRACT
originalReference: The pspReference of the initial payment.
pspReference: The token for the stored payment details. Use this to make later recurring payments for the shopper.
additionalData.recurring.shopperReference: your unique shopper reference. Use this to associate the shopper with the token.

Make a payment with a token

To make a later, recurring payment with the token, include in your /sessions or /payments request:

paymentMethod.storedPaymentMethodId: The pspReference from the RECURRING_CONTRACT.

You can also get this value using the /listRecurringDetails endpoint.
shopperReference: The unique shopper identifier that you specified when creating the token.
shopperInteraction: ContAuth.
recurringProcessingModel: Subscription or UnscheduledCardOnFile.

Refunds

If you have not captured a PayPal payment, you can cancel it. If you have captured the payment and you want to return the funds to the shopper, you need to refund it.

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

If payments are captured immediately after authorization you need to include lineItems in your partial refund request.
If payments are 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:

In your /payments/{paymentPspReference}/refunds request, specify:

Parameter	Required	Description
`amount`		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.

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

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:

Get the pspReference from the /payments/{paymentPspReference}/captures response for the payment that you want to partially refund. This is the reference to the capture that PayPal needs.
In your /payments/{paymentPspReference}/refunds request, specify:

Parameter Required Description

capturePspReference The pspReference from the /payments/{paymentPspReference}/captures response. Do not use the paymentPspReference.

Set up PayPal Seller Protection

PayPal Seller Protection only applies to physical goods.

If you participate in the PayPal Seller Protection program, make sure that you submit the following fields in your payment requests:

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.

For testing instructions, see the PayPal sandbox testing guide.

You can check the status of a PayPal test payment in your Customer Area > 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.

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.