Contents

ECM

PayPal is shown as an additional method of payment on your existing checkout, alongside credit/debit cards.

 

 

Info
Why implement ECM (Express Checkout Mark)?

  • Allows you to integrate PayPal into your existing checkout solution.
  • The address the customer submits on your website is final and cannot be changed on PayPal’s website.

 

Features

Supported customer countries No restrictions on customer countries.
Supported currencies
AUD, CAD, EUR, GBP, JPY, USD
Duplicate checks (opt-in) Supported.
Protect Plus Supported.
Refunds Full and partial refunds supported.
Chargebacks
Disputes are managed by PayPal.

 


 

Process overview

What will the customer see?

  • During the checkout process, your website presents PayPal as a payment method.
  • The customer selects their preferred delivery address on your checkout page and opts to pay using PayPal.
  • The customer is redirected to PayPal, where they sign in using their PayPal credentials (they can register with PayPal if they do not already have an account).
  • The customer reviews their order and agrees to the payment on PayPal’s website.
  • The customer is redirected to your website, where a confirmation is displayed (e.g. “Payment successful”).

 

 

How does it work behind the scenes?

The ECM payment flow can be split into three main parts, as shown below:

1

Initiate the customer

 

2

Redirect to PayPal

 

3

Processing the authorisation

 

Only continue if customer’s browser is successfully redirected back to the returnurl.

 

 


 

1. Initiate the customer

URL

Displaying PayPal on your checkout

The official PayPal acceptance mark must be presented with equal prominence and close proximity to other payment types on your details page. No payment type should be selected by default.

 

 

You can download the latest official PayPal acceptance mark images from this URL:
https://www.paypal.com/uk/webapps/mpp/logo-center

Upon selecting PayPal, card payment fields must be disabled or hidden from view.

When the customer chooses to pay with PayPal, your system will need to perform an ORDER request and interpret the response returned.

 

ORDER request example


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

order = {
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["ORDER"],
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "2001",
    "paymenttypedescription": "PAYPAL",
    "returnurl": "https://yourwebsite.com",
    "cancelurl": "https://yourwebsite.com",
    "paypallocale": "GB",
    "paypaladdressoverride": "1",
    "paypalemail": "billing@email.com"
}

strequest = securetrading.Request()
strequest.update(order)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
    'username' => 'webservices@example.com',
    'password' => 'Password1^'
);

$requestData = array(
    'currencyiso3a' => 'GBP',
    'requesttypedescriptions' => array('ORDER'),
    'accounttypedescription' => 'ECOM',
    'sitereference' => 'test_site12345',
    'baseamount' => '2001',
    'paymenttypedescription' => 'PAYPAL',
    'returnurl' => 'https://yourwebsite.com',
    'cancelurl' => 'https://yourwebsite.com',
    'paypallocale' => 'GB',
    'paypaladdressoverride' => '1',
    'paypalemail' => 'billing@email.com'
);

$api = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["ORDER"],
    "accounttypedescription": "ECOM",
    "sitereference": "test_site12345",
    "baseamount": "2001",
    "paymenttypedescription": "PAYPAL",
    "returnurl": "https://yourwebsite.com",
    "cancelurl": "https://yourwebsite.com",
    "paypallocale": "GB",
    "paypaladdressoverride": "1",
    "paypalemail": "billing@email.com"
}]}'

ORDER response example


