If you have an existing Android Components integration, you can use our Redirect Component to redirect the shopper to complete the payment. As with other redirect payment methods, you need to handle the redirect after the shopper returns to your app.
Before you begin
This page assumes you have already:
Show PayPal in your payment form
Include PayPal in the list of available payment methods. You don't need to collect any information from the shopper in your payment form.
- Specify in your /paymentMethods request:
The response contains
We provide logos for PayPal which you can use on your payment form. For more information, refer to Downloading logos.
Make a payment
The main optional payment request parameters to consider are
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.
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 email@example.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||220.127.116.11|
|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 firstname.lastname@example.org|
|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|
|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|
|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|
|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
Set this to paypal. 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
lineItems Price and product information about the purchased items. For each item, you only need to send
The allowed values for
- 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.
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.
Only for marketplaces and for merchants in specific verticals.
additional_dataarray with the PayPal risk fields that PayPal told you to send. Each array item consists of:
Contact your PayPal account manager to learn which PayPal risk fields apply in your case and what happens if you don't populate a specific field. For a list of example fields, refer to the common risk fields for marketplaces.
key: the name of the PayPal risk field.
value: the value of the PayPal risk field for the current transaction.
The /payments response contains:
action: Object containing information about the redirect.
actionobject to your client app.
Handle the redirect
- Use the Redirect Component to redirect the shopper to PayPal.
- After the shopper returns to your app, make a POST /payments/details request from your server, providing:
actionComponentData.detailsobject from the Redirect Component.
You receive a response containing:
resultCode: Use this to present the payment result to your shopper.
pspReference: Our unique identifier for the transaction.
Present the payment result
resultCode that you received in the /payments/details response to present the payment result to your shopper.
resultCode values you can receive for PayPal are:
|resultCode||Description||Action to take|
|Authorised||The payment was successful.||Inform the shopper that the payment has been successful.
See note 1
|The shopper has completed the payment but the final result is not yet known.||Inform the shopper that you've received their order, and are waiting for the payment to be completed.
You will receive the final result of the payment in an AUTHORISATION webhook.
|Error||There was an error when the payment was being processed.||Inform the shopper that there was an error processing their payment.
You will receive more information about the error in the AUTHORISATION webhook. The webhook contains a
|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.|
|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.
To receive this event code as part of your standard webhooks, see non-default event codes.
Include more details in webhooks
You can include more PayPal details in your standard webhooks. When you enable additional settings, you can get the following PayPal specific information returned as
additionalData in your standard webhooks:
Fields included in
Include PayPal Details
Receive the PayPal details of the shopper.
To include PayPal details in your standard webhooks:
- In your Customer Area, go to Developers > Webhooks.
- Next to Standard Notification, select the edit webhook icon .
- Under Additional Settings, select Include PayPal Details.
- Select Save Configuration.
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 paymentsTo 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.
You can get details about recurring payments in the AUTHORISATION and RECURRING_CONTRACT webhooks.
To receive the
recurring.recurringDetailReference and the
recurring.shopperReference in the
additionalDetails of the AUTHORISATION webhook:
- Log in to your Customer Area with your company-level account.
- Go to Developers > Additional data.
- Under Payment, select Recurring details.
Create a token
To create a token, include in your initial /payments request:
- shopperReference: Your unique identifier for the shopper
- shopperInteraction: Ecommerce
- recurringProcessingModel: Subscription or UnscheduledCardOnFile
- storePaymentMethod: true
- shopperEmail: Required when making a zero-value authorization request with
amount.value: 0. Don't include this parameter if the request is not for a zero-value authorization.
When the payment has been settled, you receive a webhook containing:
pspReferenceof the initial payment.
pspReference: This is the token for making later recurring payments for this shopper.
Make a payment with a token
To make a later, recurring payment with the token, include in your /payments request:
pspReferencefrom the RECURRING_CONTRACT.
You can also get this value by using the /listRecurringDetails endpoint.
shopperReference: The unique shopper identifier that you specified when creating the token.
recurringProcessingModel: Subscription or UnscheduledCardOnFile.
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:
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.