PayPal Integration Manual

Here we describe how to integrate your platform with the Adyen Payment System and with PayPal. This allows you to easily implement a broader range of payment solutions to offer your clients a seamless and enjoyable shopping experience.

We also offer a shortcut of integration, check Express checkout shortcut.

Audience

This manual targets developers who integrate merchants' systems with the Adyen payment platform.

In particular, we focus on configuring your PayPal account to include this payment option in your Adyen payment methods, and testing it to make sure the integration works as expected.

While integrating the Adyen platform of products and services with a third-party system, we strongly recommend you follow defensive programming best practices.
This means, for example, that system-automated decisions should have defaulted to non-delivery of products and services:
  • Your system should deliver products and services only after receiving an explicit authorisation response to a corresponding payment request.
  • Your system should not deliver any products or services when it does not receive any explicit response.

Feedback

We strive to provide you with clear, concise, and complete documentation. We are committed to improving it continuously to make it accessible and easy to understand.

We appreciate your comments, and we'd love to hear your voice: drop us a line and share your thoughts with us!

  Adyen Support Team

Paypal last update

Version

Date

Changes

4.2.2 2016-11-22

Updated PayPal account setup  to reflect the username change from "paypal_api1.adyen.com" to "paypal_api2.adyen.com".

Version

Date

Changes

4.2.2 2016-11-22 Updated PayPal account setup to reflect the username change from "paypal_api1.adyen.com" to "paypal_api2.adyen.com".
4.2.1 2016-04-21

Added information about Partial captures.

4.2 2016-03-24

Added information Express checkout shortcut.

4.1.1

2015-11-12

Added information on MASSPAY.

4.1 2015-07-17

4.0

2015-02-06

  • Documentation migration from PDF to web-based online deliverable as main distributable asset.
  • Versioning: version reset and adoption of semantic versioning as per v. 4.0.0.
  • Manual redesign to improve readability, navigation, content search.

2.04

2015-03-06

Updated: screenshots.

2.03

2014-12-15

Minor changes to screenshots.

2.02

2014-12-03

Updated API Access level exceptions in certain countries.

2.01

2014-12-02

Updated PayPal recurring information.

2.0

2014-11-27

  • Upgraded to latest Adyen Manuals' formatting and renewed screenshots (based on latest PayPal website to date)
  • Added information regarding PayPal Sandbox setup.

1.48

2011-11-22

Added information about PayPal recurring limits.

1.47

2011-10-27

  • Added information about additional reporting abilities.
  • Added requirement for PayPal Merchant Account ID.

1.46

2011-08-25

  • Changed PayPal screenshots.
  • Added details about recurring capabilities.

1.45

2011-08-05

Added iFrame section.

1.41

2011-03-02

Changed PayPal screenshots.

1.40

2011-01-09

Changed PayPal screenshots.

1.35

2010-12-28

Added information about Payment Completion part.

1.30

2010-11-30

Removed Payment Completion part.

1.21

2010-07-29

  • Added audience section.
  • Manual reviewed for English and layout consistency.

1.20

2010-06-25

Added Refund Option section.

PayPal integration prerequisites

Before you start integrating PayPal payments, take a moment to go through the following prerequisites.

Accounts

Make sure you set up and properly configured these accounts:

  • A valid merchant account
  • A valid PayPal account
  • A PayPal Business sandbox test account

Link your PayPal and Adyen accounts

To link your PayPal account(s) to your Adyen merchant account, we need to receive the following details from you:

  • The email address of your PayPal account to link it to your live Adyen account.
  • (Optional) The email address of your PayPal Business sandbox test account to link it to your test Adyen account.

PayPal account setup

PayPal's online documentation provides clear descriptions and explanations about how to carry out these tasks:

Grant API permission

In your active, live PayPal account, you need to grant API permissions to the Adyen API, so that we can:

  • Credit payments to your PayPal account.
  • Provide access to extra reporting features.

To set up API permission, do the following:

  • Log in to your PayPal account.
  • Go to Profile | Account Settings.
  • In the My Profile window, select Selling preferences.
  • In the Selling online area, look for the API access row, then click the corresponding Update link.

  • In the API Access window, click the Grant API permission link.
  • In the Add New Third Party Permissions window, go to the Third Party Permission Username field, and enter the following user name:

    paypal_api2.adyen.com

    Starting from 22 Nov 2016, use "paypal_api2.adyen.com" instead of "paypal_api1.adyen.com". If you were using "paypal_api1.adyen.com" before 22 Nov 2016, it was automatically updated by PayPal to "paypal_api2.adyen.com".

  • Click Lookup to generate a list with the available permissions for the specified API.
  • In the API permission list, select the following checkboxes:
    • Use Express Checkout to process payments.
    • Issue a refund for a specific transaction.
    • Process your customers credit or debit card payments.
    • Authorize and capture your PayPal transactions.
    • Obtain information about a single transaction.
    • Obtain authorization for pre-approved payments and initiate pre-approved transactions.
    • Generate consolidated reports for all accounts.
      (In some countries, you might get an error message informing you that the feature is not available in the country where you have your PayPal account. In this case, uncheck/deselect this option.)
    • Use Express Checkout to process mobile payments.
      (If you do not support or plan to support mobile payments, leave this option unchecked.)
  • Click Add.

  • After completing this task, contact our support team to notify the PayPal account email address you want to use for your PayPal payment integration.

Paypal- MASSPAY

For using MASSPAY, you need to provide the following permissions additionally for the MassPay setup:

  • Obtain your PayPal account balance.
  • Initiate transactions to multiple recipients in a single batch.

This feature is not available for every merchant, contact Adyen Support Team for further information.

PayPal refund period

By default, PayPal accounts limit the refund time period to 60 days. Longer refund periods may apply for certain accounts. When this is the case, the extended refund period needs to be configured accordingly in your Adyen merchant account as well: contact our support team to make sure the refund period in your Adyen merchant account reflects the one in your linked PayPal account.

Recurring payments

By default, recurring payments are disabled in Paypal. You can enable this feature during the third-party API permission setup.

PayPal's online documentation provides clear descriptions and explanations about how to carry out this task:

Add recurring payment management

Follow the steps described in the third-party API permission setup section.

In the Available Permission list, select the following checkboxes:

  • Charge an existing customer based on a prior transaction.
  • Create and manage Recurring Payments.

After enabling recurring payments in your PayPal account, you can start executing recurring transactions programmatically through the Adyen platform by passing the recurringDetailReference parameter for each subsequent recurring transaction via the  API.

You can configure your PayPal account to remember how often a shopper should be charged (frequency options for recurring payments), without making API calls to the merchant each time it needs to check the value. For further details, refer to PayPal's Reference Transactions document.

However, we do not recommend Adyen merchants to enable this feature because recurring transactions initiated by PayPal independently of the Adyen platform are not shown in the Adyen backoffice.

Sandbox account setup

If you have a PayPal Sandbox test account, you can set it up in the Adyen test environment. The setup is very similar to granting the Adyen API access to a live PayPal account. With a PayPal Sandbox test account, you need to make sure that the Adyen test API user can access it to carry out the payment operations you want to test.

 

PayPal Sandbox Business and Personal accounts

PayPal Sandbox accounts come in two flavours:

  • Business: represents a merchant's PayPal account in a transaction.
  • Personal: represents a shopper's PayPal account in a transaction.

Follow PayPal's instructions to create your Sandbox Business and Personal accounts.

Automatic creation of your first Sandbox Business and Sandbox Personal test accounts

  • PayPal automatically creates your first Sandbox Business test account by cloning your live account and by appending the -facilitator suffix to your email name.
  • PayPal automatically creates your first Sandbox Personal test account by cloning your live account and by appending the -buyer suffix to your email name.

PayPal Sandbox Business account setup

If you have a PayPal Sandbox  Business test account, you can set it up to use it as a test merchant account in the Adyen test environment. The setup is very similar to granting the Adyen API access to a live PayPal account. With a PayPal Sandbox test account, you need to make sure that the Adyen test API user can access it to carry out the payment operation you want to test.

When you set up your Sandbox  Business account , you need to link it to your Adyen test merchant account to test payments in the Adyen test environment.

Make sure you are logged in with the created Facilitator/Business account, not as the user who setup the sandbox accounts, on https://sandbox.paypal.com/ while adding these API rights.

To do so, follow the steps described in the third-party API permission setup section, and use the values listed below.

  • In the Add New Third Party Permissions window, go to the Third Party Permission Username field, and instead of entering paypal_api2.adyen.com, input the following user name:

    sell1_1287491142_biz_api1.adyen.com

  1. Click Lookup to generate a list with the available permissions for the specified API.
  2. In the API permission list, select the following checkboxes:
    1. Use Express Checkout to process payments.
    2. Issue a refund for a specific transaction.
    3. Process your shopper's credit or debit card payments.
    4. Authorize and capture your PayPal transactions.
    5. Obtain information about a single transaction.
    6. Obtain authorization for pre-approved payments and initiate pre-approved transactions.
    7. Generate consolidated reports for all accounts.
      (In some countries, you might get an error message informing you that the feature is not available in the country where you have your PayPal account. In this case, uncheck/deselect this option.)
    8. Use Express Checkout to process mobile payments.
      (If you do not support or plan to support mobile payments, leave this option unchecked.)
  3. Click Add. 

  • After completing this task, contact our support team to notify the PayPal Sandbox Business test account email address you want to use for your PayPal test payment integration.

See also

Test payments

Adyen offers a generic PayPal test shopper email and password. You can use these credentials to carry out PayPal Sandbox test payments in the Adyen test environment. 

Alternatively, you can use the PayPal Sandbox personal shopper email addresses you created in your PayPal developer environment. The main advantage of using your own shopper email is that you can keep track of your test payments in the PayPal sandbox at a shopper level.

Paypal negative testing

Positive testing

By default, the Sandbox mimics the live PayPal site as closely as possible. To reproduce specific error conditions, your test cases need to recreate the exact scenarios that trigger those errors. Therefore, in its default setting the Sandbox is a positive test environment where you can test your system or application as it follows an error-free path.

The purpose of positive testing is to verify that the system or application under test works as expected.

Negative testing

Enter negative testing, a testing methodology that lets you force flows through the specific error conditions you want to test.

The purpose of negative testing is to verify that the system or application under test can gracefully handle situations that break the happy flow. For example, negative testing checks that the system or application under test can handle errors by throwing exceptions and by returning descriptive error messages that can help understand and solve the problem, instead of crashing.

Run negative tests in the Sandbox

By default, negative testing is disabled. To enable it, go through the following steps:

  • Log in to your Paypal developer account.
  • On your account landing page, click Dashboard.
  • In the sidebar on the left, under Sandbox, click Accounts.
  • In the account overview list, expand the desired account you want to edit, then click Profile.

  • In the Account details popup dialog window, select the Settings tab.
  • On the Settings tab, set Negative testing to On.
  • Click Close.

This sets the Sandbox to the negative testing state for transactions. Without this configuration, the Sandbox does not raise error conditions.

After enabling negative testing for a Sandbox profile, your account expects transaction amounts to be handled as error codes.

To go back to normal positive testing, set Negative testing to Off.

Negative test examples

The type of error you want to trigger defines the actual value you need to pass.
For example, you can use the 10606 value to trigger a Transaction rejected error.

To trigger an error condition on an amount-related field, specify an error code value as a minor unit, as you would normally do for a standard payment.

On our test platform, the following error codes are mapped to the corresponding refusal reasons:

Error code / Amount

Description
10001 Internal error.
10002 Authentication/Authorization failed.
10069 Payment refused due to risk; user notification necessary.
10201 Agreement cancelled.
10204 Denied.
10207 Retry.
10411 This express checkout session has expired.
10417 Transaction cannot complete.
10422 Customer must choose new funding sources.
10445 This transaction cannot be processed at this time. Please try again later.
10485 Payment not authorized.
10486 This transaction could not be completed.

10606

Transaction rejected, please contact the buyer. Buyer cannot pay.

10736 Shipping address invalid city state postal code.
11084 User does not have a good funding source with which to pay.
11607 Duplicate request for specified Message Submission ID.
13113 Buyer cannot pay.
13122 Transaction refused.

There are more errors codes and refusal reasons on our live platform, but not all of them are mapped in the test environment.

The mapped error set above allows carrying out targeted negative testing on PayPal transactions in our test environment to verify that your system can handle incomplete or erroneous transactions in a live environment.

PayPal in an iFrame

We do not recommend displaying the PayPal page in an iFrame. iFramed content is handled like third-party content relative to the parent window. If the web browser is configured to allow third-party cookies, it is possible to break out of the iFrame when redirecting to an external site from within the iFrame.

However, default security settings – usually, medium security level – in commonly used browsers like Internet Explorer and Safari block third-party cookies, which results in a security warning or an error page being displayed: 

PayPal security error message

PayPal pages lack a P3P header, which defines the data the web site stores or requests when it tries to set a cookie on the client web browser. The cookie content is compared against the web browser security settings. Based on the P3P header definition and the browser security settings, the cookie is accepted or rejected.

Cookies can be completely disabled in web browsers. With this setting, payment methods like PayPal and iDEAL do not work anymore.

Payment completion

After completing a payment, shoppers are redirected to a default Adyen result page. 

PayPal handles incomplete or refused payments in a custom way. Most refused payments may return a result URL whose authorisation result URL parameter value is set to PENDING. This is because PayPal may offer shoppers the option to retry the payment. If the new attempt is successful, you receive a standard payment authorisation notification with eventCodeAUTHORISATION and success = true.

Partial captures

Refunds for Paypal can be made via modification as described in the API manual. In case of multiple partial captures the references of the refund modification request is used to identify the reference of the specific capture request to be refunded. Therefore, unknown references in the refund modification leads to a failure.  

Partial captures are not enabled by default, contact Adyen Support for more information.

Bank transfers

If your PayPal account allows it, shoppers can pay via bank transfer to PayPal. In this case, a payment authorisation notification takes about 5 to 7 business days before it is received.

Allowing bank transfers can result in never receiving refused payment notifications: when an order is initiated through the PayPal web site, you need to accept it to if you want to process it and complete the transaction.

If you do not accept an order from a shopper and/or do not take any action to accept and finalize an order, it is cancelled automatically after 29 days.
The funds are then released, and they are credited back to the shopper's PayPal account.

Shopper statements

Some acquirers, including PayPal, support variable shopper statements. To submit variable shopper statements, you can include and set the shopperStatement field in your payment request to enhance and customize the shopper experience.

If you do not include a shopperStatement in your payment request, PayPal populates the statement text field with the merchantreference data.

Reporting

To review information on your PayPal settlements in the Adyen system, browse for the External Settlement Report With Info (WIP) under Reports | Scheduled Reports. The report is the same as our usual settlement reports available at Merchant level; however, the external settlement report is available only at company level.

Express checkout shortcut

Paypal express checkout shortcut is an easier way for customers to submit a payment transaction by pre-filling billing and shipping details for them. 

Defensive Programming

While integrating the Adyen platform of products and services with a third-party system, we strongly recommend you follow defensive programming best practices.
This means, for example, that system-automated decisions should have defaulted to non-delivery of products and services:

  • Your system should deliver products and services only after receiving an explicit authorisation response to a corresponding payment request.
  • Your system should not deliver any products or services when it does not receive any explicit response.

Prerequisites

Ensure the following configurations and set up for your merchant account before implementing the PayPal Express Checkout integration:

  • Adyen HPP integration.
  • A result URL, i.e a return URL corresponding to the order update or order review page, following a successful PayPal Express Checkout payment authorisation.

