PayPal

PayPal

General information

PayPal is an American company operating a worldwide online payments system which has been a wholly owned subsidiary of eBay from 2002 till its spin-off which was completed in July 2015. The company acts as acquirer, i.e. managing payment processing for online vendors, auction sites and other commercial users.

Operating in more than 200 markets, PayPal has more than 160 million active, registered accounts and allows customers to make financial transactions online in many different currencies all over the world.

Please visit PayPal for further information and details.

To integrate and offer PayPal as payment method to your consumers in your online shop you need to take into consideration the following issues.

Important requirements

The following requirements must be met when integrating PayPal:

  • All required data of your consumer are available.

  • Submit additional parameters which are required by PayPal for processing the payment of your consumer.

  • Your consumer may change the shipping address within the payment in PayPal. Therefore we return the shipping address together with other payment details in the response parameter to your online shop for further processing in your fulfillment process.

  • Setup third party permissions for QENTA to your PayPal account as described below.

Do not offer this payment method to your consumer in your online shop unless these requirements are met.

Please visit PayPal for further information and details.

If your online shop is enabled for payment method PayPal it is required that you use additional request and response parameters when integrating QPAY Checkout Page or QMORE Checkout Seamless into your shop. Especially these request parameters have to been set whenever you (or your consumer) set the payment method to PayPal or to SELECT.

If the payment has been accepted by PayPal you will get as response the parameter paymentState with the value ”SUCCESS”.

We recommend to store the PayPal TRANSACTIONID of the payment as returned by the parameter gatewayReferenceNumber within the data regarding the corresponding session and order for documentation purposes.

At a later time you have also the possibility to get the TRANSACTIONID via the QPC Payment Center by searching for the specific payment and then using the details view for the GatewayReferenceNumber.

Two-step process for approved payments and deposited payments

PayPal transactions are by default set to be immediately approved and deposited in one single step.

However, upon your request we are able to split up this single step into a two-step processes - approval and deposit. This two-step process allows you to distinguish between approved payments and deposited payments and perform certain actions for each of them. You have the possibility to decide when to deposit amounts that have already been approved.

To enable the two-step process in your merchant settings, please contact our support teams.

Setting up 3rd party permissions

To enable the integration of PayPal into your online shop in our QENTA Checkout solutions we need to get some "third party permissions" to your PayPal Business Account for accessing PayPal related payment information. Please follow the required setup steps described in Setting up 3rd party permissions.

Order flow diagram

For a visual representation of the order flow behavior and associated transaction-based operations of this payment method we invite you to have a look at the respective order flow diagram.

Required request parameters

The use of the following request parameters is mandatory for payment method PayPal.

consumer billing data and shopping basket data

If you would like to use PayPal Seller Protection the parameters for consumer billing data and shopping basket data are required. For further information on these parameters go to Consumer billing data and Shopping basket data.

Please note the length restrictions that apply for this payment method and the following shopping basket parameters.

Shopping basket data

Parameter

Within fingerprint

Data type

Short description

basketItem(n)ArticleNumber

Required if used.

Alphanumeric with special characters and with a variable length of up to 128 characters.

Unique ID of article n in shopping basket.

basketItem(n)Description

Required if used.

Alphanumeric with special characters and with a variable length of up to 128 characters.

Product description of article n in shopping basket.

pendingUrl and confirmUrl

With the parameter pendingUrl you can define the URL of your online shop where your consumer is forwarded when the payment process could not determine a result yet. On this page of your online shop you should inform your consumer about the pending situation of the payment process.

With the parameter confirmUrl you can define the URL of your online shop used by the QENTA Checkout Server to send to your online shop relevant return values containing the result of the payment process.

Note that the state "pending" is only used if the parameter pendingUrl is set in combination with the parameter confirmUrl. Otherwise you will get a "failure" instead of a "pending" state.

For further information have a look at pendingUrl and confirmUrl.

Optional request parameters

The optional request parameters customerStatement and orderReference are more restricted with regard to their length and allowed characters than are other general request parameters.

Parameter Data type Short description

customerStatement

ASCII with a variable length of up to 254 characters.

Text displayed on bank statement issued to your consumer by the financial service provider.

orderReference

ASCII with a variable length of up to 128 characters.

Unique order reference ID sent from merchant to financial institution.

Parameter basketItem to reedem vouchers

If the consumer in your online shop redeems a voucher or coupon during the payment process, the optional request parameter basketItem must be used. This parameter must contain the negative amount corresponding to the voucher or coupon value. For vouchers with percentage discount, the percentage to be deducted must first be converted into an absolute value. The total basket amount displayed to the consumer in your online shop will then show both the voucher amount and the total basket amount reduced by this voucher amount.

Additional response parameters

When using this payment method in your online shop, we will return additional parameters to your online shop. These parameters are specific to this payment method and are only returned when your consumer selects this payment method in your online shop.

Parameter State Data type Short description

gatewayReferenceNumber

Success

Alphanumeric with special characters and a variable length of up to 255.

Transaction ID of authorization.

paypalBillingAgreementID

Success

Alphanumeric with a variable length of up to 19.

Billing agreement ID returned by PayPal.

paypalPayerAddressCity

Success

Alphanumeric with a variable length of up to 40.

City of shipping address.

paypalPayerAddressCountry

Success

Alphabetic with a variable lenth of up to 50.

Country of shipping address.

paypalPayerAddressCountryCode

Success

