Direct Support Site

Results for

icon-search-large No search results yet
Enter your search query above
Page topics

Additional information

To offer this payment method to your customers, make sure to

  • Sign an acquiring contract with PayPal and activate the payment method in your Back Office. We are happy to assist you.
  • Create PayPal test / live accounts and link them to our platform.
  • Set up your PayPal account.
  • Configure the payment method in your Direct Back Office.

Check out the following chapters to get all set!

Create PayPal test/live accounts

Both our and PayPal's test environment offer you to test your integration before going live.
Linking your Direct test account to the PayPal Sandbox with dedicated test credentials allow you to stage scenarios in a safe and realistic way. Create your test account on our platform and learn here how to set up the PayPal Sandbox for end-to-end testing.

Once you are done testing, create your live account on our platform and your PayPal live account and configure them both.

Make sure to switch to our LIVE URL endpoint as soon as you have finalised your tests.
Configure PayPal account

To link your Direct account with your PayPal (Business) account, you need to allow PayPal to access your API user. To do so, follow these steps:

  1. Login to your Paypal account with your PayPal Business e-mail address in either the sandbox or live environment
  2. Enter the following credentials in field "Third Party Permission Username". Click then on "Lookup":
    Environment API username
  3. Tick the following boxes and click then "Add":
    • "Use Express Checkout to process payments".
    • "Issue a refund for a specific transaction".
    • "Authorize and capture your PayPal transactions".
    • "Obtain information about a single transaction".
    • "Search your transactions for items that match specific criteria and display the results".

Finally, configure your Direct Back Office.

Configure Back Office
  1. Login to your Back Office. Go to Configuration > Payment methods > PayPal > Contract data.
  2. In "PayPal account e-mail address", enter your PayPal merchant e-mail address.
  3. (Optional) In "Express checkout options", flag "Display review page for ExpressCheckout Shortcut" and/or "Display review page for ExpressCheckout Mark". Use these options to redirect your customers back to your website for a final review before completing the payment.


      • Configure first your PayPal account and then your Direct Back Office. Otherwise, the Back Office rejects your configuration by displaying this error message: "Error test merchant config for PayPal ExpressCheckout, probably API access to PayPal merchant account was not authorized by the Merchant".
      • Transactions in our TEST environment are not visible in your Sandbox PayPal account
Integration: PayPal Express Checkout

There are 2 integrations of PayPal Express Checkout:

  • Express Checkout Shortcut (ECS)
  • Express Checkout Mark (ECM)

For each integration the transactions can be processed in:

  • Direct Sale
  • Authorization + Data Capture
Express Checkout Shortcut

The ECS integration allows faster checkout as the additional data, like shipping address, can be provided by the PayPal account.
When the consumer wants to pay with ECS he is immediately redirected to PayPal where he can review his order. (For better user experience it is recommended to send the line item details) Once reviewed, the consumer can either complete the purchase or he can return to the merchant for final confirmation of the order. This option can be configured by the merchant in the Payment Method configuration in the Back Office, see PayPal Account Configuration.
In the ECS flow, it is requested by PayPal not to send them a shipping address. Note that when you receive the address back in the response, the street and house number will never be in separate fields as we receive them back in the same field from PayPal. 
You must ensure you inform Direct if the goods to be delivered are digital or physical goods. This will determine the need for shipping.

Express Checkout Mark

The ECM integration is the standard PayPal checkout flow. The checkout is done on the merchant website and the consumer can choose PayPal in the merchant payment methods options. The consumer is redirected to the PayPal review page for final review.
In the ECM flow, the merchant can also request for the consumer to be redirected to its confirmation page after review on PayPal side. This option can be configured by the merchant in the Payment Method configuration in the Back Office, see PayPal Account Configuration.
The merchant must ensure the shipping address is sent for physical goods. This address will be provided and displayed on PayPal side. The consumer cannot change his address on PayPal side. He is notified to go back to the merchant website if he desires to change the delivery address. Make sure the consumer can change his shipping address when reviewing its order on the PayPal review page.

Here is a recap of the flows for ECM/and ECS with a review or without a review page. (The difference between ECS and ECM flows is that for ECS the shipping information are presented by PayPal whereas for ECM it is the merchant who sends the shipping information):



Direct Sale

For direct sales transactions, the merchant must send the parameter RequiresApproval at False. The default operation is direct sale.

Separated authorization and data captures

Authorizations are made during the checkout process. The parameter to be sent is RequiresApproval-True. Please be aware that only successful captures are covered by PayPal Seller Protection (not the successful authorization). It is therefore important not to send the goods until the funds are successfully captured.
The captures can be full or partial. In case the merchant sends a request for last partial captures and there is still an authorization amount remaining, Direct will automatically request PayPal to void (cancel) the remaining authorized amount.

Maintenance operations

The authorization can be cancelled. The cancellation can be full or partial.
Cancellation can be requested via the Back Office, Direct Maintenance or Connect.


A refund can be processed following a direct sale or a capture.
Direct supports full refund or partial refund on full captures but not partial refunds on multiple captures (this will be supported in the future).
The refund amount cannot exceed the original authorized amount. Multiple refunds can be made as long as the cumulative refunded amount does not exceed the original transaction value.
Refunds must be issued within 60 days of the original transaction.
Refunds can be requested via the Back-Office, Direct Maintenance or Connect.


The authorization is valid for a period of 29 days during which the buyer funds are on hold. PayPal offers a three-day honor period during which PayPal honors 100% of authorized funds. A new 3-day honor period can be requested when the first one has expired. However, it will not extend the original authorization period past 29 days.