You can provide the URL as the resultURL parameter value along with your HPP request when you initiate the payment, or you can define it in the skin configuration. 

  • Supply the BrandCode ‘paypal_ecs’ and POST the form to the live.adyen.com/hpp/details.shtml endpoint.

  • PayPal Express Checkout needs to be configured on your account. This is a separate configuration from the regular PayPal payment flow. Contact our support team  to set up PayPal Express Checkout.

Test and live URL endpoints

Adyen Customer Area (CA)

https://ca-test.adyen.com/

Hosted Payment Pages (Skip Details):

https://test.adyen.com/hpp/skipDetails.shtml

Authorise API call

https://pal-test.adyen.com/pal/servlet/Payment/v25/authorise

Adyen Customer Area (CA)

https://ca-live.adyen.com/

Hosted Payment Pages (Skip Details):

https://live.adyen.com/hpp/skipDetails.shtml

Authorise API call

https://pal-live.adyen.com/pal/servlet/Payment/v25/authorise

PayPal Express Checkout flow

The PayPal Express Checkout flow:

  1. The shopper initiates a PayPal checkout payment transaction on the merchant's site.
  2. The shopper is redirected to PayPal through Adyen's HPP.
  3. On PayPal, the shopper can login with their PayPal credentials; they can choose a shipping address from the available ones, the preferred card for the payment, and authorise the payment.
  4. The shopper is redirected to the order review page on the merchant's site, where they can review and update the order. Adyen fetches all the necessary order data from PayPal and sends it to the merchant, along with a payment token.
  5. After the shopper confirms their order on the merchant's site, the merchant sends a payment authorisation request to Adyen's payment API. They need to include in the API call the payment token they received from Adyen.
  6. Adyen processes the request, sends it to PayPal, and sends the response to the merchant.
  7. The payment transaction result is displayed on the merchant's site order confirmation page.

 

Initiating the payment

On the merchant's site, the shopper initiates a payment request when they submit order data for further processing. They usually enter the data in an order form page, which they subsequently submit.
On submitting, the merchant sends the information to the Adyen HPP implementation with an HTTP POST message as:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1- strict.dtd">
<html data-brandcode="paypal_ecs" data-page-model="multi-page" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<body>
    <form method="post" action="https://live.adyen.com/hpp/skipDetails.shtml" id="adyenForm" name="adyenForm" onsubmit="return formValidate(this ,'default' );" autocomplete="off">
        <input type="hidden" name="merchantSig" value="3iWDU/V5RMtdaiZC4YRIpoX9/v0=" />
        <input type="hidden" name="sessionValidity" value="2015-04-02T09:52:42Z" />
        <input type="hidden" name="merchantAccount" value="TestMerchant" />
        <input type="hidden" name="paymentAmount" value="8650" />
        <input type="hidden" name="currencyCode" value="EUR" />
        <input type="hidden" name="skinCode" value="aF563qQs" />
        <input type="hidden" name="merchantReference" value="TMRef1234" />
        <input type="hidden" name="brandCode" value="paypal_ecs" />
        <input type="hidden" name="shipBeforeDate" value="2017-04-08" />
        <input type="submit" name="submitButton" value="{PayPal-branded pay button}" />
    </form>
</body>
</html>


Redirecting to PayPal

The submitted order form on the merchant's site sends the data to the Adyen HPP page specified in the action attribute of the form element:

https://test.adyen.com/hpp/details.shtml
  • The paypal_ecs BrandCode value in the backoffice sets the corresponding brandCode attribute value on the HTML page.

From here, the data is redirected to the PayPal site, where Express Checkout is initiated.
A redirect takes the shopper from the merchant's site to the PayPal login page. After logging in with their PayPal credentials, the shopper can perform the following actions:

  1. Choose a shipping address from the available ones in their PayPal account or add a new shipping address
  2. Choose the preferred card for the payment.
  3. Add a new card.
  4. Authorise the payment.

Authorising the payment

If the payment is authorised on PayPal, the authResult URL parameter Adyen returns is authResult=PENDING.

You can send us a payment authorisation request to complete the PayPal Express Checkout transaction.

The payment request authorisation is an authorise call to our payment API.

To send API calls, you need to provide authentication credentials (username/password). You configure these details in the library you use for server-to-server communication with the Adyen platform.

The username is automatically retrieved when you initiate a payment through Adyen HPP, and it needs to match the username value you specify when you authenticate to send your authorise API call.

The default, the predefined username is ws@Company.[YourCompanyAccount]. You set the corresponding password in the Adyen Customer Area (CA) of the backoffice, under Settings -->Users.

The authorise API call you make at this point in the flow should include:

  • The payment.token HTTP POST return field
  • The paypal_ecs brandCode value that you passed with the initial HTTP POST message to Adyen HPP when you initiated the payment.

Including the payment token

In the PayPal Express checkout flow, the payment request authorise API call you make to Adyen always should include the payment token you receive from us in the payment.token HTTP POST return field.
You include the payment token as a key/value pair entry in the additionalData container object, as shown in this example:

