The classic Checkout SDK integrations are being phased out
This means we are:
- No longer developing the classic Checkout SDK integration.
- Not accepting new classic Checkout SDK integrations.
You have until March 31, 2024 to migrate.
Payment Type | Shopper journey | Recurring | Refunds | Partial Refunds | Separate captures | Partial Captures | Chargebacks |
---|---|---|---|---|---|---|---|
Wallet | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
You can accept PayPal payments with:
- Our Checkout SDKs.
- Our API integration.
Prerequisites
This page assumes you have already:
- Built a integration.
- Completed the PayPal setup steps.
Set up the PayPal payment method
When you add PayPal to your test Customer Area, you will be asked to provide:
- Your PayPal email address. Use your test PayPal Business email address, for example ending in @business.example.com.
- Your PayPal account ID. Use your test PayPal Merchant ID.
- Whether you want to enable authorisation first, and capture the payment later. By default, payments will be captured immediately after authorisation. Check this box only if payments should not be captured immediately.
Integrate with Checkout SDKs
Our Checkout SDKs support PayPal without any additional configuration.
Verifying payment results works in the same way as it does for SDKs, but you can also set up notifications.
Integrate with API
In this section, we show the API integration steps for PayPal.
Before you begin this section, make sure you read and understand our API Integration guide.
Step 1: Get payment methods
Call /paymentMethods
, specifying the amount
, a countryCode
, and the appropriate channel
.
{
"merchantAccount":"YourMerchantAccount",
"countryCode":"NL",
"amount":{
"currency":"EUR",
"value":1000
},
"channel":"Web"
}
Response
{
"paymentMethods":[
{
"name":"PayPal",
"type":"paypal"
},
...
]
}
Step 2: Redirect shopper
Make a /payments
API call, providing the amount
and a paymentMethod.type
set to paypal. Also provide a returnUrl
, which the shopper will be redirected to after they complete the payment.
If the payment will be the first in a series of recurring payments, also include:
shopperReference
: your unique ID for the shopper (minimum length three characters).paymentMethod.storeDetails
set to true.shopperEmail
: the email address of the shopper.
{
"merchantAccount": "YourMerchantAccount",
"amount": {
"currency": "EUR",
"value": 1000
},
"reference": "Your order number",
"paymentMethod": {
"type": "paypal"
},
"returnUrl": "https://your-company.com/..."
}
This returns the /payments
response which contains the redirect.url
. Redirect the shopper to this address so they can verify the payment with PayPal.
{
"resultCode":"RedirectShopper",
"details":[
{
"key":"payload",
"type":"text"
}
],
"paymentData":"sdfsdf...",
"redirect":{
"method":"GET",
"url":"https://test.adyen.com/hpp/redirectPayPal.shtml?brandCode=paypal¤cyCode=EUR&merchantAccount..."
}
}
Step 3: Handle redirect
After the shopper has completed the payment, they return back to the returnUrl
you specified in the /payments
call. This URL is appended with a payload
query parameter which you will use to verify the payment result. If any other parameters are appended, ignore them.
https://your-company.com/?payload=sdfsdf...&type=complete&resultCode=authorised
Step 4: Present payment result
Finalize the payment and present the result to the shopper.
-
URL decode the
payload
and submit it in a POST request to the /payments/details endpoint.{ "details":{ "payload":"sdfsdfsdf..." } }
The response contains a
pspReference
, which is our unique identifier for this payment, and aresultCode
.If you were tokenizing the payment details, the response also contains a
recurringDetailReference
, which is the token for the shopper's details. -
Use the
resultCode
from the/payments/details
endpoint to present first. You should generically handle theresultCode
as specified in Payment Result codes.
PayPal result codes
The resultCode
values you can receive for PayPal are:
- Authorised: The payment was successful. You will receive the funds in 3 days.
- Cancelled: The shopper canceled the payment while on the PayPal website. Request them to reselect a new payment method.
- Refused: The payment was refused by the shopper's bank.
Webhooks
Webhooks inform you of important events related to your account.
To inform you of the outcome of a payment, we send you a webhook with:
eventCode
: AUTHORISATION.pspReference
: Adyen's unique reference associated with the payment request.-
success
: Indicates the outcome of the payment. Possible values:- true: The payment was authorised.
- false: The payment failed.
AUTHORISATION is just one of the events that trigger a webhook. For more information, see Webhooks.
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.
Make a recurring PayPal payment
Adyen can not enable recurring payments on your PayPal account. To enable recurring payments for PayPal:
- Contact PayPal Support to enable reference transactions on your seller account.
- Enable the recurring permission on your PayPal account. Follow the steps described in the third-party API permission setup section.
- Send a payment request to the Adyen payments platform for PayPal with the parameter
recurringContract
set to the value RECURRING.
Set up PayPal Seller Protection
If you're enrolled in the PayPal Seller Protection program, contact our Support Team to set this up for your Adyen integration.
Once you're set up, submit the following fields with a payment: