1. Introduction

PayPal Express Checkout is a means of integrating PayPal, that allows you to break down the financial transactions into different steps:

  • authorisation
  • data capture
  • refund ...

In addition to this, PayPal Express Checkout also allows the identification step to be separated from the financial transaction (payment step). This feature enables you to perform the identification step much earlier on in the order process and use the identification result to retrieve the customer's address as registered in the customer’s PayPal account.

2. Configuration

2.1 PayPal Account Configuration

You must set up your PayPal (Business) account  at PayPal.com to allow our system’s API user to access your account.

To grant API access to our system’s API user, you need to log on to your PayPal account:

  1. Login to your Paypal account with your PayPal Business e-mail address in either the sandbox or live environment
  2. In the "Pre-built payment solution" section, click "Grant API permissions".
  3. Click the "Add New Third Party" button.
  4. Enter the Worldline API user name: “support_api1.v-psp.com” (Live) / "jbpPSP_1220517189_biz_api1.ogone.com" (Test) in the “Third Party Permission Username” field and click "Lookup".
  5. Tick the following boxes:
    • "Use Express Checkout to process payments"
    • "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"
    • "Issue a refund for any prior transaction"
    • "Generate consolidated reports for all accounts"
  6. Once the boxes are ticked, click "Add".
  7. You can now configure PayPal Express Checkout in your Worldline account.

Remarks:

  • This step is obligatory. If your PayPal account is not properly configured, you will not be able to configure PayPal on your Worldline account.
  • The actual structure and behavior of the PayPal back office may differ from this description.

2.2 Worldline Account Configuration

You have to configure PayPal via the “Payment methods” link in your Worldline Account. The activation of the payment method will be handled by our Customer Care department.

Enabling or disabling the “Direct sale” button in Express Checkout allows users to choose between working in two stages (authorisation and data capture) or in just one (direct sale: automatic data capture by our system when a valid authorisation is available).

When API permission has not been granted and you want to configure Express Checkout in your account, the following error message will be displayed: "Error test merchant config for Paypal ExpressCheckout, probably API access to Paypal merchant account was not authorised by the Merchant"

Note: No end-to-end simulation is possible so use test@test.com as the mandatory email address to test PayPal.

3. Integration: identification and transaction in one step

The following workflow represents a transaction with PayPal Express Checkout for you (as a merchant) when you don't split the identification and the transaction (payment) steps:

You must send at least the following hidden fields (general Hosted Payment Page parameters) in the redirection to orderstandard.asp / orderstandard_utf8.asp:

>
FieldExplanation
PSPID Merchant affiliation name in our system
ORDERID Merchant order number (merchant reference)
AMOUNT Amount to be paid (MULTIPLIED BY 100)
CURRENCY Order currency in ISO alpha code.
LANGUAGE Customer language
OWNERADDRESS Address
OWNERTOWN Town or city
OWNERZIP Postcode / ZIP
OWNERCTY ISO country code (BE, FR, US, etc.)
DEVICE If the cardholder is using a mobile device (such as an iPhone), you may send the "mobile" value. Our system does NOT identify the device.

Optional:

Field Explanation
COMPLUS Use this field to submit product/item details. The data will be displayed on the PayPal page.

More information about these fields can be found in your Worldline account. Just log in and go to: "Support > Integration & user manuals > Technical guides > Parameter Cookbook".

On submission of the hidden fields, the customer is displayed our secure payment page with an overview of the possible payment methods that are activated in your account. He can then select PayPal.

If you want the customer to select the payment method PayPal on your website instead of on our payment page, you must send us the value "PayPal" with the additional PM hidden field. On submission of the hidden fields, we will forward the customer directly to the PayPal website. The customer will be redirected to the PayPal login screen, where he will be able to identify himself and verify the payment.

Important note on the PayPal cancellation button

The cancel button on the PayPal Express Checkout page does not cancel the transaction on the Worldline payment page; by default it takes the customer back to the payment method selection on our payment page, OR it redirects the customer to your own payment method selection page by using the "BACKURL" or back button configuration.

