worldline Direct
Sign up

Paypal

Intro

PayPal is a wallet which offers its consumers the option to pay online. The consumers can fund their wallet or choose to pay with their preconfigured payment method.

Our platform offers you the possibility to easily accept PayPal payments online. When your consumers choose to pay by PayPal, they are redirected to their PayPal account to confirm the order information and payment method. Next, we process the transaction through PayPal and transaction feedback is provided by PayPal. A real-time confirmation message is provided to both you and the consumer which contains the payment status.

Our platform has one of the most extensive integrations with PayPal available and is integrated to PayPal’s Express Checkout interface. You can choose between Express Checkout Shortcut (ECS) or Express Checkout Mark (ECM) as integration options.

Overview

Payment group:
Payment product id:
840
Key benefits
  • Fraud Prevention: Allows you to use user data for fraud prevention
  • Line items: Allows you to include basket items in the transaction
  • Direct sale and Authorization/Data Capture
  • Re-authorizations
  • Void authorizations
  • Refunds: Full/Partial refunds on single capture; Full refunds on multiple captures
  • Seller protection

Countries & currencies

Supported countries

Supported currencies

  • Australian dollar (AUD)
  • Brazilian real (BRL)
  • Canadian dollar (CAD)
  • Czech koruna (CZK)
  • Danish krone (DKK)
  • Euro (EUR)
  • Hong Kong dollar (HKD)
  • Hungarian forint (HUF)
  • Israeli new shekel (ILS)
  • Japanese yen (JPY)
  • Malaysian ringgit (MYR)
  • Mexican peso (MXN)
  • New Taiwan dollar (TWD)
  • New Zealand dollar (NZD)
  • Norwegian krone (NOK)
  • Philippine peso (PHP)
  • Polish zloty (PLN)
  • Pound sterling (GBP)
  • Russian ruble (RUB)
  • Singapore dollar (SGD)
  • Swedish krona/kronor (SEK)
  • Swiss franc (CHF)
  • Thai baht (THB)
  • United States dollar (USD)

Integration

Redirect your customers to the Paypal payment portal via our Hosted Checkout Page. Find a high level overview in the "Process flows" chapter.

Our platform allows both Express Checkout Mark and Express Checkout Shortcut mode. Depending on the mode, , differences apply:

Express Checkout Mark mode

Add the following properties to a standard CreateHostedCheckout request:

{
"order": {
"amountOfMoney": {
"currencyCode": "EUR",
"amount": 1000
}
},
"hostedCheckoutSpecificInput": {
"returnUrl": "https://yourReturnURL.com"
},
"redirectPaymentMethodSpecificInput": {
"paymentProduct840SpecificInput": {
"isShortcut": false
},
"PaymentProductId": "840"
}
}

Express Checkout Shortcut mode

Add the following properties to a standard CreateHostedCheckout request:

{
"order": {
"amountOfMoney": {
"currencyCode": "EUR",
"amount": 1000
}
},
"hostedCheckoutSpecificInput": {
"returnUrl": "https://yourReturnURL.com"
},
"redirectPaymentMethodSpecificInput": {
"paymentProduct840SpecificInput": {
"isShortcut": true
},
"PaymentProductId": "840"
}
}
Properties Remarks

redirectPaymentMethodSpecificInput
     paymentProductId
     requiresApproval

paymentProductId: The numeric identifier of the payment method on our platform. Find this id in the "Overview" chapter. It instructs our platform to send your customers directly to the Paypal portal. If left out, our platform sends your customers to the Hosted Checkout Page instead, allowing them to choose this or any other payment method in your account.

requiresApproval: Set to "false" as this payment method allows only direct sale operations.

paymentProduct840SpecificInput.isShortcut

Defines whether you use Express Shortcut (true) or Checkout Markt (false).

hostedCheckoutSpecificInput.returnUrl

The URL we redirect your customers to after the payment has been finalised.

Find detailed information about this object and its properties in our CreateHostedCheckoutAPI.

Process flows

  1. Your customers finalise an order in your shop and select PayPal.
  2. You send one of these CreateHostedCheckout requests (Express Checkout Mark or Express Checkout Shortcut) to our platform.
  3. You redirect your customers via the redirectUrl to the PayPal portal. They confirm the order with their login credentials (email address and password).
  4. We receive the transaction result.
  5. We redirect your customer to your returnUrl
  6. You request the transaction result from our platform via GetPayment or receive the result via webhooks.
  7. If the transaction was successful, you can deliver the goods / services.
Paypal-flow.png

Testing

Refer to our Test cases for test data and detailed instructions.

Make sure to use the right endpoint and switch back to the live URL as soon as you have finished your tests.

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 PSPID. 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 PSPID.

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 credentials. 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
    Test jbpPSP_1220517189_biz_api1.ogone.com
    Production support_api1.v-psp.com
  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.
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. 

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):

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.
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.
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):

paypal-integration_1-ogone paypal-integration_2-ogone
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
Cancellation

The authorization can be cancelled. The cancellation can be full or partial.
Cancellation can be requested via the Merchant Portal or CancelPayment

Refunds

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.

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:

HostedCheckoutSpecificInput:

Field

Description

Mandatory

locale

Language to be displayed on PayPal page.

N

Order:

Field

Description

Mandatory

PurchaseType

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

N

AmountOfMoney

Object containing amount and ISO currency code attributes.

Y

EmailAddress

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

N

ShippingAddress

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 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.

N

AmountBreakdown

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

N

Items

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

N

RedirectPaymentMethodSpecificInput:

Field

Description

Mandatory

RequiresApproval

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

N

PaymentProductId

Value: 840. This is the PaymentProductId for PayPal.

N

paymentProduct840SpecificInput:

isShortcut

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

N

Token

Value of the token in case of reference transaction.

N

Tokenize

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

N

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)

PayerID


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: https://www.paypal.com/buttons/?locale.x=en_C2

Was this page helpful?

Do you have any comments?

Thank you for your response.