<pay:additionalData> 
   <pay:entry> 
      <pay:key xsi:type="xsd:string">payment.token</pay:key> 
      <pay:value xsi:type="xsd:string">eyJkYXRhIjoiYWR5ZW5ocHAwXzFfMSRoWXVGV0tkTUFEN25aRnlYSmRtRHJsYUZVcGpaTFYramxK 
         aVBlNHlnTEZmbjhzWkR4aVYxRVJjblQxdnZHNVwvb2xQZ1B3TnkwT2RcLzE5NDRsY0V1c2NNZjJc 
         L3V6RkN4M2duYWFDTGFHSU9ueE9heFVjSmQ3SFlyTDRoaGFHVGhySnN3eTl3aWJYbTU2S2NuZEdm 
         RXphUVV5VG16Q0NBdk93NnFZeTAzRHJCQ2RLS055bWpTZTBUSmExZ291UWJndUZYMnMxRXgwdzho 
         VXJ4OUNBWW5qMXVFOHljdTVreUdUQkZpb0Vsa1wvdWt1ZmNyWUdZdkd2YW1PazhQMnViaUhUMkkz 
         dWQ0V0JPN0JFaGNqdXRhOHpcLzNiNWFRTzJEcnlKaXM2N1NRRFhxbFI3QUxKYW9CblQ4bFNXakl4 
         c3lsODV6XC9cL1F6dXpvSFwvcitNWW9QSTJrUG04dz09JGlSOE5nZmY5QjEzeHZXQ0VZTjJIZjd4 
         TXFXRUpRVWVuckxcL1hheFZcLzFSMGJoTExvOGtscWxsYldyVTZLWUlnQU1Wa3hnUzdsOWJXQWZ2 
         NHVQY3NHMzBMWkE1bURkTkhKNVNTUlR1RFgrR1wvNFN5VE5VK0dzUno1QTNZQmRJYUwzU1Z4OEI4 
         WThLWXRkb1RnTGlaM1hhNktPNlg3ZVFSbm1QdU5LMGR0K3ZjS0V5aE1NeSt0SHErZ1Y2QTN5VTRN 
         dkVab0xHeTk0bTVRaklldzkrVnc3RjFcL3NpZW1seTkrZDBXUE5TNHlLVnVnZVZaWk9FSDdyWG9K 
         ZDFaN1JlQjJUak9SK3I0MVB2TXRnM05tbThPTFB0U1E3STA2UGxYVThjRUZXUHpDckg1WXM3N0o5 
         QXdlbDJzVGFhNzRja09YSDNZTENadVF6ZzRxbXFidVVBS0pSTmlveXJMQWxzSThcL1VRQlwvRlwv 
         SENcL1FOSzNXbXIzY1ArQ1Z4SnZ6c0U1ZWg2akxvdlYwU2YrK3QyRWdMVWFDdkRRRmh4MmJhd1kz 
         SklHQzJhMitYaDFoVXBpNFN4NDFlSHlcL1A4QkcrWUdJZ2Uzakt5aTVWTURBMTh1eEx5MnVySTBr 
         TVwvVnl2dXBuNWhWQ3ljWm9qQ2pQUjNPVnFhVTdMaWVzR0t6UEl6SlwvRmo1a3ZMVUVqY3VpS2pI 
         YUx5b0QyVVVKYmdSR1NiK1BpcE9ISDRuYnF3RVI4dkVFVUJcL3VSY3RscXJYQ0E4cjJJUWdESzBK 
         QWI4SkZhVGRqeXJQRTBDZ2pxK01lUFZ3RkJGZVNjaE56TTdpVWRqSkhycGc1UGpVaGdrNXFIS0NY 
         K1phd2xtdFlGZDBBdkZBdkYxdzlKR2M3Y294SVlxMlJaaUw5cFFOcHk4c2F3akNRaVZkK1RLTnVt 
         S2cxZHd2b0pPc0xoZ0w5RlpaenZqUjhWbWZIU1lETmp0ZFEzTitDbEZjVnI4VVdZdkgxZ2c3NjQy 
         S1UwVFNqa3B6WDQ1bHVDN2JKVkE4RDJEUGx3UGdwREpKYld3ZjVBd0RKNk5EK0tuNUIwUUNMS01P 
         TWxLUGpXXC9YSUxjWERtMWxpRnora0puVDVYN2lESCtcL29mVG9qUVwvT0hUUlJxNTMrRnltaERZ 
         PSIsInZlcnNpb24iOiJhZHllbi1lY192MSJ9
      </pay:value> 
   </pay:entry> 
</pay:additionalData>

The additionalData object is described in the API manual.

Include the paypal_ecs brandCode

The authorise API call needs to include also the paypal_ecs value that you passed in the brandCode field with the initial HTTP POST message to Adyen HPP when you initiated the payment:

... 
 <form id="adyenForm" name="adyenForm" onsubmit="return formValidate(this ,'default' );" autocomplete="off" method="post" action="https://live.adyen.com/hpp/skipDetails.shtml"> 
 ... 
 <input type="hidden" value="paypal_ecs" name="brandCode"> 
 ... 
 </form> 
 ...

In the payment request authorise API call, you need to pass the paypal_ecs value in the selectedBrand field:

... 
 <pay:selectedBrand>paypal_ecs</pay:selectedBrand> 
 ...

Authorise API call example