{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'responses': [{
      u 'transactionreference': u '72-32-20002',
      u 'paymenttypedescription': u 'PAYPAL',
      u 'settleduedate': u '2016-12-23',
      u 'transactionstartedtimestamp': u '2016-12-23 15:35:40',
      u 'errormessage': u 'Ok',
      u 'accounttypedescription': u 'ECOM',
      u 'errorcode': u '0',
      u 'redirecturl': u 'https://webapp.securetrading.net/cgi-bin/webscr?token=72x32x20002&useraction=commit&cmd=_express-checkout&paypalemail=billing%40email.com',
      u 'requesttypedescription': u 'ORDER',
      u 'settlestatus': u '0',
      u 'operatorname': u 'webservices@example.com',
      u 'livestatus': u '0',
      u 'paypaltoken': u '72x32x20002'
    }]
}
array(3) {
    ["requestreference"] => string(9) "A349bdehj"
    ["version"] => string(4) "1.00"
    ["responses"] =>array(1) {
    [0] => array(13) {
        ["transactionreference"] => string(11) "72-32-20002"
        ["paymenttypedescription"] => string(6) "PAYPAL"
        ["settleduedate" ]=> string(10) "2016-12-23"
        ["transactionstartedtimestamp"] => string(19) "2016-12-23 15:35:40"
        ["errormessage"] => string(2) "Ok"
        ["accounttypedescription"] => string(4) "ECOM"
        ["errorcode"] => string(1) "0"
        ["redirecturl"] => string(137) "https://webapp.securetrading.net/cgi-bin/webscr?token=72x32x20002&useraction=commit&cmd=_express-checkout&paypalemail=billing%40email.com"
        ["requesttypedescription"] => string(5) "ORDER"
        ["settlestatus"] => string(1) "0"
        ["operatorname"] => string(23) "webservices@example.com"
        ["livestatus"] => string(1) "0"
        ["paypaltoken"] => string(11) "72x32x20002"
    }
  }
}
{
  "requestreference": "W23-fjgvn3d8",
  "version": "1.00",
  "response": [{
    "transactionreference": "72-32-20002",
    "paymenttypedescription": "PAYPAL",
    "settleduedate": "2016-12-23",
    "transactionstartedtimestamp": "2016-12-23 15:35:40",
    "errormessage": "Ok",
    "accounttypedescription": "ECOM",
    "errorcode": "0",
    "redirecturl": "https://webapp.securetrading.net/cgi-bin/webscr?token=72x32x20002&useraction=commit&cmd=_express-checkout&paypalemail=billing%40email.com",
    "requesttypedescription": "ORDER",
    "settlestatus": "0",
    "operatorname": "webservices@example.com",
    "livestatus": "0",
    "paypaltoken": "72x32x20002"
  }],
  "secrand": "zO9"
}

 

Field specification

Key

Field name Type Length Request Response Description
accounttypedescription Alpha 20 Only “ECOM” (e-commerce) is supported for PayPal transactions.
baseamount Numeric 13 The amount of the transaction in base units, with no commas or decimal points, so £10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
cancelurl URL 2048 The URL that the customer will be returned to if they cancel the authorisation on their PayPal account.
currencyiso3a Alpha 3 The currency that the transaction will be processed in.

Click here for a full list of available currencies.

customerprefixname Alphanumeric
including
symbols
25 The prefix of the customer’s billing name (e.g. Mr, Miss, Dr).
customerfirstname Alphanumeric
including
symbols
127 The customer’s billing first name.
customermiddlename Alphanumeric
including
symbols
127 The customer’s billing middle name(s).
customerlastname Alphanumeric
including
symbols
127 The customer’s billing last name.
customersuffixname Alphanumeric
including
symbols
25 The customer’s suffix name (e.g. Bsc).
customerpremise Alphanumeric
including
symbols
25 The customer’s house name or number.
customertown Alphanumeric
including
symbols
127 The customer’s town.
customercountryiso2a Alpha 2 The customer’s country. This will need to be in ISO2A format. Click here for a full list of country codes.
customerstreet Alphanumeric
including
symbols
127 The customer’s street name.
customercounty Alphanumeric
including
symbols
127 The customer’s county. For US addresses, the state would be entered in this field. Valid formats:

  • Preferred: Two character state code, e.g. “NY”.
  • Full state name, e.g. “New York”.
customerpostcode Alphanumeric 25 The customer’s postcode or ZIP code.If the country provided is not United States, Great Britain or Canada, or if no country is provided, the postcode field is not validated.
errorcode Numeric 1-5 The error code should be used to determine if the request was successful or not.

  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

orderreference Alphanumeric
including
symbols
255 Your unique order reference that can be stored on Secure Trading’s and PayPal’s system (this is your PayPal invoice ID).