You can configure the BACKURL in your Worldline account, via Configuration > Technical information > Payment page > "Back button redirection", and/or you send it along with the other hidden fields to the payment page. In this last case, the URL in the "Back button redirection" (if entered) will be overwritten.

4. Integration: Split identification and payment

The following workflow represents a transaction with PayPal Express Checkout where the identification and payment steps have split:

4.1 Step 1: Identification request

This first step occurs on your website between the shopping basket confirmation and the collection of the delivery details. You need to display a PayPal pay button which redirects the customer to the Hosted Payment Page interface.

You must send the following additional hidden fields behind the pay button in the redirection to /orderstandard_UTF8.asp:

Field Explanation
PSPID Merchant affiliation name in our system
ORDERID Merchant order number (merchant reference)
AMOUNT Amount to be paid (MULTIPLIED BY 100)
CURRENCY Order currency in ISO alpha code
LANGUAGE Customer language
SHASIGN SHA-IN signature for security
ACCEPTURL URL to which the customer's details will be posted if the identification is successful
DECLINEURL URL to which the customer's details will be posted if the identification fails
PM Fixed value “PAYPAL”
TXTOKEN Fixed value “INIT”

Optional:

Field Explanation
COMPLUS Use this field to submit product/item details. The data will be displayed on the PayPal page.

More information about these fields can be found in your Worldline account. Just log in and go to: "Support > Integration & user manuals > Technical guides > Parameter Cookbook".

On submission of the hidden fields, we will redirect the customer to the PayPal website. The customer will be redirected to the PayPal login screen, where he will be able to identify himself, review his delivery details and continue.

This step can be simulated on the following test page: https://ogone.test.v-psp.com/ncol/test/teststd_paypal_express.htm. You can enter “displayparams.asp” as ACCEPTURL and DECLINEURL in order to have the customer details and parameter feedback displayed in the browser window.

4.2 Step 2: Client details reception

When the identification is successful, the customer's details, including the addresses stored in his PayPal account, will be posted to the ACCEPTURL you've specified in the hidden fields of the identification request (previous step).

4.2.1 Data

The following table lists the available customer data:

Not all fields are always available. The details come directly from the PayPal account. We cannot guarantee the accuracy of this data.
Parameter
PAYEREMAIL
Length: 127
Format: email
PAYERID
Length: 17
Format: alphanumeric
PAYERSTATUS
Length: 10
Format:alpha
Possible values: Verified / Unverified
PAYERSALUTATION
Length: 20
Format: alpha
PAYERFIRSTNAME
Length: 25
Format: alpha
PAYERMIDDLENAME
Length: 25
Format: alpha
PAYERLASTNAME
Length: 25
Format: alpha
PAYERSUFFIX
Length: 12
Format: alpha
PAYERCOUNTRY
Length: 2
Format: alpha
PAYERBUSINESS
Length: 127
Format: alpha
PAYERADRSTATUS
Length: 11
Format: alpha
Possible values: None / Confirmed / Unconfirmed
PAYERADRNAME
Length: 32
Format: alpha
PAYERADRSTREET1
Length: 100
Format: alphanumeric
PAYERADRSTREET2
Length: 100
Format: alphanumeric
PAYERADRCITYNAME
Length: 40
Format: alphanumeric
PAYERADRSTATEORPROVINCE
Length: 40
Format: alphanumeric
PAYERADRPOSTALCODE
Length: 20
Format: alphanumeric
PAYERADRCOUNTRY
Length: 2
Format: alphanumeric
CUSTOM
Length: 256
Format: alphanumeric
INVOICEID
Length: 127
Format: alphanumeric
CONTACTPHONE
Length: 12
Format: Mask (i.e. +XXXXXXXXXXX / XXX-XXX-XXXX (US) )

In addition to the data received from PayPal, you will receive the following information from our system:

  • TXTOKEN: 25 alphanumeric (the merchant needs to store this information for the payment step)
  • PAYID: 15 numeric (the merchant needs to store this information for the payment step)
  • PSPID
  • ORDERID
  • CURRENCY
  • AMOUNT
  • AUTHENTSTATUS=0 (only sent if the buyer was able to identify himself).

4.2.2 Security and configuration