The following example shows an authorise API call using SOAP.

  • The payment.token key/value pair entry in the additionalData object holds the payment token you need to return to us.
  • The selectedBrand field holds the paypal_ecs value you originally sent with the brandCode field to Adyen HPP when you initiated the payment.

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:com="http://common.services.adyen.com" xmlns:pay="http://payment.services.adyen.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Header />
   <soapenv:Body>
      <pay:authorise>
         <pay:paymentRequest>
            <pay:additionalData>
               <pay:entry>
                  <pay:key xsi:type="xsd:string">payment.token</pay:key>
                  <pay:value xsi:type="xsd:string">eyJkYXRhIjoiYWR5ZW5ocHAwXzFfMSRoWXVGV0tkTUFEN25aRnlYSmRtRHJsYUZVcGpaTFYramxK 
 aVBlNHlnTEZmbjhzWkR4aVYxRVJjblQxdnZHNVwvb2xQZ1B3TnkwT2RcLzE5NDRsY0V1c2NNZjJc 
 L3V6RkN4M2duYWFDTGFHSU9ueE9heFVjSmQ3SFlyTDRoaGFHVGhySnN3eTl3aWJYbTU2S2NuZEdm 
 RXphUVV5VG16Q0NBdk93NnFZeTAzRHJCQ2RLS055bWpTZTBUSmExZ291UWJndUZYMnMxRXgwdzho 
 VXJ4OUNBWW5qMXVFOHljdTVreUdUQkZpb0Vsa1wvdWt1ZmNyWUdZdkd2YW1PazhQMnViaUhUMkkz 
 dWQ0V0JPN0JFaGNqdXRhOHpcLzNiNWFRTzJEcnlKaXM2N1NRRFhxbFI3QUxKYW9CblQ4bFNXakl4 
 c3lsODV6XC9cL1F6dXpvSFwvcitNWW9QSTJrUG04dz09JGlSOE5nZmY5QjEzeHZXQ0VZTjJIZjd4 
 TXFXRUpRVWVuckxcL1hheFZcLzFSMGJoTExvOGtscWxsYldyVTZLWUlnQU1Wa3hnUzdsOWJXQWZ2 
 NHVQY3NHMzBMWkE1bURkTkhKNVNTUlR1RFgrR1wvNFN5VE5VK0dzUno1QTNZQmRJYUwzU1Z4OEI4 
 WThLWXRkb1RnTGlaM1hhNktPNlg3ZVFSbm1QdU5LMGR0K3ZjS0V5aE1NeSt0SHErZ1Y2QTN5VTRN 
 dkVab0xHeTk0bTVRaklldzkrVnc3RjFcL3NpZW1seTkrZDBXUE5TNHlLVnVnZVZaWk9FSDdyWG9K 
 ZDFaN1JlQjJUak9SK3I0MVB2TXRnM05tbThPTFB0U1E3STA2UGxYVThjRUZXUHpDckg1WXM3N0o5 
 QXdlbDJzVGFhNzRja09YSDNZTENadVF6ZzRxbXFidVVBS0pSTmlveXJMQWxzSThcL1VRQlwvRlwv 
 SENcL1FOSzNXbXIzY1ArQ1Z4SnZ6c0U1ZWg2akxvdlYwU2YrK3QyRWdMVWFDdkRRRmh4MmJhd1kz 
 SklHQzJhMitYaDFoVXBpNFN4NDFlSHlcL1A4QkcrWUdJZ2Uzakt5aTVWTURBMTh1eEx5MnVySTBr 
 TVwvVnl2dXBuNWhWQ3ljWm9qQ2pQUjNPVnFhVTdMaWVzR0t6UEl6SlwvRmo1a3ZMVUVqY3VpS2pI 
 YUx5b0QyVVVKYmdSR1NiK1BpcE9ISDRuYnF3RVI4dkVFVUJcL3VSY3RscXJYQ0E4cjJJUWdESzBK 
 QWI4SkZhVGRqeXJQRTBDZ2pxK01lUFZ3RkJGZVNjaE56TTdpVWRqSkhycGc1UGpVaGdrNXFIS0NY 
 K1phd2xtdFlGZDBBdkZBdkYxdzlKR2M3Y294SVlxMlJaaUw5cFFOcHk4c2F3akNRaVZkK1RLTnVt 
 S2cxZHd2b0pPc0xoZ0w5RlpaenZqUjhWbWZIU1lETmp0ZFEzTitDbEZjVnI4VVdZdkgxZ2c3NjQy 
 S1UwVFNqa3B6WDQ1bHVDN2JKVkE4RDJEUGx3UGdwREpKYld3ZjVBd0RKNk5EK0tuNUIwUUNMS01P 
 TWxLUGpXXC9YSUxjWERtMWxpRnora0puVDVYN2lESCtcL29mVG9qUVwvT0hUUlJxNTMrRnltaERZ 
 PSIsInZlcnNpb24iOiJhZHllbi1lY192MSJ9</pay:value>
               </pay:entry>
            </pay:additionalData>
            <pay:amount>
               <com:currency>EUR</com:currency>
               <com:value>600</com:value>
            </pay:amount>
            <pay:browserInfo>
               <com:acceptHeader>text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,/;q=0.5</com:acceptHeader>
               <com:userAgent>Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725 Firefox/2.0.0.6</com:userAgent>
            </pay:browserInfo>
            <pay:billingAddress>
               <com:city>Amsterdam</com:city>
               <com:country>NL</com:country>
               <com:houseNumberOrName>1</com:houseNumberOrName>
               <com:postalCode>1000 AB</com:postalCode>
               <com:stateOrProvince />
               <com:street>Main St.</com:street>
               <pay:holderName>Joe Black</pay:holderName>
            </pay:billingAddress>
            <pay:deliveryAddress>
               <com:city>Utrecht</com:city>
               <com:country>NL</com:country>
               <com:houseNumberOrName>2</com:houseNumberOrName>
               <com:postalCode>9999 XY</com:postalCode>
               <com:stateOrProvince />
               <com:street>Second St.</com:street>
            </pay:deliveryAddress>
            <pay:selectedBrand>paypal_ecs</pay:selectedBrand>
            <pay:merchantAccount>TestMerchant</pay:merchantAccount>
            <pay:reference>ref123456</pay:reference>
            <pay:shopperEmail>testmerchant@example.com</pay:shopperEmail>
            <pay:shopperName>
               <com:firstName>Mary</com:firstName>
               <com:gender>UNKNOWN</com:gender>
               <com:infix />
               <com:lastName>Lou</com:lastName>
            </pay:shopperName>
            <pay:shopperReference>shopper123456</pay:shopperReference>
            <pay:shopperStatement>ADIDAS</pay:shopperStatement>
         </pay:paymentRequest>
      </pay:authorise>
   </soapenv:Body>