When submitted, please ensure that the order reference is unique to each order.

paymenttypedescription Alpha 20 The value in the request must be “PAYPAL”. This will be returned in the response.
paypaladdressoverride Numeric 1 When using the ECM flow, the delivery address entered on your website is submitted to PayPal and cannot be modified by the customer on PayPal’s website. Please submit one of the following values:

  • 1 – Customer will use the delivery address entered on your website.
  • 2 – Customer will not be prompted to choose a delivery address on PayPal’s website (best suited to online services and downloads).
paypalemail Email 255 The email address that the customer will use to sign in to PayPal. Maximum of 64 characters allowed before the @ symbol.
paypallocale Alpha 2 The language of the PayPal login page.

Click here for a list of PayPal locales.

paypaltoken Alphanumeric 255 The token relates to the customer’s session within PayPal’s system. You should log this, as you can then use it in relation to any relevant queries you may have with PayPal.
redirecturl URL 255 Redirect the customer’s browser to this URL, to allow them to sign in to their PayPal account.
requesttypedescription Alpha 255 The value in the request must be “ORDER”. This will be returned in the response.
returnurl URL 2048 The URL that the customer will be returned to following a successful authorisation on their PayPal account.
sitereference Alphanumeric including
underscore
50 The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.

 

Info

Additional notes about ORDER requests

 

  • The customer name, customer premise, customer town and customer country are required when using PayPal address override option “1”.
  • When PayPal declines a transaction while the customer is on their servers, a message will be displayed on-screen. The customer may be prompted to try again or cancel the payment attempt.
  • You can configure your PayPal account to disable the check on duplicate invoice IDs (values submitted in the orderreference). Contact PayPal Support for further information.


 

2. Redirect to PayPal

After successfully submitting an ORDER request, your system will be returned a redirecturl in the response. Your system will need to redirect the customer’s browser to this URL, which is a page hosted by PayPal, in order to process the payment.

When testing, Secure Trading’s simulated PayPal login page (as shown below) is shown in place of a real PayPal login page.

After logging in to their PayPal account, the customer has the option to continue with the transaction or to cancel. When testing, you can replicate this by using one of the e-mails below on our test PayPal login screen.

 

Email address Scenario Result
auth@auth.com The customer performs a successful transaction. The customer’s browser is redirected to the URL specified in the returnurl that was submitted in the ORDER request.
cancel@cancel.com The customer opts to cancel the transaction. The customer’s browser is redirected to the URL specified in the cancelurl that was submitted in the ORDER request.

 

Clock
You must wait for the customer to return from the PayPal login page to the returnurl hosted on your servers before processing an authorisation.

PayPal simulator


 

3. Processing the authorisation

Status attention
If the customer is redirected to the cancelurl:
Present your customer with alternative payment methods so they can try again.
Status good
If the customer is redirected to the returnurl:
Follow the instructions below.

 

ORDERDETAILS AUTH request example

This example demonstrates how to process an ORDERDETAILS followed by an AUTH request. Notice how the structure of the request is similar to that of a standard AUTH request, except “ORDERDETAILS” is included in the requesttypedescriptions field before “AUTH”.


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

orderdetailsauth = {
    "requesttypedescriptions": ["ORDERDETAILS","AUTH"],
    "sitereference": "test_site12345",
    "parenttransactionreference": "72-32-20002",
    "paymenttypedescription": "PAYPAL",
    "paypaladdressoverride": "1"
}

strequest = securetrading.Request()
strequest.update(orderdetailsauth)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
    'username' => 'webservices@example.com',
    'password' => 'Password1^'
);

$requestData = array(
                'requesttypedescriptions' => array('ORDERDETAILS','AUTH'),
                'sitereference' => 'test_site12345',
                'parenttransactionreference' => '72-32-20002',
                'paymenttypedescription' => 'PAYPAL',
                'paypaladdressoverride' => '1'
);

