PayPal is an international e-commerce business allowing payments and money transfers to be made online.
Express Checkout Shortcut (ECS): Customers click the “Check out with PayPal” button on your website and are redirected to PayPal’s servers.
| Supported customer countries | No restrictions on customer countries. |
| Supported currencies | AUD, CAD, EUR, GBP, JPY, USD |
| Refunds |
Full and partial refunds permitted. |
| Chargebacks |
Disputes are managed by PayPal. |
| Zero-authorisation |
Not supported. |
| Recurring payments |
Not supported. |
Benefits of implementing ECS
- The customer does not need to type in their delivery address. They can use the details saved on their PayPal account.
- Simplifying the checkout experience can help increase both your online and mobile conversion rates.
- Allows you to append a delivery charge to the transaction that can differ based on the delivery address selected by the customer while on PayPal’s website.
Process overview
What will the customer see?
- On your basket page, your website offers the customer the ability to check out using PayPal.
- The customer clicks the button and 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 selects their preferred delivery address and payment method on PayPal’s website.
- The customer is redirected back to your website, where you can add additional delivery charges and display a final summary with the total amount shown.
- The customer agrees to the payment on your website and is shown a confirmation of purchase.
How does it work behind the scenes?
The ECS payment flow can be split into four main parts, as shown below:
1. Initiate the customer 
2. Redirect to PayPal
3. Retrieve order details
Only continue if customer's browser is successfully redirected back to the returnurl.
4. Processing the authorisation
1. Initiate the customer
You will need to provide the customer with the option to check out with PayPal.
Displaying PayPal on your checkout
PayPal provides a button you can add to your website, along with guidelines and how it should be used.
Click here to download the latest official “Check out with PayPal” buttons (link to external site).
The “Check out with PayPal” button must take the customer directly to PayPal without any deviations or intermediate steps and return to your website afterwards. The customer must not be required to sign in to a store account prior to purchase. In addition, the button should:
- Be placed directly below or next to each of your own checkout buttons.
- Be placed above the fold (visible without needing to scroll).
- Have alternative text “Checkout with PayPal” for cases where the image isn’t loaded in the customer’s browser.
These guidelines are outlined by PayPal and are subject to change.
When the customer clicks the “Check out with PayPal” button, 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",
"requesttypedescription": "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',
'requesttypedescription' => '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 = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
?>curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
"currencyiso3a": "GBP",
"requesttypedescription": "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"
}]
}'{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"currencyiso3a":"GBP",
"requesttypedescription":"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"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="ORDER">
<merchant>
<returnurl>https://www.example.com/return</returnurl>
<cancelurl>https://www.example.com/cancel</cancelurl>
</merchant>
<billing>
<amount currencycode="GBP">2001</amount>
<payment type="PAYPAL">
<locale>GB</locale>
<paypaladdressoverride>0</paypaladdressoverride>
<paypalemail>billing@email.com</paypalemail>
</payment>
</billing>
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</request>
</requestblock>Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
| Field | Format | Description | |
 |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | Only “ECOM” (e-commerce) is supported. |
|
baseamount XPath: /billing/amount |
Numeric (11) | 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 XPath: /merchant/cancelurl |
URL (2048) | The URL that the customer will be returned to if they cancel the authorisation on their PayPal account. |
|
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction will be processed in (in ISO3A format).
For a list of currency codes supported by PayPal, refer to the list found at the top of this page. |
 |