To receive the transaction parameters on the specified ACCEPTURL, you need to activate the “I would like to receive transaction feedback parameters on the redirection URLs” option in the "Transaction feedback" tab, in the "HTTP redirection in the browser" section of the Technical Information page.

The redirection process is visible, as it is sent via the customer’s browser. Consequently, you must use an SHA-OUT signature to verify the contents of the request (see SHA-OUT). If you don't configure an SHA-OUT signature, we shall not send any feedback parameters to your ACCEPTURL.

All parameters can be transmitted to the ACCEPTURL using the POST or GET method, depending on the configuration in your Worldline Account's Technical information page > "Transaction feedback" tab, in the "Direct HTTP server-to-server request" section (Request method).

4.2.3 SHA-OUT

To ensure the integrity of the feedback parameters, we strongly recommend you to perform a SHA-OUT calculation.

The values of the fields listed below need to be concatenated in the given order, with the SHA-OUT pass phrase only at the end of the string.

Note: This SHA-OUT calculation should not to be confused with the SHA-OUT calculation on the transaction feedback (see Hosted Payment Page).

Fields to include (if a value is given) Example Parameters
PAYEREMAIL billsmith@test.com
PAYERID smith123
PAYERSTATUS Verified
PAYERSALUTATION Mr.
PAYERFIRSTNAME Bill
PAYERMIDDLENAME
PAYERLASTNAME Smith
PAYERSUFFIX
PAYERCOUNTRY BE
PAYERBUSINESS
PAYERADRSTATUS Confirmed
PAYERADRNAME Smith
PAYERADRSTREET1 Teststreet 123
PAYERADRSTREET2
PAYERADRCITYNAME Brussels
PAYERADRSTATEORPROVINCE
PAYERADRPOSTALCODE 1000
PAYERADRCOUNTRY BE
CUSTOM
INVOICEID abcde12345
CONTACTPHONE 021234567
TXTOKEN 1a76c18n4klo693ms77dq42wb
PAYID 123456789
PSPID MyPSPID
orderID test1234
currency EUR
amount 15.00
AUTHENTSTATUS 0
SHA-OUT PASS PHRASE (as configured in the Technical information page "Transaction feedback") Mysecretsig1875!?

String to hash: billsmith@test.comsmith123VerifiedMr.BillSmithBEConfirmedSmithTeststreet123
Brussels1000BEabcde123450212345671a76c18n4klo693ms77dq42wb123456789
MyPSPIDtest1234 EUR15.00Mysecretsig1875!?

Resulting Digest (SHA-1): DBD2CD8AD440649A5CDB6B6C5C1A49EF29E5474A

4.3 Step 3: Authorisation/payment request

You can perform this third step via Hosted Payment Page or via DirectLink.

4.3.1 Hosted Payment Page

You must send at least the following additional hidden fields in the redirection to orderstandard.asp / orderstandard_UTF8.asp:

Parameter Explanation
PSPID Merchant affiliation name in our system
ORDERID Merchant order number (merchant reference)
AMOUNT Amount to be paid (MULTIPLIED BY 100)
CURRENCY Currency of the order in ISO alpha code
LANGUAGE Language of the customer
SHASIGN SHA-IN signature for security
PM “PAYPAL” fixed value
TXTOKEN As received from our system (see step 2)
PAYID As received from our system (see step 2)

Optional:

Field Explanation
COMPLUS Use this field to submit product/item details. The data will be displayed on the PayPal page.

More information about these fields can be found online. Just log in to your Worldline account and go to: "Support > Integration & user manuals > Technical guides > Parameter Cookbook".

If you send us the authorisation/payment request via Hosted Payment Page, on submission of the hidden fields the customer will be sent straight to the transaction confirmation screen (unless an error occurs).

If you want to redirect the customer at the end of the transaction process, you can send an ACCEPTURL or DECLINEURL in the hidden fields that differs from those sent in step 1.

This step can be simulated on the following test page: https://ogone.test.v-psp.com/ncol/test/teststd.asp

Important note on the PayPal cancellation button

The cancel button on the PayPal Express Checkout page does not cancel the transaction on the Worldline payment page; by default it takes the customer back to the payment method selection on our payment page, OR it redirects the customer to your own payment method selection page by using the "BACKURL" or back button configuration.

You can configure the BACKURL in your Worldline account, via Configuration > Technical information > Payment page > "Back button redirection", and/or you send it along with the other hidden fields to the payment page. In this last case, the URL in the "Back button redirection" (if entered) will be overwritten.

4.3.2 DirectLink

You must send at least the following parameters in the request on orderdirect.asp: (No credit card related information needs to be sent)

Parameter Explanation
PSPID The merchant’s affiliation name in our system
USERID Name of the merchant’s application (API) user
PSWD Password of the API user (USERID)
ORDERID The merchant’s order number (merchant reference)
AMOUNT Amount to be paid MULTIPLIED BY 100
CURRENCY Currency of the order in ISO alpha code
PM Fixed value “PAYPAL”
TXTOKEN As received from our system (see step 2)
PAYID As received from our system (see step 2)

Optional:

Field Explanation
COMPLUS Use this field to submit product/item details. The data will be displayed on the PayPal page.

If you've entered a value in the SHA-IN Signature field in the "Checks for DirectLink" section (in the Technical information page in your account, the "Data and origin verification" tab), you also need to send the SHASIGN parameter with your request.

If you send us the authorisation/payment request via DirectLink, our system returns you the response in XML format.

5. Maintenance operations

Maintenance operations (data capture, refund, etc.) can be performed in your Worldline Account or via DirectLink, i.e. in a similar way as for standard credit card transactions.

A PayPal authorisation is only valid for 3 days.

6. Alias Manager: Recurring transactions

You can perform recurring transactions with PayPal Express Checkout without having to re-enter the customer's identification details.

In order to work with recurring PayPal transactions, you need to activate the Alias Manager option in your Worldline account. Alias Manager allows you to process recurring transactions.

6.1 PayPal Account Configuration

Next to the basic PayPal account configuration, the following boxes will also need to be ticked for the API permissions:

  • Create and manage Recurring Payments
  • Obtain authorization for pre-approved payments and initiate pre-approved transactions
  • Charge an existing customer based on a prior transaction
Note: The actual structure and behaviour of the PayPal back office may differ from the description below.

6.2 Integration: identification and transaction in one step

To create an alias, in addition to the default hidden fields the merchant must send specific alias fields:

Field Description
ALIAS Alias proposed by the merchant
ALIASOPERATION Fixed value “BYMERCHANT”
ALIASUSAGE A text explaining the reason for the Alias registration
SHASIGN SHA-IN signature, for data integrity. (Please refer to the Alias Manager integration guide)

When the customer is sent to the PayPal login screen, he will identify himself and verify the payment (the current and future amounts) by clicking the “Agree and Pay” button.

When the customer clicks the “Agree and Pay” button, he enters into an invoicing agreement with PayPal, which authorises the merchant to charge the customer's PayPal account directly. We will create the Alias in our Alias database based on the PayPal invoicing agreement.

6.3 Integration: splitting identification and payment

6.3.1 Step 1: Identification request

To create an alias, in addition to the default hidden fields the merchant must send specific alias fields:

Field Description
ALIAS Alias proposed by the merchant
ALIASOPERATION Fixed value “BYMERCHANT”
ALIASUSAGE A text explaining the reason for the Alias registration
SHASIGN SHA-IN signature, for data integrity. (Please refer to the Alias Manager integration guide)

When the customer is sent to the PayPal login screen, he will identify himself and verify the payment (the current and future amounts) by clicking the “Agree and Pay” button.

When the customer clicks the “Agree and Pay” button, he enters into an invoicing agreement with PayPal, which authorises the merchant to charge the customer's PayPal account directly. We will create the Alias in our Alias database based on the PayPal invoicing agreement.

6.3.2 Step 2: Client details reception

Same as normal "Step 2" (cf. Step 2: Client details reception), but only via Hosted Payment Page (hosted payment page).

6.3.3 Step 3: Authorisation payment request

In step 3, the same additional fields as in "Step 1" must be sent (see default hidden fields of Step 3):