</soapenv:Envelope>

Redirecting to the merchant's return URL

After authorising the payment, PayPal sends the payment data to Adyen.

Adyen then sends an HTTP POST message to the predefined result URL, i.e. the return URL to a specified page on your website. This URL points to an order review page where the shopper can review and update the order, for example by selecting new quantities, or by adding or removing items.

If the shopper updates the order and submits the changes, order recalculation takes place on the merchant's backend; make sure you implement the necessary logic on your end.
The HTTP POST message we send you includes the following details:

  • PayPal Express Checkout payment data for the current transaction.
  • We append to the result URL a number of URL query parameters to provide you with transaction status information.

The authResult URL parameter notifies you about the current transaction status:

  • authResult=PENDING: The shopper authorised the payment on PayPal, the payment data is available. The transaction is in progress. You need to send a payment authorisation request to authorise it.
  • authResult=CANCELLED: The shopper either cancelled or did not successfully authorised the payment on PayPal. The transaction is cancelled.
  • authResult=REFUSED: PayPal refused to initiate the transaction.
  • authResult=ERROR: An error is returned in all other cases.

For further information on the URL query parameters that we return at this point in the flow, refer to the HPP manual.

  • A payment token (payment.token). You need to send back this token with your payment authorisation request.

HTTP POST return fields

After the shopper authorises the payment on PayPal, these are the fields Adyen returns to you:

HTTP POST field

Description

card.holderName

Billing name of the shopper.

billingAddress.street

Street name, as retrieved from the billing address details selected by the shopper on PayPal.

billingAddress.city

City name, as retrieved from the billing address details selected by the shopper on PayPal.

billingAddress.stateOrProvince

State/Region/Province name, if applicable, as retrieved from the billing address details selected by the shopper on PayPal.

.stateOrProvince replaces .state, which is deprecated.

billingAddress.postalCode

ZIP code details, as retrieved from the billing address details selected by the shopper on PayPal.

billingAddress.country

Two-letter ISO 3166-compliant country name, as retrieved from the billing address details selected by the shopper on PayPal.

shopper.firstName

First name/Surname of the shopper, as retrieved from the shipping address details selected by the shopper on PayPal.

shopper.lastName

Last name/Family name of the shopper, as retrieved from the shipping address details selected by the shopper on PayPal.

shopper.telephoneNumber

The contact telephone number, as specified by the shopper on PayPal.

shopperEmail

The contact e-mail address, as specified by the shopper on PayPal.

deliveryAddress.street

Street name, as retrieved from the shipping address details specified by the shopper on PayPal.

deliveryAddress.city

City name, as retrieved from the shipping address details specified by the shopper on PayPal.

deliveryAddress.stateOrProvince

State/Region/Province name, if applicable, as retrieved from the shipping address details specified by the shopper on PayPal.

.stateOrProvince replaces .state, which is deprecated.

deliveryAddress.postalCode

ZIP code details, as retrieved from the shipping address details specified by the shopper on PayPal.

deliveryAddress.country

Country name, as retrieved from the shipping address details specified by the shopper on PayPal.

payment.token

Encrypted payment details. You need to include this payment token in the payment request authorise API call you make to Adyen to complete the transaction.

Paypal recurring payments

Recurring payments are made using the regular recurring functionality, you can find more information in the recurring manual.

Create a recurring contact, you need the Paypal token for this request.