customerprefixname XPath: /customer/name/prefix |
Alphanumeric including symbols (25) |
The prefix of the customer’s billing name (e.g. Mr, Miss, Dr). At least one of the customer name fields must be submitted if paypaladdressoverride is set to "0" or "1". Otherwise, these fields are optional. |
| customerfirstname XPath: /customer/name/first |
Alphanumeric including symbols (127) |
The customer’s billing first name. At least one of the customer name fields must be submitted if paypaladdressoverride is set to "0" or "1". Otherwise, these fields are optional. |
|
| customermiddlename XPath: /customer/name/middle |
Alphanumeric including symbols (127) |
The customer’s billing middle name(s). At least one of the customer name fields must be submitted if paypaladdressoverride is set to "0" or "1". Otherwise, these fields are optional. |
|
| customerlastname XPath: /customer/name/last |
Alphanumeric including symbols (127) |
The customer’s billing last name. At least one of the customer name fields must be submitted if paypaladdressoverride is set to "0" or "1". Otherwise, these fields are optional. |
|
| customersuffixname XPath: /customer/name/suffix |
Alphanumeric including symbols (25) |
The customer’s suffix name (e.g. Bsc). At least one of the customer name fields must be submitted if paypaladdressoverride is set to "0" or "1". Otherwise, these fields are optional. |
|
|
customerpremise XPath: /customer/premise |
Alphanumeric including symbols (25) |
The customer’s house name or number. These customer address fields are required if paypaladdressoverride is set to "0" or "1". Otherwise, these fields are optional. |
| customertown XPath: /customer/town |
Alphanumeric including symbols (127) |
The customer’s town. These customer address fields are required if paypaladdressoverride is set to "0" or "1". Otherwise, these fields are optional. |
|
| customercountryiso2a XPath: /customer/country |
Alpha (2) |
The customer’s country. This will need to be in ISO2A format. Click here for a full list of country codes. These customer address fields are required if paypaladdressoverride is set to "0" or "1". Otherwise, these fields are optional. |
|
 |
customerstreet XPath: /customer/street |
Alphanumeric including symbols (127) | The customer’s street name. |
|
customercounty XPath: /customer/county |
Alphanumeric including symbols (127) |
The customer’s county. For US addresses, the state would be entered in this field. Valid formats:
Required if customercountryiso2a is one of the following: AR, BR, CA, CN, ID, IN, IT, JP, MX, TH, US |
|
customerpostcode XPath: /customer/postcode |
Alphanumeric (25) | The customer’s postcode or ZIP code.
This must be a valid postcode/ZIP code for the customercountryiso2a submitted. |
|
orderreference XPath: /merchant/orderreference |
Alphanumeric including symbols (25)
Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction. |
Your unique order reference that can be stored on Trust Payments and PayPal’s system (this is your PayPal invoice ID).
When submitted, please ensure that the order reference is unique to each order. |
|
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value must be submitted as “PAYPAL”. |
|
paypaladdressoverride XPath: /billing/payment/paypaladdressoverride |
Numeric (1) |
Allows you to override the delivery address chosen by the customer on PayPal:
|
|
paypalemail XPath: /billing/payment/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 XPath: /billing/payment/locale |
Alpha (2) | The language of the PayPal login page.
Click here for a list of PayPal locales (link to external site). |
|
paypalmaxbaseamount XPath: /billing/payment/paypalmaxbaseamount |
Numeric (11) | The expected maximum total amount of the complete order, including shipping cost and tax charges. PayPal uses this value to validate the buyer’s funding source. Must be in base units. For further information on this field, please refer to PayPal’s own specification. |
|
requesttypedescription XPath: /@type |
Alpha (20) | The value in the request must be “ORDER”. |
|
returnurl XPath: /merchant/returnurl |
URL (2048) | The URL that the customer will be returned to following a successful authorisation on their PayPal account. |
|
sitereference XPath: /operation/sitereference |
Alphanumeric & 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. |
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 '2020-06-01',
u 'transactionstartedtimestamp': u '2020-06-01 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) "2020-06-01"
["transactionstartedtimestamp"] => string(19) "2020-06-01 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":"2020-06-01",
"transactionstartedtimestamp":"2020-06-01 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"
}
<responseblock version="3.67">
<requestreference>X62d3qhev</requestreference>
<response type="ORDER">
<merchant>
<operatorname>webservices@example.com</operatorname>
</merchant>
<transactionreference>72-32-20002</transactionreference>
<billing>
<payment type="PAYPAL"/>
</billing>
<timestamp>2020-06-01 15:35:40</timestamp>
<paypal>
<redirecturl>https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&useraction=commit&cmd=_express-checkout&paypalemail=billing%40email.com</redirecturl>
<token>56604A14170900854600</token>
</paypal>
<settlement>
<settleduedate>2020-06-01</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<live>1</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</response>
<secrand>SO</secrand>
</responseblock>
Field specification
| Field | Format | Description | |
 |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | The value returned is “ECOM”. |