$api = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
	"alias": "webservices@example.com",
	"version": "1.00",
	"request": [{
                "requesttypedescriptions": ["ORDERDETAILS","AUTH"],
                "sitereference": "test_site12345",
                "parenttransactionreference": "72-32-20002",
                "paymenttypedescription": "PAYPAL",
                "paypaladdressoverride": "1"
		}]
}'

 

ORDERDETAILS AUTH response example

Here is an example of a combined ORDERDETAILS then AUTH response. Notice how the response is divided into two parts; the first represents the “ORDERDETAILS” response and the second represents the “AUTH” response (as indicated by the values of the requesttypedescription fields).


{
  u 'requestreference': u 'A0dcb11e6',
    u 'version': u '1.00',
    u 'responses': [{
      u 'transactionreference': u '72-32-20003',
      u 'merchantname': u 'Test Merchant',
      u 'billinglastname': u 'PAYPALLastName',
      u 'transactionstartedtimestamp': u '2016-12-23 15:36:29',
      u 'paypalpayerstatus': u 'verified',
      u 'parenttransactionreference': u '72-32-20002',
      u 'accounttypedescription': u 'ECOM',
      u 'errorcode': u '0',
      u 'settleduedate': u '2017-05-30',
      u 'billingcountryiso2a': u 'GB',
      u 'paypalpayerid': u 'e018408a43pid',
      u 'paypaladdressstatus': u 'Confirmed',
      u 'billingemail': u 'paypal.email@example.com',
      u 'requesttypedescription': u 'ORDERDETAILS',
      u 'errormessage': u 'Ok',
      u 'billingfirstname': u 'Andru00e9',
      u 'operatorname': u 'webservices@example.com',
      u 'livestatus': u '0',
      u 'settlestatus': u '0'
    }, {
      u 'transactionreference': u '72-32-20004',
      u 'merchantname': u 'Test Merchant',
      u 'paymenttypedescription': u 'PAYPAL',
      u 'authcode': u '44782-D149613359266',
      u 'transactionstartedtimestamp': u '2016-12-23 15:36:31',
      u 'errormessage': u 'Ok',
      u 'parenttransactionreference': u '72-32-20003',
      u 'accounttypedescription': u 'ECOM',
      u 'errorcode': u '0',
      u 'settleduedate': u '2017-05-30',
      u 'currencyiso3a': u 'GBP',
      u 'baseamount': u '2001',
      u 'acquirerresponsecode': u 'None',
      u 'requesttypedescription': u 'AUTH',
      u 'operatorname': u 'webservices@example.com',
      u 'livestatus': u '0',
      u 'settlestatus': u '0'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["responses"] => array(2) {
      [0] => array(19) {
        ["transactionreference"] => string(11) "72-32-20003"
        ["merchantname"] => string(13) "Test Merchant"
        ["billinglastname"] => string(14) "PAYPALLastName"
        ["transactionstartedtimestamp"] => string(19) "2016-12-23 15:36:29"
        ["paypalpayerstatus"] => string(8) "verified"
        ["parenttransactionreference"] => string(11) "72-32-20002"
        ["accounttypedescription"] => string(4) "ECOM"
        ["errorcode"] => string(1) "0"
        ["settleduedate"] => string(10) "2016-12-24"
        ["billingcountryiso2a"] => string(2) "GB"
        ["paypalpayerid"] => string(13) "e018408a43pid"
        ["paypaladdressstatus"] => string(9) "Confirmed"
        ["billingemail"] => string(24) "paypal.email@example.com"
        ["requesttypedescription"] => string(12) "ORDERDETAILS"
        ["errormessage"] => string(2) "Ok"
        ["billingfirstname"] => string(10) "Andru00e9"
        ["operatorname"] => string(23) "webservices@example.com"
        ["livestatus"] => string(1) "0"
        ["settlestatus"] => string(1) "0"
      }
      [1] =>array(17) {
        ["transactionreference"] => string(11) "72-32-20004"
        ["merchantname"] => string(13) "Test Merchant"
        ["paymenttypedescription"] => string(6) "PAYPAL"
        ["authcode"] => string(19) "44782-D149613359266"
        ["transactionstartedtimestamp"] => string(19) "2016-12-23 15:36:31"
        ["errormessage"] => string(2) "Ok"
        ["parenttransactionreference"] => string(11) "72-32-20003"
        ["accounttypedescription"] => string(4) "ECOM"
        ["errorcode"] => string(1) "0"
        ["settleduedate"] => string(10) "2017-05-30"
        ["currencyiso3a"] => string(3) "GBP"
        ["baseamount"] => string(4) "2001"
        ["acquirerresponsecode"] => string(4) "None"
        ["requesttypedescription"] => string(4) "AUTH"
        ["operatorname"] => string(23) "webservices@example.com"
        ["livestatus"] => string(1) "0"
        ["settlestatus"] => string(1) "0"
      }
  }
}
{
  "requestreference": "W23-fjgvn3d8",
  "version": "1.00",
  "response": [{
            "transactionreference": "72-32-20003",
            "merchantname": "Test Merchant",
            "billinglastname": "PAYPALLastName",
            "transactionstartedtimestamp": "2016-12-23 15:36:29",
            "paypalpayerstatus": "verified",
            "parenttransactionreference": "72-32-20002",
            "accounttypedescription": "ECOM",
            "errorcode": "0",
            "settleduedate": "2017-05-30",
            "billingcountryiso2a": "GB",
            "paypalpayerid": "e018408a43pid",
            "paypaladdressstatus": "Confirmed",
            "billingemail": "paypal.email@example.com",
            "requesttypedescription": "ORDERDETAILS",
            "errormessage": "Ok",
            "billingfirstname": "Andru00e9",
            "operatorname": "webservices@example.com",
            "livestatus": "0",
            "settlestatus": "0"
        },
        {
            "transactionreference": "72-32-20004",
            "merchantname": "Test Merchant",
            "paymenttypedescription": "PAYPAL",
            "authcode": "44782-D149613359266",
            "transactionstartedtimestamp": "2016-12-23 15:36:31",
            "errormessage": "Ok",
            "parenttransactionreference": "72-32-20003",
            "accounttypedescription": "ECOM",
            "errorcode": "0",
            "settleduedate": "2017-05-30",
            "currencyiso3a": "GBP",
            "baseamount": "2001",
            "acquirerresponsecode": "None",
            "requesttypedescription": "AUTH",
            "operatorname": "webservices@example.com",
            "livestatus": "0",
            "settlestatus": "0"
  }],
  "secrand": "zO9"
}

 

Field specification

The following table describes the fields required in a combined ORDERDETAILS then AUTH request, and the important fields to check in the response returned.

Info
As the AUTH section of the response follows the same structure as a standard AUTH response, most of the fields returned in the AUTH response have been omitted from the below. Click here for the full AUTH specification.

Key

Field name Type Length Request Response Description
errorcode Numeric 1-5 The error code should be used to determine if the request was successful or not.

  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

parenttransactionreference Alphanumeric
including
hyphens
25 In the request, this is the transactionreference of the preceding ORDER.

This field is returned in both sections of the response, referring to previous requests processed in the sequence.

paymenttypedescription Alpha 20 The value in the request must be “PAYPAL”. This will be returned in the response.
paypaladdressoverride Numeric 1 Must be the same value submitted in the ORDER request.
paypaladdressstatus Alpha 25 The status of the address with PayPal. Either “Confirmed” or “Unconfirmed”.
paypalpayerid Alphanumeric 255 Unqiue PayPal customer account number.
paypalpayerstatus Alpha 25 The status of the payer with PayPal. Either “verified” or “unverified”.
requesttypedescriptions Alpha 255 Submit “ORDERDETAILS” and “AUTH”, as shown in the request example above.
settlestatus Numeric 3 This field is used to determine the transaction status. Click here for further information on the settlestatus field and the settlement process for PayPal.
sitereference Alphanumeric
including underscore
50 The site reference identifies your Secure Trading account.

 


Info
Additional notes

  • You cannot perform tokenisation with PayPal.
  • The PayPal fields returned are defined by PayPal. These are correct at time of writing, but may be subject to change.