Field Description
ALIAS Alias proposed by the merchant (the same as in step 1)
ALIASOPERATION Fixed value “BYMERCHANT” (the same as in step 1)
ALIASUSAGE A text explaining the reason for the Alias registration (the same as in step 1)

At this stage we will create the Alias in our Alias database, based on the invoicing agreement from PayPal.

6.4 Alias usage

The merchant can perform a recurring PayPal transaction via the Hosted Payment Page or DirectLink mode.

6.4.1 Hosted Payment Page

The merchant needs to send an existing ALIAS value in the “ALIAS” hidden field. We will then check whether the ALIAS already exists for the merchant’s PSPID. If the ALIAS exists, we will trigger a recurring payment. The customer will be sent straight to the payment confirmation screen (unless an error occurs).

Please refer to the Alias Manager integration guide for information on the mandatory pre-payment checks (SHA-IN signature) and post-transaction feedback requests (SHA-OUT signature).

6.4.2 DirectLink

The merchant has to send the “ALIAS” parameter in his request. We will then check whether the ALIAS exists for the merchant’s PSPID and look up the financial profile (based on the ALIAS) in the database.

Please refer to the Alias Manager integration guide for information on the mandatory pre-payment check (SHA-IN signature).

Important
When using an Alias with Paypal, the Merchant also has to specify the brand in his request (PM=PAYPAL)

6.5 Alias management

The value in the “card number” field in the alias management page represents the PayPal invoicing agreement for that specific alias.

It is not possible to update an alias (manually or during a transaction). The merchant needs to delete the original alias and create a new one in the event that some of the details change.

Every Alias remains valid until it is deleted.

7. Instant Payment Review (IPR)

Instant Payment Review is a process aimed at reducing fraud through PayPal online payments.

With this functionality, each transaction will have a "pending" status until manually verified by PayPal; this verification usually takes between 24 and 36 hours after the online transaction. Once verified, Paypal will send you an IPN (Instant Payment Notification) containing all relevant payment information.

7.1 Parameters

In order for IPR to function, you must send the customer's address information via the fields below:

Field Description Mandatory
ECOM_SHIPTO_ONLINE_EMAIL E-mail address N
ECOM_SHIPTO_POSTAL_CITY Town or city Y
ECOM_SHIPTO_POSTAL_COUNTRYCODE ISO country code (BE, FR, US, etc.) Y
ECOM_SHIPTO_POSTAL_NAME_FIRST First name Y
ECOM_SHIPTO_POSTAL_NAME_LAST Last name Y
ECOM_SHIPTO_POSTAL_POSTALCODE Postcode / zip Y
ECOM_SHIPTO_POSTAL_STATE State (ISO code - 2 chars) Y
ECOM_SHIPTO_POSTAL_STREET_LINE1 Address Y
ECOM_SHIPTO_POSTAL_STREET_LINE2 Additional address details N
ECOM_SHIPTO_POSTAL_STREET_NUMBER House number N
ECOM_SHIPTO_TELECOM_FAX_NUMBER Fax number N
ECOM_SHIPTO_TELECOM_PHONE_NUMBER Telephone number N

More information about these fields can be found in your Worldline account. Just log in and go to: "Support > Integration & user manuals > Technical guides > Parameter Cookbook".

7.2 Workflow

  • During the payment process: After the customer has identified himself, all information is sent to PayPal. The customer will see that the transaction is being processed Offline.
  • In the first 24 hours following the payment: Nothing will happen. PayPal will not provide a response for at least 24 hours.
  • Between 24 and 48 hours after the payment: PayPal will send the review results to our system. If you have configured your account to receive offline status change notifications, you will receive one at that moment. This is to be configured in your Technical Information, in the "Transaction Feedback" tab. For more information about notifications, go to "Use your Worldline account".
  • Between 48 and 96 hours after the payment: If we have not received any information from PayPal after 48 hours, our system will fetch the payment result from PayPal. If no result is received, we will re-try every 4 hours.
  • 96+ hours after the payment: If the transaction is still unresolved after 96 hours, you should contact our Customer Care department, which will contact PayPal and solve the issue manually.

7.3 Statuses

