Last update 6/09/2019

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 e-Commerce 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”
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 ePDQ 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://mdepayments.epdq.co.uk/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.
Name Length Format Possible Values
PAYEREMAIL 127 email  
PAYERID 17 alphanumeric  
PAYERSTATUS 10 alpha Verified / Unverified
PAYERSALUTATION 20 alpha  
PAYERFIRSTNAME 25 alpha  
PAYERMIDDLENAME 25 alpha  
PAYERLASTNAME 25 alpha  
PAYERSUFFIX 12 alpha  
PAYERCOUNTRY 2 alpha  
PAYERBUSINESS 127 alpha  
PAYERADRSTATUS 11 alpha None / Confirmed / Unconfirmed
PAYERADRNAME 32 alpha  
PAYERADRSTREET1 100 alphanumeric  
PAYERADRSTREET2 100 alphanumeric  
PAYERADRCITYNAME 40 alphanumeric  
PAYERADRSTATEORPROVINCE 40 alphanumeric  
PAYERADRPOSTALCODE 20 alphanumeric  
PAYERADRCOUNTRY 2 alphanumeric  
CUSTOM 256 alphanumeric  
INVOICEID 127 alphanumeric  
CONTACTPHONE 12 Mask +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 ePDQ 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 e-Commerce).

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 e-Commerce or via DirectLink.

4.3.1 e-Commerce

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 ePDQ account and go to: "Support > Integration & user manuals > Technical guides > Parameter Cookbook".

If you send us the authorisation/payment request via e-Commerce, 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://mdepayments.epdq.co.uk/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 ePDQ 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 ePDQ 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.

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.

*Call Charges: The following is a guide to call charge information from Business landlines within the UK.

Barclaycard is a trading name of Barclays Bank PLC. Barclays Bank PLC is authorised by the Prudential Regulation Authority and regulated by the Financial Conduct Authority and the Prudential Regulation Authority (Financial Services Register number: 122702). Registered in England. Registered No. 1026167. Registered office: 1 Churchill Place, London E14 5HP

Barclays Bank PLC subscribes to the Lending Code which is monitored and enforced by the Lending Standards Board. Further details can be found at www.lendingstandardsboard.org.uk escape arrow


© Barclaycard 2016