Alphabetic with a fixed length of 2.

Country code (ISO 3166-1) of shipping address.

paypalPayerAddressName

Success

Alphanumeric with a variable length of up to 32.

Name of shipping address.

paypalPayerAddressState

Success

Alphanumeric with a variable length of up to 40.

State of shipping address.

paypalPayerAddressStreet1

Success

Alphanumeric with a variable length of up to 100.

Street line 1 of shipping address.

paypalPayerAddressStreet2

Success

Alphanumeric with a variable length of up to 100.

Street line 2 of shipping address.

paypalPayerAddressZIP

Success

Alphanumeric with a variable length of up to 20.

ZIP code of shipping address.

paypalPayerEmail

Success

Alphanumeric with special characters and a variable length of up to 127.

E-mail address of consumer as returned by PayPal.

paypalPayerFirstName

Success

Alphanumeric with a variable length of up to 64.

First name of consumer as returned by PayPal.

paypalPayerID

Success

Alphanumeric with a variable length of up to 13.

ID of consumer as returned by PayPal.

paypalPayerLastName

Success

Alphanumeric with a variable length of up to 64.

Last name of consumer as returned by PayPal.

Back-end operations

Please refer to transaction-based operations by payment method and non-transaction-based operations by payment method for further information and details on back-end operations in QPAY Checkout Page and QMORE Checkout Seamless.

Recurring payments

To carry out recurring payments the parameter request_parameters#transactionIdentifier is used. For more information visit recurPayment.

Additional required request parameters

This otherwise optional request parameter consumerDeviceId is required by PayPal for so-called "on-demand payments" initiated by the consumer in the online shop.

Recurring payments initiated by the merchant, without interaction of consumer, used for handling subscription-based transactions do not need this parameter.

Security parameter

Parameter

Data type

Short description

consumerDeviceId

Alphanumeric with special characters and a variable length of up to 32 characters.

Unique token which serves as a method of fraud protection.

Please note that the parameter consumerDeviceId is NOT part of the fingerprint.

We recommend merchants to contact PayPal on integration to obtain more information on this parameter in tems of the specific business case.

Additionally for payment method PayPal the basket parameters can be set and will be displayed when used in a recurring payment.

Although the following parameters are in general optional, either all parameters need to be set, except for basketItem(n)Description and basketItem(n)ImageUrl which remain optional, or none.

Please note that these basket parameters are NOT part of the fingerprint.

Shopping basket data

Parameter

Within fingerprint

Data type

Short description

basketItems

Required if used.

Numeric.

Number of items in shopping basket.

basketItem(n)ArticleNumber

Required if used.

Alphanumeric with special characters.

Unique ID of article n in shopping basket.

basketItem(n)Description

Required if used.

Alphanumeric with special characters.

Product description of article n in shopping basket.

basketItem(n)ImageUrl

Required if used.

Alphanumeric with special characters.

URL to an image of each item.

basketItem(n)Name

Required if used.

Alphanumeric with special characters.

Product name of article n in shopping basket.

basketItem(n)Quantity

Required if used.

Numeric

Items count of article n in shopping basket.

basketItem(n)UnitGrossAmount

Required if used.

Amount

Price per unit of article n in shopping basket with taxes.

basketItem(n)UnitNetAmount

Required if used.

Amount

Price per unit of article n in shopping basket without taxes.

basketItem(n)UnitTaxAmount

Required if used.

Amount

Tax amount per unit of article n in shopping basket.

basketItem(n)UnitTaxRate

Required if used.

Percentage of tax, e.g. 20 or 19.324. Up to 3 fractions.

Percentage of tax per unit of article n in shopping basket.

Approval from PayPal

Please remember that for using the back-end operation recurPayment (called reference transaction in PayPal, not recurring transaction) you need to request approval from PayPal to enable this reference transaction. To request approval, please contact PayPal Customer Support or your PayPal account representative. After receiving approval from PayPal please also contact our support teams to enable this feature.

FAQ

Which language is presented to your consumer on the PayPal pages?

If the parameter consumerShippingCountry is set, PayPal will display its own pages in the language of that country. Otherwise if this parameter is not set PayPal will use the language configured within the web browser of your consumer.

What configuration settings are necessary if no shipping address needs to be entered by the consumer because e.g. only digital goods are sold in the online shop (no shipping)?

The respective PayPal parameter is NOSHIPPING=1. Please be aware that your merchant configuration has to be changed by our support teams on your behalf in order to use this feature.

What configuration settings are necessary to prevent the consumer in your online shop from editing the shipping address (parameter "no address change")?

The respective PayPal parameter is ADDROVERRIDE=1. Please be aware that your merchant configuration has to be changed by our support teams on your behalf in order to use this feature.

It is not possible to open PayPal in an iframe to enter the consumer’s data. How is the PayPal page displayed then?

As pop-up which is generally well suited for all devices and used by default, or via a page redirect which should be used for checkout processes in web view within a native app. For further information contact our support teams.

What happens if pop-up blockers are enabled and the PayPal page is not shown?

When the consumer to your online shop selects the payment method PayPal, a pop-up will open by default to enter the relevant consumer’s payment details. Since a lot of consumers have pop-up blockers enabled, the pop-up may not be shown and consumers may not proceed with the checkout process. In order to allow consumers to proceed with the checkout even if pop-up blockers are enabled, QENTA offers the option to open PayPal as a normal page without using pop-ups.

Please contact our support teams to enable this feature.