If working with the Sale operation code:

  • When submitting a new transaction, the status will be "91 - Payment processing"
  • If the Review result is positive (no fraud) the transaction status will be "9 - Payment requested"
  • If the Review Result is negative, the transaction status will be "93 - Payment refused"

If working with the Authorisation operation code:

  • When submitting a new transaction, the status will be "51 - authorisation processing"
  • If the Review result is positive (no fraud), the transaction status will be "5 - Authorised"
  • If the Review Result is negative, the transaction status will be "2 - Authorisation refused"
PayPal recommends you NOT to deliver any goods until payment has been settled!

For more information about operation codes, go to "Use your Worldline account".

7.4 Worldline account

When viewing the transaction detail in your Worldline Account, the following message will appear:

Note that this message will remain visible, even when the status has been updated following the PayPal response, (in this example, you see the transaction is already in status 9).

8. 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 should contact PayPal for any further questions about Seller Protection and eligibility requirements.

In order for a transaction to comply with Seller Protection after approval from PayPal, you must send the following fields with every transaction:

Parameter Description
ECOM_SHIPTO_POSTAL_NAME_FIRST Delivery first name
ECOM_SHIPTO_POSTAL_NAME_LAST Delivery last name
ECOM_SHIPTO_POSTAL_STATE Delivery state (ISO code - 2 chars)
ECOM_SHIPTO_POSTAL_STREET_LINE1 Delivery address first line
ECOM_SHIPTO_POSTAL_STREET_LINE2 Delivery address second line
ECOM_SHIPTO_POSTAL_COUNTRYCODE Delivery ISO country code (BE, FR, US, etc.)

The following parameters are not mandatory but are recommended to comply in the best way with seller protection:

Parameter Description
ECOM_SHIPTO_POSTAL_CITY Delivery city
ECOM_SHIPTO_POSTAL_POSTALCODE Delivery postcode 

Best practice for Seller Protection

  • According to PayPal specifications, Worldline must send the buyer's full name in the field ADRSHIPNAME to PayPal. 
    The corresponding value for this field is the value of either
    ECOM_SHIPTO_POSTAL_NAME_LAST or ECOM_SHIPTO_POSTAL_NAME_FIRST

  • ECOM_SHIPTO_POSTAL_NAME_LAST has a higher priority than ECOM_SHIPTO_POSTAL_NAME_FIRST.
    When you send data for both fields, only ECOM_SHIPTO_POSTAL_NAME_LAST will be taken into account.

  • Please make sure that you send correct and complete data for these fields.  This will ensure that we transfer the data to Paypal and you will be eligible for Seller protection

  • As a fallback solution, we will not transfer the shipping data to Paypal if we detect errors, such as
    • the data is incomplete
    • the format of your data is incorrect
    • contradicting information (i.e. state code incompatible with country code)

      This will prevent transactions from being declined, but you will not be eligible for the Seller protection anymore.

FAQs

The time to activate a payment method depends on the following factors:

  • It generally takes the acquirer or bank about a week to complete your affiliation. If you already have an affiliation, the activation takes a few days.
  • Some payment methods require additional checks before they can be activated, e.g. in case of 3-D Secure, which is requested directly at VISA or MasterCard (and not at the acquirer). 

With Worldline Collect, you can activate several payment methods in one go.


An acquirer is a financial institution that processes payments from certain credit and debit cards. The acquirer is responsible for the financial part of transaction processing and Worldline is responsible for the technical part. In other words, without an acquirer the money will not be transferred to your bank account.

For every online payment method you want to add, you need an acceptance contract with an acquirer. If you’d like advice on which acquirer would be best suited for you and your region, please contact us. If you know which acquirer you want to work with, you can simply select them from the drown down list when adding a payment method in your account. 

But why not let us take care of it for you? Full Service allows you to activate many local payment methods, all at once and in several different countries – with one single contract. If you trade internationally, it could be the ideal way to accept payments from all across Europe. It saves you time-consuming administration and because you can offer more payment methods, it can also increase your revenues. 

Find out more about Full Service here and by contacting us and asking for contract information.

Sometimes it happens that an affiliation number has been put inactive on the side of the acquirer. We suggest you contact your acquirer for this.