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