|
errorcode XPath: /error/code |
Numeric (1-5) |
The error code should be used to determine if the request was successful or not.
|
|
errordata XPath: /error/data |
Alphanumeric (255) |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
|
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
|
livestatus XPath: /live |
Numeric (1) |
|
|
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
|
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | The value returned is “PAYPAL”. |
|
paypaltoken XPath: /paypal/token |
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 XPath: /paypal/redirecturl |
URL (255) | Redirect the customer’s browser to this URL, to allow them to sign in to their PayPal account. |
|
requesttypedescription XPath: /@type |
Alpha (20) | The value returned is “ORDER”. |
|
settleduedate XPath: /settlement/settleduedate |
Date YYYY-MM-DD | The date on which the transaction will be settled. |
|
settlestatus XPath: /settlement/settlestatus |
Numeric (3) |
|
|
transactionreference XPath: /transactionreference |
Alphanumeric including hyphens (25) |
A unique reference for the request assigned by Trust Payments. |
|
transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the request was processed. |
Additional notes about ORDER requests
- The customer name, customer premise, customer town and customer country are required when using PayPal address override options “0” or “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, our 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. |
You must wait for the customer to return from the PayPal login page to the returnurl hosted on your servers before processing an authorisation.
3. Retrieve order details
If the customer is redirected to the cancelurl:
Present your customer with alternative payment methods so they can try again.
If the customer is redirected to the returnurl:
Follow the instructions below.
ORDERDETAILS request example
Here is an example of an ORDERDETAILS request. This request retrieves the address information entered by the customer while on PayPal’s servers, and returns this in an ORDERDETAILS response.
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
orderdetails = {
"requesttypedescription": "ORDERDETAILS",
"sitereference": "test_site12345",
"parenttransactionreference": "72-32-20002"
}
strequest = securetrading.Request()
strequest.update(orderdetails)
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(
'requesttypedescription' => array'ORDERDETAILS',
'sitereference' => 'test_site12345',
'parenttransactionreference' => '72-32-20002'
);
$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
?>curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
"requesttypedescription": "ORDERDETAILS",
"sitereference": "test_site12345",
"parenttransactionreference": "72-32-20002"
}]
}'{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescription":"ORDERDETAILS",
"sitereference":"test_site12345",
"parenttransactionreference":"72-32-20002"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="ORDERDETAILS">
<operation>
<sitereference>test_site12345</sitereference>
<parenttransactionreference>72-32-20002</parenttransactionreference>
</operation>
</request>
</requestblock>Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
| Field | Format | Description | |
|
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
Submit the transactionreference of the preceding ORDER response. This will come from the redirect from PayPal. |
|
requesttypedescription XPath: /@type |
Alpha (20) | The value in the request must be “ORDERDETAILS”. |
|
sitereference XPath: /operation/sitereference |
Alphanumeric & 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. |
ORDERDETAILS response
You must use the information returned in the ORDERDETAILS response to display a page to the customer on your website that summarises the order. The customer can use this page to review their order and confirm they would like to proceed, in which case your system would submit an AUTH request, as described below.
Best practice guidelines
- The customer should be able to complete the purchase in two or fewer steps after being redirected to your website from PayPal’s checkout pages.
- The customer must not be required to manually enter additional information on the review page that is available via the PayPal APIs.
On the aforementioned review order page, the following information should be presented to the customer before completing the purchase:
- PayPal as the selected payment method.
- Delivery address and email address from PayPal (found in the ORDERDETAILS response).
- The total amount to be paid by the customer, including any additional delivery charges added to the initial transaction amount (if applicable). See below for further information on delivery charges.
About delivery charges
Once your system has received the ORDERDETAILS response, you should now be in possession of the customer’s delivery address (if you intend on shipping a physical product). At this point, you are permitted to append a delivery charge to the transaction cost.
Regardless of any delivery charges, you must present the total cost to the customer and they must agree to this final amount before the payment is processed. We recommend separating the cost of the product(s) from the cost of delivery, so the customer can better understand how the amount was calculated.
Once the customer agrees to the payment, your system can process an AUTH request with this final amount submitted in the baseamount field (as described below). This total amount, including any additional delivery charges, should not exceed the paypalmaxbaseamount value (if submitted in the ORDER request).
The additional charge applied to cover the delivery costs is decided by you. Generally speaking, there are three approaches to calculating the delivery charge:
- Free delivery – You opt not to add any additional fees to the cost of the product and your business will cover the cost of the delivery.
- Fixed delivery price – You opt to add the same delivery charge to every order. This works best when you ensure the aforementioned charge has the same value as the average delivery cost across all of your orders.
- Charge the exact cost (using real-time rates) – Now you have the customer’s delivery address, and the size and weight of the delivery, you can contact your shipping partner and calculate the exact delivery cost and present this to the customer prior to completing the payment.
Here is an example of an ORDERDETAILS response:
{
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 '2020-06-01 15:36:00',
u 'paypalpayerstatus': u 'verified',
u 'parenttransactionreference': u '72-32-20002',
u 'accounttypedescription': u 'ECOM',
u 'errorcode': u '0',
u 'settleduedate': u '2020-06-01',
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'
}]
}array(3) {
["requestreference"] => string(9) "A58cdfkpy"
["version"] => string(4) "1.00"
["responses"] => array(1) {
[0] => array(19) {
["transactionreference"] => string(11) "72-32-20003"
["merchantname"] => string(13) "Test Merchant"
["billinglastname"] => string(14) "PAYPALLastName"
["transactionstartedtimestamp"] => string(19) "2020-06-01 15:36:00"
["paypalpayerstatus"] => string(8) "verified"
["parenttransactionreference"] => string(11) "72-32-20002"
["accounttypedescription"] => string(4) "ECOM"
["errorcode"] => string(1) "0"
["settleduedate"] => string(10) "2020-06-01"
["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"
}
}
}{
"requestreference":"W23-fjgvn3d8",
"version":"1.00",
"response":[{
"transactionreference":"72-32-20003",
"merchantname":"Test Merchant",
"billinglastname":"PAYPALLastName",
"transactionstartedtimestamp":"2020-06-01 15:36:00",
"paypalpayerstatus":"verified",
"parenttransactionreference":"72-32-20002",
"accounttypedescription":"ECOM",
"errorcode":"0",
"settleduedate":"2020-06-01",
"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"
}],
"secrand":"zO9"
}
<responseblock version="3.67">
<requestreference>X538160153</requestreference>
<response type="ORDERDETAILS">
<merchant>
<merchantname>My Test Site</merchantname>
<operatorname>webservices@example.com</operatorname>
</merchant>
<customer>
<town>PAYPAL City</town>
<county>MI</county>
<street>MORE STREET</street>
<name>
<last>PayPalShipToName</last>
</name>
<premise>1 PayPalStreet</premise>
<country>US</country>
</customer>
<transactionreference>72-32-20003</transactionreference>
<billing>
<name>
<last>PAYPALLastName</last>
</name>
<country>GB</country>
<email>paypal.email@example.com</email>
<telephone type="M">0777777777</telephone>
</billing>
<timestamp>2020-06-01 15:36:00</timestamp>
<paypal>
<addressstatus>Confirmed</addressstatus>
<payerstatus>verified</payerstatus>
<payerid>4d22e2606apid</payerid>
</paypal>
<settlement>
<settleduedate>2020-06-01</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<live>1</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<operation>
<parenttransactionreference>72-32-20002</parenttransactionreference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</response>
<secrand>bt</secrand>
</responseblock>
Field specification
The following table describes the fields most important fields to check in the response returned:
| Field | Format | Description | |
 |
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | The value returned is “ECOM”. |
|
errorcode XPath: /error/code |
Numeric (1-5) |
The error code should be used to determine if the request was successful or not.
|
 |
errordata XPath: /error/data |
Alphanumeric (255) |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
|
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
|
livestatus XPath: /live |
Numeric (1) |
|
|
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. Depends on your account configuration. |
|
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
|
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
The transactionreference of the preceding ORDER response. |
|
paypaladdressstatus XPath: /paypal/addressstatus |
Alpha (25) | The status of the address with PayPal. Either “Confirmed” or “Unconfirmed”. |
|
paypalpayerid XPath: /billing/payment/payerid |
Alphanumeric (255) | Unqiue PayPal customer account number. |
|
paypalpayerstatus XPath: /paypal/payerstatus |
Alpha (25) | The status of the payer with PayPal. Either “verified” or “unverified”. |
|
requesttypedescription XPath: /@type |
Alpha (20) | The value returned is “ORDERDETAILS”. |
|
settleduedate XPath: /settlement/settleduedate |
Date YYYY-MM-DD | The date on which the transaction will be settled. |
|
settlestatus XPath: /settlement/settlestatus |
Numeric (3) |
|
|
transactionreference XPath: /transactionreference |
Alphanumeric including hyphens (25) |
A unique reference for the request assigned by Trust Payments. |
|
transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the request was processed. |
Additional notes about ORDERDETAILS responses
- The billing and customer details returned may be different to those submitted in the initial ORDER request. This can occur when the customer uses different details when logged in to PayPal’s servers (and paypaladdressoverride is set to “0”).
- The PayPal fields returned are defined by PayPal. These are correct at time of writing, but may be subject to change.
4. Processing the authorisation
After the customer has confirmed they would like to continue with the payment, your system will need to perform an AUTH request and interpret the response returned.
AUTH request example
Here is an example of a PayPal AUTH request. Notice how the structure is similar to a standard AUTH request, except for the exclusion of most of the payment, billing and delivery details, because these are inherited from the previous requests. Please ensure the parenttransactionreference field is submitted, containing the unique transaction reference of the preceding ORDERDETAILS request.
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
auth = {
"requesttypedescription": "AUTH",
"sitereference": "test_site12345",
"parenttransactionreference": "72-32-20003",
"paymenttypedescription": "PAYPAL",
"paypaladdressoverride": "1"
}
strequest = securetrading.Request()
strequest.update(auth)
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(
'requesttypedescription' => 'AUTH',
'sitereference' => 'test_site12345',
'parenttransactionreference' => '72-32-20003',
'paymenttypedescription' => 'PAYPAL',
'paypaladdressoverride' => '1'
);
$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
?>curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "webservices@example.com",
"version": "1.00",
"request": [{
"requesttypedescription": "AUTH",
"sitereference": "test_site12345",
"parenttransactionreference": "72-32-20003",
"paymenttypedescription": "PAYPAL",
"paypaladdressoverride": "1"
}]
}'{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescription":"AUTH",
"sitereference":"test_site12345",
"parenttransactionreference":"72-32-20003",
"paymenttypedescription":"PAYPAL",
"paypaladdressoverride":"1"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<operation>
<sitereference>test_site12345</sitereference>
<parenttransactionreference>72-32-20003</parenttransactionreference>
</operation>
<billing>
<payment type="PAYPAL">
<paypaladdressoverride>0</paypaladdressoverride>
</payment>
</billing>
</request>
</requestblock>Replace <DOMAIN> with a supported domain. Click here for a full list.
Field specification
| Field | Format | Description | |
|
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
Submit the transactionreference returned in the preceding ORDERDETAILS response. |
|
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | This value must be submitted as “PAYPAL”. |
|
paypaladdressoverride XPath: /billing/payment/paypaladdressoverride |
Numeric (1) | Must be the same value submitted in the ORDER request. |
|
requesttypedescription XPath: /@type |
Alpha (20) | The value in the request must be “AUTH”. |
|
sitereference XPath: /operation/sitereference |
Alphanumeric & 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. |
AUTH response example
Here is an example of a PayPal AUTH response. The structure is similar to a standard AUTH response, except for the inclusion of additional PayPal-specific fields.
{
u 'requestreference': u 'A0dcb11e6',
u 'version': u '1.00',
u 'responses': [{
u 'transactionreference': u '72-32-20004',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'PAYPAL',
u 'authcode': u '44782-D149613359266',
u 'transactionstartedtimestamp': u '2020-06-01 15:36:20',
u 'errormessage': u 'Ok',
u 'parenttransactionreference': u '72-32-20003',
u 'accounttypedescription': u 'ECOM',
u 'errorcode': u '0',
u 'settleduedate': u '2020-06-01',
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(1) {
[0] =>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) "2020-06-01 15:36:20"
["errormessage"] => string(2) "Ok"
["parenttransactionreference"] => string(11) "72-32-20003"
["accounttypedescription"] => string(4) "ECOM"
["errorcode"] => string(1) "0"
["settleduedate"] => string(10) "2020-06-01"
["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-20004",
"merchantname":"Test Merchant",
"paymenttypedescription":"PAYPAL",
"authcode":"44782-D149613359266",
"transactionstartedtimestamp":"2020-06-01 15:36:20",
"errormessage":"Ok",
"parenttransactionreference":"72-32-20003",
"accounttypedescription":"ECOM",
"errorcode":"0",
"settleduedate":"2020-06-01",
"currencyiso3a":"GBP",
"baseamount":"2001",
"acquirerresponsecode":"None",
"requesttypedescription":"AUTH",
"operatorname":"webservices@example.com",
"livestatus":"0",
"settlestatus":"0"
}],
"secrand":"zO9"
}
<responseblock version="3.67">
<requestreference>X538160153</requestreference>
<response type="AUTH">
<merchant>
<merchantname>My Test Site</merchantname>
<operatorname>webservices@example.com</operatorname>
</merchant>
<transactionreference>72-32-20004</transactionreference>
<timestamp>2020-06-01 15:36:20</timestamp>
<acquirerresponsecode>None</acquirerresponsecode>
<operation>
<parenttransactionreference>72-32-20003</parenttransactionreference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<settlement>
<settleduedate>2020-06-01</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<billing>
<amount currencycode="GBP">2001</amount>
<payment type="PAYPAL"/>
</billing>
<authcode>83154-D140912749345</authcode>
<live>1</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
</response>
<secrand>LLq</secrand>
</responseblock>
Field specification
| Field | Format | Description | |
|
accounttypedescription XPath: /operation/accounttypedescription |
Alpha (20) | The value returned is “ECOM”. |
|
acquirerresponsecode XPath: /acquirerresponsecode |
Alphanumeric (255) | Used by your acquirer to indicate the outcome of the request. |
|
authcode XPath: /authcode |
Alphanumeric (255) |
The authorisation code provided by the issuing bank. Only returned if the transaction is authorised. |
|
baseamount XPath: /billing/amount |
Numeric (11) | The amount of the transaction in base units, with no commas or decimal points, so €10 is returned as 1000. |
|
currencyiso3a XPath: /billing/amount/@currencycode |
Alpha (3) | The currency that the transaction was processed in (in ISO3A format).
For a list of currency codes supported by PayPal, refer to the list found at the top of this page. |
|
errorcode XPath: /error/code |
Numeric (1-5) |
The error code should be used to determine if the request was successful or not.
|
|
errordata XPath: /error/data |
Alphanumeric (255) |
Additional information to help troubleshoot the error. Only returned if there has been an error. |
|
errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. |
|
livestatus XPath: /live |
Numeric (1) |
|
|
merchantname XPath: /merchant/merchantname |
Alphanumeric (255) | These are details associated with the account used to process the transaction.
To amend these fields, please contact our Support Team. Depends on your account configuration. |
|
operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. |
|
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
The transactionreference of the preceding ORDERDETAILS response. |
|
paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | The value returned is “PAYPAL”. |
|
requesttypedescription XPath: /@type |
Alpha (20) | The value returned is “AUTH”. |
|
settleduedate XPath: /settlement/settleduedate |
Date YYYY-MM-DD | The date on which the transaction will be settled. |
|
settlestatus XPath: /settlement/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. |
|
transactionreference XPath: /transactionreference |
Alphanumeric including hyphens (25) |
A unique reference for the request assigned by Trust Payments. |
|
transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the request was processed. |
You cannot perform tokenisation with PayPal.