Menu

User Tools

Create PDF

Site Tools


This is an old revision of the document!


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 Wirecard 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 Wirecard Checkout Page or Wirecard 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 Wirecard 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 Wirecard 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 Wirecard 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

Parameter mapping

The tables below show the parameter mapping between Wirecard request and response parameters and the respective PayPal interface parameters.

Request parameter mapping

(m): Payment request number.
(n): Basket item number.

Wirecard parameter PayPal interface parameter
amount PAYMENTREQUEST_(m)_AMT
currency PAYMENTREQUEST_(m)_CURRENCYCODE
Calculated by Wirecard. PAYMENTREQUEST_(m)_ITEMAMT
Calculated by Wirecard. PAYMENTREQUEST_(m)_TAXAMT
basketItem(n)ArticleNumber L_PAYMENTREQUEST_(m)_NUMBER(n)
basketItem(n)Description L_PAYMENTREQUEST_(m)_DESC(n)
basketItem(n)Name L_PAYMENTREQUEST_(m)_NAME(n)
basketItem(n)Quantity L_PAYMENTREQUEST_(m)_QTY(n)
basketItem(n)UnitNetAmount L_PAYMENTREQUEST_(m)_AMT(n)
basketItem(n)UnitTaxAmount L_PAYMENTREQUEST_(m)_TAXAMT(n)
consumerShippingAddress1 SHIPTOSTREET
consumerShippingAddress2 SHIPTOSTREET2
consumerShippingCity SHIPTOCITY
consumerShippingCountry SHIPTOCOUNTRYCODE
consumerShippingFirstName SHIPTONAME
consumerShippingLastName SHIPTONAME
consumerShippingPhone PHONENUM
consumerShippingState SHIPTOSTATE
consumerShippingZipCode SHIPTOZIP
customerStatement DESC
orderReference INVNUM
transactionIdentifier L_BILLINGTYPE(m), MerchantInitiatedBilling
LEGACY Shopping basket data
Wirecard parameter PayPal interface parameter
basketAmount ITEMAMT
basketCurrency Not needed for PayPal.
basketItems Not needed explicitly within PayPal interface.
basketItem(n)ArticleNumber L_NUMBERn
basketItem(n)Description L_DESCn
basketItem(n)Quantity L_QTYn
basketItem(n)Tax L_TAXAMTn
basketItem(n)UnitPrice L_AMTn
Calculated by Wirecard. TAXAMT

Response parameter mapping

Wirecard parameter PayPal interface parameter
gatewayReferenceNumber TRANSACTIONID
paypalBillingAgreementID BILLINGAGREEMENTID
paypalPayerAddressCity SHIPTOCITY
paypalPayerAddressCountry SHIPTOCOUNTRY
paypalPayerAddressCountryCode SHIPTOCOUNTRYCODE
paypalPayerAddressName SHIPTONAME
paypalPayerAddressState SHIPTOSTATE
paypalPayerAddressStreet1 SHIPTOSTREET
paypalPayerAddressStreet2 SHIPTOSTREET2
paypalPayerAddressZIP SHIPTOZIP
paypalPayerEmail EMAIL
paypalPayerFirstName FIRSTNAME
paypalPayerID PAYERID
paypalPayerLastName LASTNAME

Back-end operations

Recurring payments

To carry out recurring payments the parameter 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 255 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, Wirecard offers the option to open PayPal as a normal page without using pop-ups.

Please contact our support teams to enable this feature.


This website uses cookies to deliver the best service to you. By continuing to browse the site, you are agreeing to our use of cookies.