{
   "additionalData":{
      "payment.token":"eyJ2ZXJzaW9uIjoiYWR5ZW4tZWNfdjIiLCJkYXRhIjoiQlFBQkFRQjRlNm14YTdVR09LNGtCZzRIS3B5dThDVXlXUWFzZTVLcjBRWXBXT3Q4aVgrWExCc1FZNVp6MGt6UWdqNkFHQVd4d2JQZHAwK1hYSE1mQ0hSSnNDYlNXWjRhaWtCdW5pVW50ejNZeGlDRzNDRy80NWcrdUVuK1haU3laSjJmVmFMQVZlY2VadkY2Q2FLbmt6UG50dGxxT0JjRlhjZmlhM2FhTWFMRzRhdHJla29iWEFUK0NWUHdXYnhIQlliT1Z0SmEyRU8rU1phdHN2eHUrL21wZG5aVHZDNU1Kam1wYVhLSWhHUTR0MHd1YVZHZzkxNUtOUGxzODg2U280bHlMUVB2SlFoTVZZb2QzMExaNmh2VjhUWFd2OWVOaWwrU0FPaHV2c0QybHY1dlIzQ0FVS3dwanA4SjRoQXNVQnN3clBjVkdHQnRwbC81aVdGWTNySzI0MTBMRUtGQVB3OHJvWEptTk9HQlVJb3liMlFBQU1QeEx4VGZnRWJXbkZzUVBqYW5pYmVoU1FOTnMrNHZYbmlWZ1pxVDJOWm5NTC9rbUpjam9HLythd3RRajAvalpJZlY3SHlDMlN6SVJSWVV6ckEzQ1ZNdmgvbHN2L2g0bFJjL2xRNjBRM2F0ZnhpZjRjL1UrbVpiMGRJcUJYZzdTTkh2akdYQ1JWMmNjTUdVV2pZVG9iQUdrL0JRdWNuQjEvNS9vdWtSOW5GZlkzTDA3djJUcWFtMFdIR3BoeFlUaUVaL25mWkVRbGRGQ29yTlkwd2dtV2xkaUhBd01WTWd5Rng0aTY4YjFURHpXSVlRNFNGUkNRK0k1N1h4SWJ6K2dFWktKR1ZMMVhVTlVHdXY3VVptV2lUdm9Cbnk0cVY1NXdsMlFkNFczYlc3Ylg3Ty9vNmlYUVBEd0Ftdmw2TEpBQzh3TzZJME8zNWFJK29qU1dJWEoySzcwSlYzYnhMeGZLb2EzWFVWOHZ1eHJvZUVObVUxKzU3MGxtaXhnenpvcWNsRC9WSFlJMGtMc1NQK2YvQXRmVTRIdUQ4cFJEVCtwS1o0WFJvckVzakNHY2hlYUpPS0hJOERwcDRKSHViWDdoeTJ0MDVlUDdxOGllZTRGejlqNm9ZY0Z1T1pZWHJCZSt2SEIyUTQzTDhMRGpHbGxoZEkrTzQ3Y085ZEVqNXpGQ2dHWEQ1VGlZcEJvR3lsOGJrTlV2RU1NYjZPdENxTlRtSE9oVnNsL3liU21oWGQ1OHYxamlKb0hSc1BsbzN3eXVyT1FxVnpkRE0vYTZBbEc1UVhpRmVSa2gyT2VaOGJtcXkwZnV2aFRDMmd1bVE2MStBYVh4YXZYQ2trb3FwRVk1bU50RnNMaENkcDVVSTFpT0RmYWRWWXZEVmdXWWJka1BXN25LSTBURWhUWW0vUGI3RExIUnMzMUtzNTVjVFNVNk44TktXbjZVVkFwQjF2RVczeW5NRVJKZ1VWclp6WVIvelVuR1BVbmNKRGtzUzN3VWN0QnNrNEMwb05JK0lkMGZlMFpjR2MwbDBiNm5DOHJFbzQvSHNwU2NNUGtQUVpybk84Vm1sQ1UrY3lzNUVaRHI2eEJIWHZXSUF6OFNmbVNzTXV2akVKREhwdG5GMDJ4aWF6M05PbVFXbkVUM1lLSGdNMWZ3REJiTTlIci9pbm5nbitNc3dQNnJuWUh5NER6QXRMV0JOMFdncWpncHRaWlZpNTRvclIyeEtBbnBWYVhMZzdXaFlCbVY4SmYyMzZ6RTh4MkwrSEVKb3NEWUxXdlAyRVVrcG9CeWFFL09JVy9oRFh1UGJZWk9MbGVVanVQM2ZUMUlqSHMrMU5pRFNFaHhHbWZXQU1kUHJEbkdqMWNRLzM5SlBaMFdPYnRSc0JBSTFobGV4MDhtZmJ3ME9sdzVnZjBrY1RRbkZpOEFCY1pCWHhoYWVEeEFTdXRkSzk1ZEhDWFN5VlVLL3FOeWlNdm5kYXZabC9OYVgwQUdMVFNrYURIakFReUx2RWtudmhSZ3M0YUFjc2VpWkNxWEdiVzA4bHVCV2RGV3BRSzViUnNrYU9NV3pQTXc9PSJ9"
   },
   "brandCode":"paypal_ecs",
   "amount":{
      "value":3541,
      "currency":"USD"
   },
   "reference":"paypaltokencharge1",
   "merchantAccount":"TestMerchant",
   "shopperInteraction":"ContAuth",
   "shopperEmail":"paypal1253@adyen.com",
   "shopperReference":"paypal1253",
   "recurring":{
      "contract":"RECURRING"
   }
}

For subsequent payments, using this billing agreement, use selectedRecurringDetailReference instead of the Paypal token.

{
   "selectedRecurringDetailReference":"8314443424715123",
   "amount":{
      "value":2010,
      "currency":"USD"
   },
   "reference":"paypalrecurringcharge1",
   "merchantAccount":"TestMerchant",
   "shopperInteraction":"ContAuth",
   "shopperEmail":"paypal1253@adyen.com",
   "shopperReference":"paypal1253",
   "recurring":{
      "contract":"RECURRING"
   }
}