Re-authorization can be requested via the Back Office or Direct Maintenance.

Line items

The content of the shopping basket can be provided in the line items to PayPal. This way each product is shown on the PayPal review page with its own name, price, quantity and description.

Reference transactions

Reference Transaction allows the merchants to have recurring payments through PayPal. If you want to use this feature please contact PayPal. Each merchant must get approved individually for reference transactions by PayPal Underwriting.

Below steps are needed to change your account configuration on PayPal:

  1. After log in, go to “Profile”.
  2. Click “Payment Receiving Preferences” link under “Selling Preferences”.
  3. Select “No, allow multiple payments per invoice ID”.

Billing Agreement

The buyer can sign up for recurring payments as part of the Express Checkout flow.
Buyers must set up a Billing Agreement (hosted on PayPal) first before merchant can charge consumers. PayPal will need to make sure that the buyer specifically agrees to the reference transaction in the purchase flow and that this is also reflected in the website terms and conditions for the provision of service.

The buyer must log in to PayPal once to agree, but after that PayPal login is not required. This agreement is represented as a billing agreement between the merchant and the buyer, which is maintained by PayPal. The buyer can agree during the Express Checkout flow. This Billing Agreement ID is stored in our database, which is send to PayPal automatically whenever a new recurring payment is made on an order. The billing agreement ID does not have a time frame; it is approved until canceled by the buyer.

In order to have a billing agreement ID created, the parameter tokenize = true  must be sent in the redirectPaymentMethodSpecificInput. The billing agreement ID can be created at the same time as a financial transaction or it can be created alone for future usage (in this case the amount of transaction must be equal to 0). A token will be sent back to the merchant.
For future reference transactions, the token must be provided in order for Worldline to send the correct billing agreement ID to PayPal.

Create Hosted Checkout for PayPal

Here is the information that can be sent in the Create Hosted Checkout for PayPal:






Language to be displayed on PayPal page







Physical/digital. Inform if the goods are physical or digital (for digital goods no shipping address must be sent)



Object containing amount and ISO currency code attributes



Sent to paypal to pre-fill the login page for the customer



Shipping address of the goods. It must not be sent in case for Express Checkout Shortcut and/or digital goods.

In order to have the transaction eligible for seller protection, some information must be sent in the shipping address:
- name.firstName or name.surname
- street
- city
- countryCode
- zip (some countries only)
- state (some countries only. Find here the complete list of supported state codes by PayPal. Please note: when you send an incomplete or incorrect shipping address, PayPal might decline the transaction.)

For more information about seller protection, please contact PayPal.



Used to display shopping basket. Please refer to Connect documentation for more information.





Used to display shopping basket. Please refer to Connect documentation for more information.







True/False. This field must be set to true when you request an authorization before capture. It is sent to false for direct sale



Value: 840. This is the PaymentProductId for PayPal





True/False. This field must be set to true for PayPal Express Checkout Shortcut and to false for PayPal Express Checkout Mark



Value of the token in case of reference transaction



True: When the merchant requests the creation of a billing agreement ID (for future reference transactions)


PayPal Fraud Prevention

User account status

The status of the PayPal account can be either verified or unverified. It becomes verified only after the user has validated the funding source that is attached to the PayPal account. On first PayPal registration consumer has status unverified.
Possible values

  • Verified
  • Unverified

How to get verified

To become verified, the user must:

  • Confirm the email address.
  • Add a credit card or bank account to the PayPal account.
  • Link and confirm the CC/bank account by either confirming the deposits made by PayPal or a random code posted on the statement
Address status

Status of the customer's address. A status of Confirmed means that a buyer‟s credit card billing and shipping addresses are the same. PayPal maintains a history of transactions shipped to any given address - when the address shows continual use with no issues raised by the buyer for non-receipt of items it will be rated confirmed.

Most unconfirmed addresses are not fraudulent, and sellers usually won’t experience problems with them. When you do ship to an unconfirmed address, PayPal encourages you to be alert and minimize risk by following their Security Tips for Sellers.

Possible values

  • Confirmed
  • Unconfirmed
  • None (consumer has never had goods shipped to his address)


The unique identifier of a PayPal account and will never change in the life cycle of a PayPal account. It is a unique 13 alphanumerical character’s value (e.g. RZJF8EE021L5P).

Account ID

The field AccountID is the username with which the PayPal account holder has registered at PayPal. This can be used with black- or whitelist as well as for velocity checks.

Possible values
  • Email address

PayPal Seller protection

With PayPal Seller Protection, you might be covered in the event of an unauthorised payment, an item not received dispute, chargeback, or reversal, as long as the transaction in question meets PayPal's eligibility requirements. You will receive this information in the field  RedirectPaymentMethodSpecificOutput.PaymentProduct840SpecificOutput.ProtectionEligibility:

  • Eligible
  • Ineligible

You should contact PayPal for any further questions about Seller Protection and eligibility requirements.

Your liability

PayPal’s policy outlines that a merchant is both liable and responsible for all PayPal disputes, claims and chargeback’s. Please click here for the most up to date information on dispute handling and resolution. Please click here for PayPal’s comprehensive guide on chargebacks.

PayPal logos and branding

For ECS flow, the “Checkout with PayPal button” can be located on the basket page or on the product page as there is no need for checkout on merchant side. The merchant must ensure that it is also optimized for mobile websites.

PayPal local buttons for shortcut: please check with your contact on PayPal.

For ECM flow, the PayPal logo is presented together with the other payment methods offered by the merchant.

PayPal logos: