PayPal for Webservices API (Pilot)

Guidance for established merchants migrating to the new PayPal platform

Trust Payments has recently added support for integration with PayPal's latest platform. This is to ensure continued compatibility with new PayPal features and enable a more streamlined onboarding process for new merchants.

Established Trust Payments merchants who are already transacting with PayPal will be required to take the following steps to continue using PayPal going forward:

You will need to be onboarded onto the new PayPal platform. This is a simplified process where you will be emailed a link to agree to new terms and grant Trust Payments the permissions needed to link to your PayPal account.
PayPal mandates that you update the ORDER request submitted to our API to include additional information on all products in the customer's order.

Each ORDER request will now require the following fields to be submitted:
- products containing an array of JSON objects, each containing the following fields for each product in the customer's order:
  - productmainamount - The price per product.
  - productcurrencyiso3a - The currency associated with the product price.
  - productquantity - The quantity of the product in the order.
  - producttitle - The name of the product.
For full field specifications, please select between the ECM and ECS tabs below and scroll to the relevant section describing the request/response you need to work with.
Merchants operating in certain sectors that PayPal deems to be high risk will also need to update the ORDER request to submit the following additional fields:
- The products array above must also include the following additional fields for each product in the customer's order:
  - productcode - The Stock Keeping Unit (SKU) of the product.
  - productdescription - A description of the product.
  - producttaxmainamount - The tax applied to the product.
  - producttaxcurrencyiso3a - The currency associated with the tax applied.
  - producttype - Choose a product type from "digital", "physical" or "gift".
- paypaltransactionriskcontextdata containing an array of JSON objects, each containing the fields paypaltransactionriskcontextdatakey and paypaltransactionriskcontextdatavalue.
You can now submit the shipping amount to Trust Payments during the checkout process.
- If you know the final shipping amount at the start of the order, this should be submitted in the ORDER request using the customershippingbaseamount field. Doing so provides the customer with a better user experience by displaying the shipping amount on PayPal's website before they agree to the purchase.
- If you are using ECS flow, you can parse the ORDERDETAILS response for the customer's delivery address and use this to calculate the shipping amount. This can then be submitted in the AUTH request using the customershippingbaseamount field.
- Remember that while submitting the shipping amount is recommended, it is not required. For example, you won't be forced to submit a shipping amount for digital purchases that don't require shipping.
When parsing the ORDERDETAILS response, you will need to be aware that the PayPal address and payer status is no longer verified on the new platform (these checks have been deprecated), and as such paypaladdressstatus will always return "Unconfirmed" and paypalpayerstatus will always return "unverified".

The overall flow of requests sent / responses received remains unchanged. This allows you to make updates to your existing implementation without the need to start from scratch.

We recommend you first deploy these changes to a staging environment and test your integration before deploying to a production environment. As part of this process, your test site can be configured to connect to PayPal's sandbox environment to more accurately represent the customer journey while testing.

In particular, you should ensure you understand the new Pay Later options that can now be displayed when the customer is redirected to PayPal and ensure your solution accounts for this.

Click here to learn more (external link)

PayPal is an international e-commerce business allowing payments and money transfers to be made online.

Supported customer countries	No restrictions on customer countries.
Supported currencies	AUD, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD, USD
Refunds	Full and partial refunds permitted.
Chargebacks	Disputes are managed by PayPal.
Zero-authorisation	Not supported.
Recurring payments	Not supported.

We support two PayPal transaction flows:

Use the tabs above to change the workflow.

The below covers Express Checkout Mark (ECM)

Express Checkout Mark (ECM) - PayPal is shown as an additional method of payment on your existing checkout, alongside credit/debit cards.

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”).

Pay Later

During the time that the customer's browser has been redirected away to pages hosted by PayPal, PayPal is in control of the checkout experience. To enable customers to spread the cost of larger purchases, PayPal may display additional finance options for transactions that meet their requirements to do so.

Click here to learn more (external link)

First steps

Requirements

Before you can process live PayPal transactions, you will need to have a PayPal Business Account. If you do not already have a Business Account, you will be prompted to register a new account as part of the onboarding process we outline below.
PayPal does not support their hosted pages being rendered within an iframe. Instead, you must always redirect the customer's browser to PayPal during the checkout session.

For some industries (such as Travel, Gaming and Events), PayPal requires additional information called Set Transaction Context (STC). Such information can be included in your requests to Trust Payments and these will be passed onto PayPal as necessary. Please contact our Support Team for further information.

PayPal onboarding

Contact our Support Team and enquire about enabling PayPal on your TRU Connect account.
Our Support Team will provide you with a URL to complete the setup.
Navigate directly to the URL in your browser and sign in with your PayPal Business Account.

If you haven't already registered a PayPal Business Account, you will be prompted to do so as part of onboarding.
You will be presented with a list of permissions that you will need to grant us in order to complete the setup. Read these carefully and click "Accept" to continue.
After you have granted the necessary permissions, PayPal will perform additional verification checks on your account. If you have not already done so, you then may be prompted to validate the email address associated with your PayPal account.
Once the above has been performed, a request will automatically be sent from PayPal to Trust Payments to activate PayPal on your site reference and the boarding process is complete. We will confirm via email when your site reference is enabled to process PayPal transactions.

If you have any queries regarding the status of your PayPal onboarding, please contact our Support Team.

Overview of ECM

Initiate the customer
- Customer enters their preferred delivery address on the merchant's website and selects to pay with PayPal.
- Merchant submits ORDER request to initiate the session, including cancelurl and returnurl.
- Merchant receives ORDER response, including paypaltoken and redirecturl.
Redirect to PayPal
- Merchant redirects the customer's browser to the redirecturl, including the paypaltoken.
- Customer signs in and confirms their preferred delivery address and payment method on PayPal’s website, and agrees to perform the payment.
- If successful, the customer's browser is redirected to the returnurl.
- If the PayPal order is cancelled, the browser is redirected to the cancelurl where an error message can be displayed. We recommend that alternative payment methods are displayed, allowing the customer to try again.
Process the authorisation
- Only if the above has been successful, the merchant submits combined ORDERDETAILS and AUTH request to process the payment.
- Merchant receives ORDERDETAILS AUTH response and displays receipt page to the customer.
Payment completion
- Under default behaviour, the transaction is in a pending state and funds will typically settle within 24 hours.
- But if preferred, merchants can configure their setup to instead request funds are settled immediately. Or alternatively, settlement can be deferred for up to 7 days.
- Once settlement has been completed, Trust Payments will submit a URL notification (if enabled) to the merchant’s system as confirmation. Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.

1. Initiate the customer

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 (link to external site)
Upon selecting PayPal, card payment fields must be disabled or hidden from view.

Processing ORDER

The ORDER request is used to initiate the order with PayPal.

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

ORDER Request (ECM)

#!/usr/bin/python
import securetrading

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

order = {
  "accounttypedescription": "ECOM",
  "baseamount": "2150",
  "cancelurl": "https://yourwebsite.com",
  "currencyiso3a": "GBP",
  "customercountryiso2a": "GB",
  "customerfirstname": "Jay",
  "customerlastname": "Doe",
  "customerpostcode": "TR45 6ST",
  "customerprefixname": "Mr",
  "customerpremise": "123 Trust Lane",
  "customertown": "Bangor",
  "paymenttypedescription": "PAYPAL",
  "paypaladdressoverride": "1",
  "products":
  [{
    "productbaseamount": "200",
    "productcurrencyiso3a": "GBP",
    "productquantity": "5",
    "producttitle": "Item 1"
  },
  {
    "productbaseamount": "500",
    "productcurrencyiso3a": "GBP",
    "productquantity": "1",
    "producttitle": "Item 2"
  }],
  "requesttypedescription": "ORDER",
  "returnurl": "https://yourwebsite.com",
  "sitereference": "test_site12345"
}

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(
  'accounttypedescription' => 'ECOM',
  'baseamount' => '2150',
  'cancelurl' => 'https://yourwebsite.com',
  'currencyiso3a' => 'GBP',
  'customercountryiso2a' => 'GB',
  'customerfirstname' => 'Jay',
  'customerlastname' => 'Doe',
  'customerpostcode' => 'TR45 6ST',
  'customerprefixname' => 'Mr',
  'customerpremise' => '123 Trust Lane',
  'customertown' => 'Bangor',
  'paymenttypedescription' => 'PAYPAL',
  'paypaladdressoverride' => '1',
  'products' =>
  [[
    'productbaseamount' => '200',
    'productcurrencyiso3a' => 'GBP',
    'productquantity' => '5',
    'producttitle' => 'Item 1'
  ], 
  [
    'productbaseamount' => '500',
    'productcurrencyiso3a' => 'GBP',
    'productquantity' => '1',
    'producttitle' => 'Item 2'
  ]], 
  'requesttypedescription' => 'ORDER',
  'returnurl' => 'https://yourwebsite.com',
  'sitereference' => 'test_site12345'
);

$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": [{
    "accounttypedescription": "ECOM",
    "baseamount": "2150",
    "cancelurl": "https://yourwebsite.com",
    "currencyiso3a": "GBP",
    "customercountryiso2a": "GB",
    "customerfirstname": "Jay",
    "customerlastname": "Doe",
    "customerpostcode": "TR45 6ST",
    "customerprefixname": "Mr",
    "customerpremise": "123 Trust Lane",
    "customertown": "Bangor",
    "paymenttypedescription": "PAYPAL",
    "paypaladdressoverride": "1",
    "products":
    [{
      "productbaseamount": "200",
      "productcurrencyiso3a": "GBP",
      "productquantity": "5",
      "producttitle": "Item 1"
    },
    {
      "productbaseamount": "500",
      "productcurrencyiso3a": "GBP",
      "productquantity": "1",
      "producttitle": "Item 2"
    }],
  "requesttypedescription": "ORDER",
  "returnurl": "https://yourwebsite.com",
  "sitereference": "test_site12345"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accounttypedescription": "ECOM",
    "baseamount": "2150",
    "cancelurl": "https://yourwebsite.com",
    "currencyiso3a": "GBP",
    "customercountryiso2a": "GB",
    "customerfirstname": "Jay",
    "customerlastname": "Doe",
    "customerpostcode": "TR45 6ST",
    "customerprefixname": "Mr",
    "customerpremise": "123 Trust Lane",
    "customertown": "Bangor",
    "paymenttypedescription": "PAYPAL",
    "paypaladdressoverride": "1",
    "products":
    [{
      "productbaseamount": "200",
      "productcurrencyiso3a": "GBP",
      "productquantity": "5",
      "producttitle": "Item 1"
    },
    {
      "productbaseamount": "500",
      "productcurrencyiso3a": "GBP",
      "productquantity": "1",
      "producttitle": "Item 2"
    }],
    "requesttypedescription": "ORDER",
    "returnurl": "https://yourwebsite.com",
    "sitereference": "test_site12345"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="ORDER">
    <billing>
      <amount currencycode="GBP">2150</amount>
      <payment type="PAYPAL">
        <paypaladdressoverride>1</paypaladdressoverride>
      </payment>
    </billing>
    <customer>
      <country>GB</country>
      <name>
        <first>Jay</first>
        <last>Doe</last>
        <prefix>Mr</prefix>
      </name>
      <postcode>TR45 6ST</postcode>
      <premise>123 Trust Lane</premise>
      <town>Bangor</town>
    </customer>
    <merchant>
      <cancelurl>https://www.example.com/cancel</cancelurl>
      <returnurl>https://www.example.com/return</returnurl>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
      <products>
        <amount currencycode="GBP">200</amount>
        <quantity>5</quantity>
        <title>Item 1</title>
      </products>
      <products>
        <amount currencycode="GBP">500</amount>
        <quantity>1</quantity>
        <title>Item 2</title>
      </products>
      <sitereference>test_site12345</sitereference>
    </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 baseamount is the full total of the transaction, covering the cost of all products/services ordered and any associated shipping fees and/or tax. E.g. baseamount = the sum of (productbaseamount x productquantity) + the sum of (producttaxbaseamount x productquantity) + customershippingbaseamount The baseamount is submitted in base units, with no commas or decimal points, e.g. €10 is submitted as 1000.
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	ISO3A	The currency associated with the total baseamount. For a list of currency codes supported by PayPal, refer to the list found at the top of this page.
customercountryiso2a XPath: /customer/country	Alpha (2)	The delivery address country. This will need to be in ISO2A format. Click here for a full list of country codes.
customerpostcode XPath: /customer/postcode	Alphanumeric (25)	The delivery address postcode or ZIP code. This must be a valid postcode/ZIP code for the customercountryiso2a submitted.
customertown XPath: /customer/town	Alphanumeric including symbols (127)	The delivery address town.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	This value must be submitted as “PAYPAL”.
paypaladdressoverride XPath: /billing/payment/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 – The delivery address submitted in the request will be shown to the customer. 2 – The delivery address submitted in the request will not be shown to the customer. This option is best suited for the purchasing of online services or products that are downloaded.
products XPath: /operation/products	Array of JSON Objects	The products object must include the following subfields flagged as "Required" in an array of JSON Objects. The array of JSON Objects subfields is repeated within the products object where multiple products make up the total main amount. Please refer to the example ORDER request above.
products » productbaseamount XPath: /operation/products/amount	Numeric (11)	This amount is the price of the given product in base units. This is per unit, e.g. it doesn't matter if the customer purchases 1 or 5 of this product - the productbaseamount will stay the same. This amount does not include tax or shipping.
products » productcurrencyiso3a XPath: /operation/products/amount/@currencycode	ISO3A	The currency associated with the productbaseamount. If submitted, this must be the same as currencyiso3a.
products » productquantity XPath: /operation/products/quantity	Numeric (10)	Quantity of the given product in the order.
products » producttitle XPath: /operation/products/title	Alphanumeric (127)	The name or title of the given product.
products » productcode XPath: /operation/products/code	Alphanumeric (127)	The Stock Keeping Unit (SKU) of the given product. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
products » productdescription XPath: /operation/products/description	Alphanumeric (127)	Detailed description for the given product. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
products » producttaxbaseamount XPath: /operation/products/taxamount	Numeric (11)	Tax amount for 1 unit of the given product, in base units. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
products » producttaxcurrencyiso3a XPath: /operation/products/taxamount/@currencycode	ISO3A	The currency associated with the producttaxbaseamount. If submitted, this must be the same as currencyiso3a. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
products » producttype XPath: /operation/products/type	Alpha (20)	Submit one of the following: digital - Goods that are stored, delivered and used in their electronic format. physical - A tangible item that can be shipped with proof of delivery. gift - A contribution or gift for which no good or service is exchanged, usually to a charity. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
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.
customercounty XPath: /customer/county	Alphanumeric including symbols (127)	The delivery address 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”. Required if customercountryiso2a is one of the following: AR, BR, CA, CN, ID, IN, IT, JP, MX, TH, US
customerfirstname XPath: /customer/name/first	Alphanumeric including symbols (127)	The customer’s first name. Required if paypaladdressoverride is set to "1" or "2". Otherwise, optional.
customerlastname XPath: /customer/name/last	Alphanumeric including symbols (127)	The customer’s last name. Required if paypaladdressoverride is set to "1" or "2". Otherwise, optional.
customerprefixname XPath: /customer/name/prefix	Alphanumeric including symbols (25)	The customer's prefix name (e.g. Mr, Miss, Dr). Required if paypaladdressoverride is set to "1" or "2". Otherwise, optional.
customerpremise XPath: /customer/premise	Alphanumeric including symbols (25)	The first line of the delivery address. Required if paypaladdressoverride is set to "1". Otherwise, optional.
paypaltransactionriskcontextdata XPath: /operation/paypaltransactionriskcontextdata	Array of JSON Objects	This array is used to share additional context data to PayPal regarding a customer before the transaction is processed. PayPal uses this data to complete a pre-transaction risk management evaluation. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
paypaltransactionriskcontextdata » paypaltransactionriskcontextdatakey XPath: /operation/paypaltransactionriskcontextdata/key	Alphanumeric (255)	Key of merchant-specific risk context field regarding the transaction. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
paypaltransactionriskcontextdata » paypaltransactionriskcontextdatavalue XPath: /operation/paypaltransactionriskcontextdata/value	Alphanumeric (255)	Value of merchant-specific risk context field regarding the transaction. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
paypaltransactionriskcontexttrackingid XPath: /operation/paypaltransactionriskcontexttrackingid	Alphanumeric (255)	A unique ID specified by the merchant to track each transaction. Can be any unique value. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
customeremail XPath: /customer/email	Email (255)	The email address to which digital goods are delivered. We recommend you submit the customer's email address when the paypaladdressoverride is set to "2".
customermiddlename XPath: /customer/name/middle	Alphanumeric including symbols (127)	The customer’s middle name(s).
customershippingbaseamount XPath: /customer/shippingamount	Numeric (11)	This amount is the total spent on shipping in base units. For the ECM flow, this must be the final shipping amount as this cannot be updated again prior to the customer completing the purchase on PayPal's website.
customerstreet XPath: /customer/street	Alphanumeric including symbols (127)	The second line of the delivery address.
customershippingcurrencyiso3a XPath: /customer/shippingamount/@currencycode	ISO3A	The currency associated with the customershippingbaseamount. If submitted, this must be the same as currencyiso3a.
customersuffixname XPath: /customer/name/suffix	Alphanumeric including symbols (25)	The customer’s suffix name (e.g. Bsc).
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.
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).
settlestatus XPath: /settlement/settlestatus	Numeric (3)	This conveys the settlement flow to be employed. Submit one of the following: 0 (or omit field) - For default PayPal settlement flow, where funds are pending settlement for up to 24 hours and then are settled automatically. 100 - Funds to be settled immediately after authorisation. Subject to additional requirements. Contact our Support Team to enable. 2 - Defer settlement. Settlement can be deferred for up to 7 days. Your system will need to submit a TRANSACTIONUPDATE with settlestatus=0 in order to schedule settlement in the next settlement batch.

While the submission of a separate billing address in the ORDER request is optional, if you are submitting a billing address, you must ensure you submit the fields billingcountryiso2a, billingcounty, billingpostcode and billingpostcode. Submitting a partial billing address without these listed fields will result in a 30000 "Invalid field" error being returned.

ORDER Response (ECM)

{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'ECOM',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'livestatus': u '0',
u 'operatorname': u 'webservices@example.com',
u 'paymenttypedescription': u 'PAYPAL',
u 'paypaltoken': u '56604A14170900854600',
u 'requesttypedescription': u 'ORDER',
u 'redirecturl': u 'https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&amp;useraction=commit&amp;cmd=_express-checkout',
u 'settleduedate': u '2020-06-01',
u 'settlestatus': u '0',
u 'transactionreference': u '72-32-20002',
u 'transactionstartedtimestamp': u '2020-06-01 15:35:40'
}]
}

array(3) {
  ["requestreference"] => string(9) "A349bdehj"
  ["version"] => string(4) "1.00"
  ["responses"] =>array(1) {
    [0] => array(13) {
      ["accounttypedescription"] => string(4) "ECOM"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["livestatus"] => string(1) "0"
      ["operatorname"] => string(23) "webservices@example.com"
      ["paymenttypedescription"] => string(6) "PAYPAL"
      ["paypaltoken"] => string(20) "56604A14170900854600"
      ["redirecturl"] => string(112) "https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&amp;useraction=commit&amp;cmd=_express-checkout"
      ["requesttypedescription"] => string(5) "ORDER"
      ["settleduedate" ]=> string(10) "2020-06-01"
      ["settlestatus"] => string(1) "0"
      ["transactionreference"] => string(11) "72-32-20002"
      ["transactionstartedtimestamp"] => string(19) "2020-06-01 15:35:40"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"ECOM",
    "errorcode":"0",
    "errormessage":"Ok",
    "livestatus":"0",
    "operatorname":"webservices@example.com",
    "paymenttypedescription":"PAYPAL",
    "paypaltoken":"56604A14170900854600",
    "redirecturl":"https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&amp;useraction=commit&amp;cmd=_express-checkout",
    "requesttypedescription":"ORDER",
    "settleduedate":"2020-06-01",
    "settlestatus":"0",
    "transactionreference":"72-32-20002",
    "transactionstartedtimestamp":"2020-06-01 15:35:40"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>X62d3qhev</requestreference>
  <response type="ORDER">
    <billing>
      <payment type="PAYPAL"/>
    </billing>
    <error>
      <code>0</code>
      <message>Ok</message>
    </error>
    <live>0</live>
    <merchant>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <paypal>
      <redirecturl>https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&amp;useraction=commit&amp;cmd=_express-checkout</redirecturl>
      <token>56604A14170900854600</token>
    </paypal>
    <settlement>
      <settleduedate>2020-06-01</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <timestamp>2020-06-01 15:35:40</timestamp>
    <transactionreference>72-32-20002</transactionreference>
  </response>
  <secrand>9yFfRJfI</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. 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.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
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)	0 - Default settlement flow for PayPal is currently being applied to this transaction (if subsequent AUTH is successful, expect funds to be settled within 24 hours). 100 - Funds will be settled immediately after the subsequent AUTH, providing said request is successful. 2 - Funds will be deferred following the AUTH, providing the request is successful. 3 - The ORDER request was unsuccessful. You should not proceed with the PayPal transaction and instead display an error message to the customer, allowing them to retry or select a different payment method.
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.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.

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. To process the payment, your system will need to use this URL when redirecting the customer’s browser to a page hosted by PayPal.

By amending the URL as described below, you can change the text shown on the submit button displayed to the customer on the PayPal details page:

To display this button:

Use the redirecturl unchanged.

To display this button:

Add useraction to the endpoint as follows:
[redirecturl]&useraction=commit

After signing in to their PayPal account, the customer has the option to continue with the transaction or to cancel.

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

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.

When testing, at this stage you will be redirected to PayPal's sandbox, an environment that closely resembles the interface the customer would use to sign in to their PayPal account and authorise the payment.

3. Process the authorisation

If customer is redirected to cancelurl, allow customer to retry or select another payment method.

If customer is redirected to returnurl, follow the instructions below.

The ORDERDETAILS request is used to retrieve changes made by the customer on PayPal prior to performing the AUTH.
The AUTH request is to process the payment.

ORDERDETAILS AUTH request (ECM)

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 = {
  "parenttransactionreference": "72-32-20002",
  "paymenttypedescription": "PAYPAL",
  "requesttypedescriptions": ["ORDERDETAILS","AUTH"],
  "sitereference": "test_site12345"
}

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(
  'parenttransactionreference' => '72-32-20002',
  'paymenttypedescription' => 'PAYPAL',
  'requesttypedescriptions' => array('ORDERDETAILS','AUTH'),
  'sitereference' => 'test_site12345'
);

$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": [{
    "parenttransactionreference": "72-32-20002",
    "paymenttypedescription": "PAYPAL",
    "requesttypedescriptions": ["ORDERDETAILS","AUTH"],
    "sitereference": "test_site12345"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "parenttransactionreference":"72-32-20002",
    "paymenttypedescription":"PAYPAL",
    "requesttypedescriptions":["ORDERDETAILS","AUTH"],
    "sitereference":"test_site12345"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="ORDERDETAILS">
    <operation>
      <parenttransactionreference>72-32-20002</parenttransactionreference>
      <sitereference>test_site12345</sitereference>
    </operation>
  </request>
  <request type="AUTH">
    <billing>
      <payment type="PAYPAL"/>
    </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 ORDER response.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	This value must be submitted as “PAYPAL”.
requesttypedescriptions XPath: /@type Note: The XML submission is comprised of two separate requests. We recommend using the example above to help structure this request.	List	Submit “ORDERDETAILS” and “AUTH”, as shown in the request example above.
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 AUTH response (ECM)

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 'accounttypedescription': u 'ECOM',
u 'billingcountryiso2a': u 'GB',
u 'billingemail': u 'paypal.email@example.com',
u 'billingfirstname': u 'Andru00e9',
u 'billinglastname': u 'PAYPALLastName',
u 'customercountryiso2a': u 'GB',
u 'customercounty': u 'Gwynedd',
u 'customeremail': u 'email@customer.com',
u 'customerip': u '1.2.3.4',
u 'customerlastname': u 'Jay Doe',
u 'customerpostcode': u 'PA45 6AL',
u 'customerpremise': u 'No 456',
u 'customerstreet': u 'Trust Street',
u 'customertown': u 'Caernarfon',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'livestatus': u '0',
u 'operatorname': u 'webservices@example.com',
u 'merchantname': u 'Test Merchant',
u 'parenttransactionreference': u '72-32-20002',
u 'paypaladdressstatus': u 'Unconfirmed',
u 'paypalpayerid': u 'e018408a43pid',
u 'paypalpayerstatus': u 'unverified',
u 'requesttypedescription': u 'ORDERDETAILS',
u 'settleduedate': u '2020-06-01',
u 'settlestatus': u '0',
u 'transactionreference': u '72-32-20003',
u 'transactionstartedtimestamp': u '2020-06-01 15:36:00'
}, {
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u 'CREATED',
u 'authcode': u '44782-D149613359266',
u 'baseamount': u '2150',
u 'currencyiso3a': u 'GBP',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'livestatus': u '0',
u 'merchantname': u 'Test Merchant',
u 'operatorname': u 'webservices@example.com',
u 'parenttransactionreference': u '72-32-20003',
u 'paymenttypedescription': u 'PAYPAL',
u 'requesttypedescription': u 'AUTH',
u 'settleduedate': u '2020-06-01',
u 'settlestatus': u '0',
u 'transactionreference': u '72-32-20004',
u 'transactionstartedtimestamp': u '2020-06-01 15:36:00'

}]
}

array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["responses"] => array(2) {
    [0] => array(28) {
      ["accounttypedescription"] => string(4) "ECOM"
      ["billingcountryiso2a"] => string(2) "GB"
      ["billingemail"] => string(24) "paypal.email@example.com"
      ["billingfirstname"] => string(10) "Andru00e9"
      ["billinglastname"] => string(14) "PAYPALLastName"
      ["customercountryiso2a"] => string(2) "GB"
      ["customercounty"] => string(7) "Gwynedd"
      ["customeremail"] => string(18) "email@customer.com"
      ["customerip"] => string(7) "1.2.3.4"
      ["customerlastname"] => string(7) "Jay Doe"
      ["customerpostcode"] => string(8) "PA45 6AL"
      ["customerpremise"] => string(6) "No 456"
      ["customerstreet"] => string(10) "Trust Street"
      ["customertown"] => string(10) "Caernarfon"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["livestatus"] => string(1) "0"
      ["merchantname"] => string(13) "Test Merchant"
      ["operatorname"] => string(23) "webservices@example.com"
      ["parenttransactionreference"] => string(11) "72-32-20002"
      ["paypaladdressstatus"] => string(11) "Unconfirmed"
      ["paypalpayerid"] => string(13) "e018408a43pid"
      ["paypalpayerstatus"] => string(10) "unverified"
      ["requesttypedescription"] => string(12) "ORDERDETAILS"
      ["settleduedate"] => string(10) "2020-06-01"
      ["settlestatus"] => string(1) "0"
      ["transactionreference"] => string(11) "72-32-20003"
      ["transactionstartedtimestamp"] => string(19) "2020-06-01 15:36:00"

    }
    [1] =>array(17) {
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(7) "CREATED"
      ["authcode"] => string(19) "44782-D149613359266"
      ["baseamount"] => string(4) "2150"
      ["currencyiso3a"] => string(3) "GBP"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["livestatus"] => string(1) "0"
      ["merchantname"] => string(13) "Test Merchant"
      ["operatorname"] => string(23) "webservices@example.com"
      ["parenttransactionreference"] => string(11) "72-32-20003"
      ["paymenttypedescription"] => string(6) "PAYPAL"
      ["requesttypedescription"] => string(4) "AUTH"
      ["settleduedate"] => string(10) "2020-06-01"
      ["settlestatus"] => string(1) "0"
      ["transactionreference"] => string(11) "72-32-20004"
      ["transactionstartedtimestamp"] => string(19) "2020-06-01 15:36:00"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"ECOM",
    "billingcountryiso2a":"GB",
    "billingemail":"paypal.email@example.com",
    "billingfirstname":"Andru00e9",
    "billinglastname":"PAYPALLastName",
    "customercountryiso2a": "GB",
    "customercounty": "Gwynedd",
    "customeremail": "email@customer.com",
    "customerip": "1.2.3.4",
    "customerlastname": "Jay Doe",
    "customerpostcode": "PA45 6AL",
    "customerpremise": "No 456",
    "customerstreet": "Trust Street",
    "customertown": "Caernarfon",
    "errorcode":"0",
    "errormessage":"Ok",
    "livestatus":"0",
    "merchantname":"Test Merchant",
    "operatorname":"webservices@example.com",
    "parenttransactionreference":"72-32-20002",
    "paypaladdressstatus":"Unconfirmed",
    "paypalpayerid":"e018408a43pid",
    "paypalpayerstatus":"unverified",
    "requesttypedescription":"ORDERDETAILS",
    "settleduedate":"2020-06-01",
    "settlestatus":"0",
    "transactionreference":"72-32-20003",
    "transactionstartedtimestamp":"2020-06-01 15:36:00"
  },
  {
    "accounttypedescription":"ECOM",
    "acquirerresponsecode":"CREATED",
    "authcode":"44782-D149613359266",
    "baseamount":"2150",
    "currencyiso3a":"GBP",
    "errorcode":"0",
    "errormessage":"Ok",
    "livestatus":"0",
    "merchantname":"Test Merchant",
    "operatorname":"webservices@example.com",
    "parenttransactionreference":"72-32-20003",
    "paymenttypedescription":"PAYPAL",
    "requesttypedescription":"AUTH",
    "settleduedate":"2020-06-01",
    "settlestatus":"0",
    "transactionreference":"72-32-20004",
    "transactionstartedtimestamp":"2020-06-01 15:36:00"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>X538160153</requestreference>
  <response type="ORDERDETAILS">
    <billing>
      <country>GB</country>
      <email>paypal.email@example.com</email>
      <name>
        <first>Andru00e9</first>
        <last>PAYPALLastName</last>
      </name>
    </billing>
    <customer>
      <country>GB</country>
      <county>Gwynedd</county>
      <email>email@customer.com</email>
      <ip>1.2.3.4</ip>
      <name>
        <last>Jay Doe</last>
      </name>
      <postcode>PA45 6AL</postcode>
      <premise>No 456</premise>
      <street>Trust Street</street>
      <town>Caernarfon</town>
    </customer>
    <error>
      <code>0</code>
      <message>Ok</message>
    </error>
    <live>0</live>
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
      <parenttransactionreference>72-32-20002</parenttransactionreference>
    </operation>
    <paypal>
      <addressstatus>Unconfirmed</addressstatus>
      <payerid>e018408a43pid</payerid>
      <payerstatus>unverified</payerstatus>
    </paypal>
    <settlement>
      <settleduedate>2020-06-01</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <timestamp>2020-06-01 15:36:00</timestamp>
    <transactionreference>72-32-20003</transactionreference>
  </response>
  <response type="AUTH">
    <acquirerresponsecode>CREATED</acquirerresponsecode>
    <authcode>83154-D140912749345</authcode>
    <billing>
      <amount currencycode="GBP">2150</amount>
      <payment type="PAYPAL"/>
    </billing>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <live>0</live>
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
      <parenttransactionreference>72-32-20003</parenttransactionreference>
    </operation>
    <settlement>
      <settleduedate>2020-06-01</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <timestamp>2020-06-01 15:36:00</timestamp>
    <transactionreference>72-32-20004</transactionreference>
  </response>
  <secrand>oSs0Vl</secrand>
</responseblock>

Field specification

Because many of the fields returned in this response are also found in a standard AUTH response, we have only listed the most important fields below, which are relevant when handling PayPal responses.
Click here for the full AUTH 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. If the error code is “0” then the transaction was successful. If the error code is not “0” then the transaction was not successful. Remember to check the error response in both ORDERDETAILS and AUTH responses. Click here for a full list of errorcode and message values.
	errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Remember to check the error response in both ORDERDETAILS and AUTH responses. Click here for a full list of errorcode and message values.
	livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
	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)	This field is returned in both sections of the response, referring to previous requests processed in the sequence.
Only returned in AUTH response	paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	The value returned is “PAYPAL”.
Only returned in ORDERDETAILS response	paypaladdressstatus XPath: /paypal/addressstatus	Alpha (25)	The status of the address with PayPal. This is a deprecated check and PayPal will always return the value “Unconfirmed”.
Only returned in ORDERDETAILS response	paypalpayerid XPath: /paypal/payerid	Alphanumeric (255)	Unique PayPal customer account number.
Only returned in ORDERDETAILS response	paypalpayerstatus XPath: /paypal/payerstatus	Alpha (25)	The status of the payer with PayPal. This is a deprecated check and PayPal will always return the value “unverified”.
	requesttypedescription XPath: /@type	Alpha (20)	“ORDERDETAILS” and “AUTH” are returned in their respective responses.
	settleduedate XPath: /settlement/settleduedate	Date YYYY-MM-DD	The date on which the transaction will be settled.
	settlestatus XPath: /settlement/settlestatus	Numeric (3)	0 - Funds are pending settlement. You can expect funds to be settled within 24 hours. 100 - Funds were settled immediately. 2 - Funds were deferred. You will need to process a TRANSACTIONUPDATE with settlestatus=100 to perform settlement. 3 - The AUTH request was unsuccessful. You should not proceed with the PayPal transaction and instead display an error message to the customer, allowing them to retry or select a different payment method. (See below for info on settlement)
	transactionreference XPath: /transactionreference	Alphanumeric including hyphens (25)	Unique references for both requests, assigned by Trust Payments.
	transactionstartedtimestamp XPath: /timestamp	Date time YYYY-MM-DD hh:mm:ss	The time each request was processed.
Only returned in ORDERDETAILS response	customercountryiso2a XPath: /customer/country	Alpha (2)	The country of the delivery address returned from PayPal. This will need to be in ISO2A format. Click here for a full list of country codes. Returned from PayPal if available.
Only returned in ORDERDETAILS response	customercounty XPath: /customer/county	Alphanumeric including symbols (127)	The county of the delivery address returned from PayPal. For US addresses, the 2-character state code, is returned here. Returned from PayPal if available.
Only returned in ORDERDETAILS response	customeremail XPath: /customer/email	Email (255)	The delivery email address returned from PayPal. Maximum length of 255 (maximum of 64 characters before the ”@” symbol). Returned from PayPal if available.
Only returned in ORDERDETAILS response	customerip XPath: /customer/ip	IP address (39)	The IP address of the device used to process the order. Returned from PayPal if available.
Only returned in ORDERDETAILS response	customerlastname XPath: /customer/name/last	Alphanumeric including symbols (127)	The full name for the delivery returned from PayPal. Returned from PayPal if available.
Only returned in ORDERDETAILS response	customerpostcode XPath: /customer/postcode	Alphanumeric (25)	The postcode (ZIP code) of the delivery address returned from PayPal. Returned from PayPal if available.
Only returned in ORDERDETAILS response	customerpremise XPath: /customer/premise	Alphanumeric including symbols (25)	The first line of the delivery address returned from PayPal. Returned from PayPal if available.
Only returned in ORDERDETAILS response	customerstreet XPath: /customer/street	Alphanumeric including symbols (127)	The second line of the delivery address returned from PayPal. Returned from PayPal if available.
Only returned in ORDERDETAILS response	customertown XPath: /customer/town	Alphanumeric including symbols (127)	The town of the delivery address returned from PayPal. Returned from PayPal if available.
	errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Remember to check the error response in both ORDERDETAILS and AUTH responses. Only returned if there has been an error.
	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.

4. Payment completion

Settlement

By default, once a PayPal transaction has been authorised, funds will typically be settled into your bank account within 24 hours:

Following authorisation, the Settle status is set to 0 to indicate settlement is pending.
On a daily basis, Trust Payments initiates the settlement process for pending PayPal transactions.
The Settle status of a PayPal transaction is updated to 10 when settlement is in progress.
Shortly afterwards, Trust Payments receives confirmation from PayPal that funds have been settled and the Settle status is updated to 100.

About Pay Later

When handling order enquiries from customers, please remember that a customer may have opted to spread the cost of the purchase via PayPal's Pay Later products.

Regardless of how the customer chose to fund the transaction, you will always be paid in full at time of purchase, as with a conventional PayPal transaction.

As a result of this, a PayPal transaction can be recorded as "Settled", even if the customer has not yet settled their balance with PayPal. Any issues that have arisen relating to interest-free credit or pending instalments must be taken up with PayPal directly by the customer.

Alternative settlement flows

Deferred settlement

To defer settlement on a given PayPal transaction, include settlestatus=2 in the ORDER request. This will be inherited by the AUTH request, which triggers the temporary suspension of the transaction following authorisation.

The settlement is deferred until you submit a TRANSACTIONUPDATE with settlestatus=0.

PayPal transactions can be deferred for up to 31 days.

Immediate settlement

Immediate settlement functionality is subject to additional requirements.

Before processing immediate settlement, you must contact our Support Team and request for this to be enabled on your account.

To enable immediate settlement for a given transaction, include settlestatus=100 in the ORDER request. This will be inherited by the AUTH request, which will trigger Trust Payments to attempt the settlement of funds immediately after authorisation.

If PayPal needs more time to perform checks, the transaction may be temporarily set to Settle status 10.

Partial settlement

You can opt to settle a lower amount than was originally authorised. To do so, submit a TRANSACTIONUPDATE with a lower settlebaseamount.

Notifications

Before you begin testing, we recommend that you contact our Support Team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:

When a payment is authorised (AUTH has errorcode=0).
When funds have been settled (AUTH in settlestatus=100).

When contacting Support, please provide your site reference and the endpoint to which the notification will be sent.

You will need to check the contents of each notification received and respond accordingly by following the processes outlined in our URL notifications documentation. In particular, you will need to look at the updated settlestatus value:

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (deferred and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

Refunds

The process of processing PayPal refunds is the same as refunding a standard card transaction, but please first review the following:

To ensure your records with Trust Payments remain in sync with Paypal, we strongly recommend that you perform refunds exclusively using the Trust Payments platform, rather than through the PayPal admin portal.

You must ensure you refund the AUTH request, and NOT pass through references to any related ORDER or ORDERDETAILS requests.

Most PayPal refunds are settled immediately (settlestatus=100). However, under certain conditions defined by PayPal, refunds can be set to settlestatus=10 (“settling”), which is an intermediate step prior to settlement. If a PayPal refund on your account is in settlestatus=10, it is recommended you query it with our Support Team in case further actions need to be completed to ensure settlement.

About Pay Later

When handling refund enquiries from customers, please remember that a customer may have opted to spread the cost of the initial purchase via PayPal's Pay Later products.

Because of this, it is imperative that when performing a full refund of a transaction, you should refund for the full amount to ensure the customer is not later billed for any funds still outstanding on credit.

When a refund is performed, the funds are debited from your bank account and PayPal is responsible for ensuring the customer is credited accordingly.

With the above notes in mind, click the links below to open instructions on performing PayPal refunds in a new tab:

Use the tabs above to change the workflow.

The below covers Express Checkout Shortcut (ECS)

Express Checkout Shortcut (ECS) - Customers click the “Check out with PayPal” button on your website and are redirected to PayPal’s servers.

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 shipping fees 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.

Pay Later

Click here to learn more (external link)

First steps

Requirements

Before you can process live PayPal transactions, you will need to have a PayPal Business Account. If you do not already have a Business Account, you will be prompted to register a new account as part of the onboarding process we outline below.
PayPal does not support their hosted pages being rendered within an iframe. Instead, you must always redirect the customer's browser to PayPal during the checkout session.

PayPal onboarding

Contact our Support Team and enquire about enabling PayPal on your TRU Connect account.
Our Support Team will provide you with a URL to complete the setup.
Navigate directly to the URL in your browser and sign in with your PayPal Business Account.

If you haven't already registered a PayPal Business Account, you will be prompted to do so as part of onboarding.
You will be presented with a list of permissions that you will need to grant us in order to complete the setup. Read these carefully and click "Accept" to continue.
After you have granted the necessary permissions, PayPal will perform additional verification checks on your account. If you have not already done so, you then may be prompted to validate the email address associated with your PayPal account.
Once the above has been performed, a request will automatically be sent from PayPal to Trust Payments to activate PayPal on your site reference and the boarding process is complete. We will confirm via email when your site reference is enabled to process PayPal transact
If you have any queries regarding the status of your PayPal onboarding, please contact our Support Team.

Overview of ECS

Initiate the customer
- Customer agrees to a payment using PayPal on the merchant's website.
- Merchant submits ORDER request to initiate the session, including cancelurl and returnurl.
- Merchant receives ORDER response, including paypaltoken and redirecturl.
Redirect to PayPal
- Merchant redirects the customer's browser to the redirecturl, including the paypaltoken.
- Customer signs in and agrees to the payment using their PayPal account.
- If successful, the customer's browser is redirected to the returnurl.
- If the PayPal order is cancelled, the browser is redirected to the cancelurl where an error message can be displayed. We recommend that alternative payment methods are displayed, allowing the customer to try again.
Retrieve order details
- Only if the above has been successful, the merchant submits an ORDERDETAILS request to retrieve the transaction details from PayPal.
- Merchant receives ORDERDETAILS response and uses this to display an order summary to the customer. This response can be parsed for the delivery address and this can be used to calculate and display an updated shipping fee (if required).
Process the authorisation
- If the customer agrees to the purchase on your website, the merchant submits an AUTH request to process the payment.
- Merchant receives AUTH response and displays receipt page to the customer.
Payment completion
- Under default behaviour, the transaction is in a pending state and funds will typically settle within 24 hours.
- But if preferred, merchants can configure their setup to instead request funds are settled immediately. Or alternatively, settlement can be deferred for up to 7 days.
- Once settlement has been completed, Trust Payments will submit a URL notification (if enabled) to the merchant’s system as confirmation. Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.

1. Initiate the customer

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 “PayPal Checkout” 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 “Check out 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.

Processing ORDER

The ORDER request is used to initiate the order with PayPal.

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

ORDER Request (ECS)

#!/usr/bin/python
import securetrading

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

order = {
  "accounttypedescription": "ECOM",
  "baseamount": "1650",
  "cancelurl": "https://yourwebsite.com",
  "currencyiso3a": "GBP",
  "customercountryiso2a": "GB",
  "customerpostcode": "TR45 6ST",
  "customertown": "Bangor",
  "paymenttypedescription": "PAYPAL",
  "products":
  [{
    "productbaseamount": "200",
    "productcurrencyiso3a": "GBP",
    "productquantity": "5",
    "producttitle": "Item 1"
  },
  {
    "productbaseamount": "500",
    "productcurrencyiso3a": "GBP",
    "productquantity": "1",
    "producttitle": "Item 2"
  }],
  "requesttypedescription": "ORDER",
  "returnurl": "https://yourwebsite.com",
  "sitereference": "test_site12345"
}

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(
  'accounttypedescription' => 'ECOM',
  'baseamount' => '1650',
  'cancelurl' => 'https://yourwebsite.com',
  'currencyiso3a' => 'GBP',
  'customercountryiso2a' => 'GB',
  'customerpostcode' => 'TR45 6ST',
  'customertown' => 'Bangor',
  'paymenttypedescription' => 'PAYPAL',
  'products' =>
  [[
    'productbaseamount' => '200',
    'productcurrencyiso3a' => 'GBP',
    'productquantity' => '5',
    'producttitle' => 'Item 1'
  ], 
  [
    'productbaseamount' => '500',
    'productcurrencyiso3a' => 'GBP',
    'productquantity' => '1',
    'producttitle' => 'Item 2'
  ]], 
  'requesttypedescription' => 'ORDER',
  'returnurl' => 'https://yourwebsite.com',
  'sitereference' => 'test_site12345'
);

$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": [{
    "accounttypedescription": "ECOM",
    "baseamount": "1650",
    "cancelurl": "https://yourwebsite.com",
    "currencyiso3a": "GBP",
    "customercountryiso2a": "GB",
    "customerpostcode": "TR45 6ST",
    "customertown": "Bangor",
    "paymenttypedescription": "PAYPAL",
    "products":
    [{
      "productbaseamount": "200",
      "productcurrencyiso3a": "GBP",
      "productquantity": "5",
      "producttitle": "Item 1"
    },
    {
      "productbaseamount": "500",
      "productcurrencyiso3a": "GBP",
      "productquantity": "1",
      "producttitle": "Item 2"
    }],
  "requesttypedescription": "ORDER",
  "returnurl": "https://yourwebsite.com",
  "sitereference": "test_site12345"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accounttypedescription": "ECOM",
    "baseamount": "1650",
    "cancelurl": "https://yourwebsite.com",
    "currencyiso3a": "GBP",
    "customercountryiso2a": "GB",
    "customerpostcode": "TR45 6ST",
    "customertown": "Bangor",
    "paymenttypedescription": "PAYPAL",
    "products":
    [{
      "productbaseamount": "200",
      "productcurrencyiso3a": "GBP",
      "productquantity": "5",
      "producttitle": "Item 1"
    },
    {
      "productbaseamount": "500",
      "productcurrencyiso3a": "GBP",
      "productquantity": "1",
      "producttitle": "Item 2"
    }],
    "requesttypedescription": "ORDER",
    "returnurl": "https://yourwebsite.com",
    "sitereference": "test_site12345"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="ORDER">
    <billing>
      <amount currencycode="GBP">1650</amount>
      <payment type="PAYPAL"/>
    </billing>
    <customer>
      <country>GB</country>
      <postcode>TR45 6ST</postcode>
      <town>Bangor</town>
    </customer>
    <merchant>
      <cancelurl>https://www.example.com/cancel</cancelurl>
      <returnurl>https://www.example.com/return</returnurl>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
      <products>
        <amount currencycode="GBP">200</amount>
        <quantity>5</quantity>
        <title>Item 1</title>
      </products>
      <products>
        <amount currencycode="GBP">500</amount>
        <quantity>1</quantity>
        <title>Item 2</title>
      </products>
      <sitereference>test_site12345</sitereference>
    </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 baseamount is the full total of the transaction, covering the cost of all products/services ordered and any associated shipping fees and/or tax. E.g. baseamount = the sum of (productbaseamount x productquantity) + the sum of (producttaxbaseamount x productquantity) + customershippingbaseamount The baseamount is submitted in base units, with no commas or decimal points, e.g. €10 is submitted as 1000.
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	ISO3A	The currency associated with the total baseamount. For a list of currency codes supported by PayPal, refer to the list found at the top of this page.
customercountryiso2a XPath: /customer/country	Alpha (2)	The delivery address country. This will need to be in ISO2A format. Click here for a full list of country codes.
customerpostcode XPath: /customer/postcode	Alphanumeric (25)	The delivery address postcode or ZIP code. This must be a valid postcode/ZIP code for the customercountryiso2a submitted.
customertown XPath: /customer/town	Alphanumeric including symbols (127)	The delivery address town.
paymenttypedescription XPath: /billing/payment/@type	Alpha (20)	This value must be submitted as “PAYPAL”.
products XPath: /operation/products	Array of JSON Objects	The products object must include the following subfields flagged as "Required" in an array of JSON Objects. The array of JSON Objects subfields is repeated within the products object where multiple products make up the total main amount. Please refer to the example ORDER request above.
products » productbaseamount XPath: /operation/products/amount	Numeric (11)	This amount is the price of the given product in base units. This is per unit, e.g. it doesn't matter if the customer purchases 1 or 5 of this product - the productbaseamount will stay the same. This amount does not include tax or shipping.
products » productcurrencyiso3a XPath: /operation/products/amount/@currencycode	ISO3A	The currency associated with the productbaseamount. If submitted, this must be the same as currencyiso3a.
products » productquantity XPath: /operation/products/quantity	Numeric (10)	Quantity of the given product in the order.
products » producttitle XPath: /operation/products/title	Alphanumeric (127)	The name or title of the given product.
products » productcode XPath: /operation/products/code	Alphanumeric (127)	The Stock Keeping Unit (SKU) of the given product. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
products » productdescription XPath: /operation/products/description	Alphanumeric (127)	Detailed description for the given product. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
products » producttaxbaseamount XPath: /operation/products/taxamount	Numeric (11)	Tax amount for 1 unit of the given product, in base units. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
products » producttaxcurrencyiso3a XPath: /operation/products/taxamount/@currencycode	ISO3A	The currency associated with the producttaxbaseamount. If submitted, this must be the same as currencyiso3a. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
products » producttype XPath: /operation/products/type	Alpha (20)	Submit one of the following: digital - Goods that are stored, delivered and used in their electronic format. physical - A tangible item that can be shipped with proof of delivery. gift - A contribution or gift for which no good or service is exchanged, usually to a charity. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
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.
customercounty XPath: /customer/county	Alphanumeric including symbols (127)	The delivery address 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”. Required if customercountryiso2a is one of the following: AR, BR, CA, CN, ID, IN, IT, JP, MX, TH, US
customerfirstname XPath: /customer/name/first	Alphanumeric including symbols (127)	The customer’s first name. Required if paypaladdressoverride is set to "1" or "2". Otherwise, optional.
customerlastname XPath: /customer/name/last	Alphanumeric including symbols (127)	The customer’s last name. Required if paypaladdressoverride is set to "1" or "2". Otherwise, optional.
customerprefixname XPath: /customer/name/prefix	Alphanumeric including symbols (25)	The customer's prefix name (e.g. Mr, Miss, Dr). Required if paypaladdressoverride is set to "1" or "2". Otherwise, optional.
customerpremise XPath: /customer/premise	Alphanumeric including symbols (25)	The first line of the delivery address. Required if paypaladdressoverride is set to "1". Otherwise, optional.
paypaltransactionriskcontextdata XPath: /operation/paypaltransactionriskcontextdata	Array of JSON Objects	This array is used to share additional context data to PayPal regarding a customer before the transaction is processed. PayPal uses this data to complete a pre-transaction risk management evaluation. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
paypaltransactionriskcontextdata » paypaltransactionriskcontextdatakey XPath: /operation/paypaltransactionriskcontextdata/key	Alphanumeric (255)	Key of merchant-specific risk context field regarding the transaction. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
paypaltransactionriskcontextdata » paypaltransactionriskcontextdatavalue XPath: /operation/paypaltransactionriskcontextdata/value	Alphanumeric (255)	Value of merchant-specific risk context field regarding the transaction. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
paypaltransactionriskcontexttrackingid XPath: /operation/paypaltransactionriskcontexttrackingid	Alphanumeric (255)	A unique ID specified by the merchant to track each transaction. Can be any unique value. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure.
customeremail XPath: /customer/email	Email (255)	The email address to which digital goods are delivered. We recommend you submit the customer's email address when the paypaladdressoverride is set to "2".
customermiddlename XPath: /customer/name/middle	Alphanumeric including symbols (127)	The customer’s middle name(s).
customershippingbaseamount XPath: /customer/shippingamount	Numeric (11)	This amount is the total spent on shipping in base units. For the ECS flow, if you already know the final shipping amount, we recommend including it in the ORDER request as this will be shown to the customer on PayPal's website, making it easier for the customer to understand the breakdown of the amount they are to pay. Otherwise, you can omit this field and instead use the address returned from PayPal in the subsequent ORDERDETAILS response to calculate a more accurate shipping amount and submit this in the AUTH request.
customershippingcurrencyiso3a XPath: /customer/shippingamount/@currencycode	ISO3A	The currency associated with the customershippingbaseamount. If submitted, this must be the same as currencyiso3a.
customerstreet XPath: /customer/street	Alphanumeric including symbols (127)	The second line of the delivery address.
customersuffixname XPath: /customer/name/suffix	Alphanumeric including symbols (25)	The customer’s suffix name (e.g. Bsc).
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.
paypaladdressoverride XPath: /billing/payment/paypaladdressoverride	Numeric (1)	Allows you to override the delivery address chosen by the customer on PayPal: 0 – While on PayPal's website, the customer will see the delivery address submitted in the request and will have the option to change their delivery address. 1 – While on PayPal's website, the customer will see the delivery address submitted in the request but will not have the option to change their delivery address. 2 – While on PayPal's website, the customer will not see the delivery address submitted in the request and will not have the option to change their delivery address.
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).
settlestatus XPath: /settlement/settlestatus	Numeric (3)	This conveys the settlement flow to be employed. Submit one of the following: 0 (or omit field) - For default PayPal settlement flow, where funds are pending settlement for up to 24 hours and then are settled automatically. 100 - Funds to be settled immediately after authorisation. Subject to additional requirements. Contact our Support Team to enable. 2 - Defer settlement. Settlement can be deferred for up to 7 days. Your system will need to submit a TRANSACTIONUPDATE with settlestatus=0 in order to schedule settlement in the next settlement batch.

ORDER Response (ECS)

{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'ECOM',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'livestatus': u '0',
u 'operatorname': u 'webservices@example.com',
u 'paymenttypedescription': u 'PAYPAL',
u 'paypaltoken': u '56604A14170900854600',
u 'redirecturl': u 'https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&amp;useraction=commit&amp;cmd=_express-checkout',
u 'requesttypedescription': u 'ORDER',
u 'settleduedate': u '2020-06-01',
u 'settlestatus': u '0',
u 'transactionreference': u '72-32-20002',
u 'transactionstartedtimestamp': u '2020-06-01 15:35:40'

}]
}

array(3) {
  ["requestreference"] => string(9) "A349bdehj"
  ["version"] => string(4) "1.00"
  ["responses"] =>array(1) {
    [0] => array(13) {
      ["accounttypedescription"] => string(4) "ECOM"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["livestatus"] => string(1) "0"
      ["operatorname"] => string(23) "webservices@example.com"
      ["paymenttypedescription"] => string(6) "PAYPAL"
      ["paypaltoken"] => string(11) "56604A14170900854600"
      ["redirecturl"] => string(112) "https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&amp;useraction=commit&amp;cmd=_express-checkout"
      ["requesttypedescription"] => string(5) "ORDER"
      ["settleduedate" ]=> string(10) "2020-06-01"
      ["settlestatus"] => string(1) "0"
      ["transactionreference"] => string(11) "72-32-20002"
      ["transactionstartedtimestamp"] => string(19) "2020-06-01 15:35:40"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"ECOM",
    "errorcode":"0",
    "errormessage":"Ok",
    "livestatus":"0",
    "operatorname":"webservices@example.com",
    "paymenttypedescription":"PAYPAL",
    "paypaltoken":"56604A14170900854600",
    "redirecturl":"https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&amp;useraction=commit&amp;cmd=_express-checkout",
    "requesttypedescription":"ORDER",
    "settleduedate":"2020-06-01",
    "settlestatus":"0",
    "transactionreference":"72-32-20002",
    "transactionstartedtimestamp":"2020-06-01 15:35:40"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>X62d3qhev</requestreference>
  <response type="ORDER">
    <billing>
      <payment type="PAYPAL"/>
    </billing>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <live>0</live>
    <merchant>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <paypal>
      <redirecturl>https://www.paypal.com/cgi-bin/webscr?token=56604A14170900854600&amp;useraction=commit&amp;cmd=_express-checkout</redirecturl>
      <token>56604A14170900854600</token>
    </paypal>
    <settlement>
      <settleduedate>2020-06-01</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <timestamp>2020-06-01 15:35:40</timestamp>
    <transactionreference>72-32-20002</transactionreference>
  </response>
  <secrand>9yFfRJfI</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. 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.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
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)	0 - Default settlement flow for PayPal is currently being applied to this transaction (if subsequent AUTH is successful, expect funds to be settled within 24 hours). 100 - Funds will be settled immediately after the subsequent AUTH, providing said request is successful. 2 - Funds will be deferred following the AUTH, providing the request is successful. 3 - The ORDER request was unsuccessful. You should not proceed with the PayPal transaction and instead display an error message to the customer, allowing them to retry or select a different payment method.
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.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.

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

By amending the URL as described below, you can change the text shown on the submit button displayed to the customer on the PayPal details page:

To display this button:

Use the redirecturl unchanged.

To display this button:

Add to the endpoint as follows:
&useraction=commit

After signing in to their PayPal account, the customer has the option to continue with the transaction or to cancel.

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

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.

3. Retrieve order details

If customer is redirected to cancelurl, allow customer to retry or select another payment method.

If customer is redirected to returnurl, follow the instructions below.

The ORDERDETAILS request is used to retrieve changes made by the customer on PayPal. Of particular note, your system should use the delivery address returned to calculate/amend any shipping fees for inclusion in the AUTH request as appropriate.

ORDERDETAILS request (ECS)

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 = {
  "parenttransactionreference": "72-32-20002",
  "requesttypedescription": "ORDERDETAILS",
  "sitereference": "test_site12345"
}

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(
  'parenttransactionreference' => '72-32-20002',
  'requesttypedescription' => array'ORDERDETAILS',
  'sitereference' => 'test_site12345'
);

$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": [{
    "parenttransactionreference": "72-32-20002",
    "requesttypedescription": "ORDERDETAILS",
    "sitereference": "test_site12345"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "parenttransactionreference":"72-32-20002",
    "requesttypedescription":"ORDERDETAILS",
    "sitereference":"test_site12345"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="ORDERDETAILS">
    <operation>
      <parenttransactionreference>72-32-20002</parenttransactionreference>
      <sitereference>test_site12345</sitereference>
    </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 (ECS)

Here is an example of an ORDERDETAILS response:

{
u 'requestreference': u 'A0dcb11e6',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'ECOM',
u 'billingcountryiso2a': u 'GB',
u 'billingemail': u 'paypal.email@example.com',
u 'billingfirstname': u 'Andru00e9',
u 'billinglastname': u 'PAYPALLastName',
u 'customercountryiso2a': u 'GB',
u 'customercounty': u 'Gwynedd',
u 'customeremail': u 'email@customer.com',
u 'customerip': u '1.2.3.4',
u 'customerlastname': u 'Jay Doe',
u 'customerpostcode': u 'PA45 6AL',
u 'customerpremise': u 'No 456',
u 'customerstreet': u 'Trust Street',
u 'customertown': u 'Caernarfon',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'livestatus': u '0',
u 'merchantname': u 'Test Merchant',
u 'operatorname': u 'webservices@example.com',
u 'parenttransactionreference': u '72-32-20002',
u 'paypaladdressstatus': u 'Unconfirmed',
u 'paypalpayerid': u '4d22e2606apid',
u 'paypalpayerstatus': u 'unverified',
u 'requesttypedescription': u 'ORDERDETAILS',
u 'settleduedate': u '2020-06-01',
u 'settlestatus': u '0',
u 'transactionreference': u '72-32-20003',
u 'transactionstartedtimestamp': u '2020-06-01 15:36:00'
}]
}

array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(28) {
      ["accounttypedescription"] => string(4) "ECOM"
      ["billingcountryiso2a"] => string(2) "GB"
      ["billingemail"] => string(24) "paypal.email@example.com"
      ["billingfirstname"] => string(10) "Andru00e9"
      ["billinglastname"] => string(14) "PAYPALLastName"
      ["customercountryiso2a"] => string(2) "GB"
      ["customercounty"] => string(7) "Gwynedd"
      ["customeremail"] => string(18) "email@customer.com"
      ["customerip"] => string(7) "1.2.3.4"
      ["customerlastname"] => string(7) "Jay Doe"
      ["customerpostcode"] => string(8) "PA45 6AL"
      ["customerpremise"] => string(6) "No 456"
      ["customerstreet"] => string(10) "Trust Street"
      ["customertown"] => string(10) "Caernarfon"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["livestatus"] => string(1) "0"
      ["merchantname"] => string(13) "Test Merchant"
      ["operatorname"] => string(23) "webservices@example.com"
      ["parenttransactionreference"] => string(11) "72-32-20002"
      ["paypaladdressstatus"] => string(11) "Unconfirmed"
      ["paypalpayerid"] => string(13) "4d22e2606apid"
      ["paypalpayerstatus"] => string(10) "unverified"
      ["requesttypedescription"] => string(12) "ORDERDETAILS"
      ["settleduedate"] => string(10) "2020-06-01"
      ["settlestatus"] => string(1) "0"
      ["transactionreference"] => string(11) "72-32-20003"
      ["transactionstartedtimestamp"] => string(19) "2020-06-01 15:36:00"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"ECOM",
    "billingcountryiso2a":"GB",
    "billingemail":"paypal.email@example.com",
    "billingfirstname":"Andru00e9",
    "billinglastname":"PAYPALLastName",
    "customercountryiso2a": "GB",
    "customercounty": "Gwynedd",
    "customeremail": "email@customer.com",
    "customerip": "1.2.3.4",
    "customerlastname": "Jay Doe",
    "customerpostcode": "PA45 6AL",
    "customerpremise": "No 456",
    "customerstreet": "Trust Street",
    "customertown": "Caernarfon",
    "errorcode":"0",
    "errormessage":"Ok",
    "livestatus":"0",
    "merchantname":"Test Merchant",
    "operatorname":"webservices@example.com",
    "parenttransactionreference":"72-32-20002",
    "paypaladdressstatus":"Unconfirmed",
    "paypalpayerid":"4d22e2606apid",
    "paypalpayerstatus":"unverified",
    "requesttypedescription":"ORDERDETAILS",
    "settleduedate":"2020-06-01",
    "settlestatus":"0",
    "transactionreference":"72-32-20003",
    "transactionstartedtimestamp":"2020-06-01 15:36:00"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>X538160153</requestreference>
  <response type="ORDERDETAILS">
    <billing>
      <country>GB</country>
      <email>paypal.email@example.com</email>
      <name>
        <first>Andru00e9</first>
        <last>PAYPALLastName</last>
      </name>
    </billing>
    <customer>
      <country>GB</country>
      <county>Gwynedd</county>
      <email>email@customer.com</email>
      <ip>1.2.3.4</ip>
      <name>
        <last>Jay Doe</last>
      </name>
      <postcode>PA45 6AL</postcode>
      <premise>No 456</premise>
      <street>Trust Street</street>
      <town>Caernarfon</town>
    </customer>
    <error>
      <code>0</code>
      <message>Ok</message>
    </error>
    <live>0</live>
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
      <parenttransactionreference>72-32-20002</parenttransactionreference>
    </operation>
    <paypal>
      <addressstatus>Unconfirmed</addressstatus>
      <payerid>4d22e2606apid</payerid>
      <payerstatus>unverified</payerstatus>
    </paypal>
    <settlement>
      <settleduedate>2020-06-01</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <timestamp>2020-06-01 15:36:00</timestamp>
    <transactionreference>72-32-20003</transactionreference>
  </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. 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.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
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. This is a deprecated check and PayPal will always return the value “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. This is a deprecated check and PayPal will always return the value “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)	“0” indicates no issues have been raised so far that would prevent settlement from taking place. “3” indicates the request was unsuccessful.
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.
customercountryiso2a XPath: /customer/country	Alpha (2)	The country of the delivery address returned from PayPal. This will need to be in ISO2A format. Click here for a full list of country codes. Returned from PayPal if available.
customercounty XPath: /customer/county	Alphanumeric including symbols (127)	The county of the delivery address returned from PayPal. For US addresses, the 2-character state code, is returned here. Returned from PayPal if available.
customeremail XPath: /customer/email	Email (255)	The delivery email address returned from PayPal. Maximum length of 255 (maximum of 64 characters before the ”@” symbol). Returned from PayPal if available.
customerip XPath: /customer/ip	IP address (39)	The IP address of the device used to process the order. Returned from PayPal if available.
customerlastname XPath: /customer/name/last	Alphanumeric including symbols (127)	The full name for the delivery returned from PayPal. Returned from PayPal if available.
customerpostcode XPath: /customer/postcode	Alphanumeric (25)	The postcode (ZIP code) of the delivery address returned from PayPal. Returned from PayPal if available.
customerpremise XPath: /customer/premise	Alphanumeric including symbols (25)	The first line of the delivery address returned from PayPal. Returned from PayPal if available.
customerstreet XPath: /customer/street	Alphanumeric including symbols (127)	The second line of the delivery address returned from PayPal. Returned from PayPal if available.
customertown XPath: /customer/town	Alphanumeric including symbols (127)	The town of the delivery address returned from PayPal. Returned from PayPal if available.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.
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.

Display summary page to the customer

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 practices

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.

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 tax and any additional shipping fees added to the initial transaction amount (if applicable). See below for further information on shipping fees.

About shipping fees

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 shipping fee to the transaction cost.

Regardless of any shipping fees, 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) and tax 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 following fields:

baseamount - Total purchase amount including shipping fees and tax.
customershippingbaseamount - Shipping fees calculated using the delivery address returned from PayPal.

The additional charge applied to cover the shipping costs is decided by you. Generally speaking, there are three approaches to calculating the shipping fee:

Free shipping – You opt not to add any additional fees to the cost of the product and your business will cover the cost of shipping.
Fixed shipping price – You opt to add the same shipping fee to every order. This works best when you ensure the aforementioned charge has the same value as the average shipping 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 shipping cost and present this to the customer prior to completing the payment.

4. Process the authorisation

The AUTH request is to process the payment.

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 (ECS)

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 = {
  "baseamount": "2150",
  "customershippingbaseamount": "500",
  "parenttransactionreference": "72-32-20003",
  "paymenttypedescription": "PAYPAL",
  "requesttypedescription": "AUTH",
  "sitereference": "test_site12345"
}

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(
  'baseamount' => '2150',
  'customershippingbaseamount' => '500',
  'parenttransactionreference' => '72-32-20003',
  'paymenttypedescription' => 'PAYPAL',
  'requesttypedescription' => 'AUTH',
  'sitereference' => 'test_site12345'
);

$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": [{
    "baseamount": "2150",
    "customershippingbaseamount": "500",
    "parenttransactionreference": "72-32-20003",
    "paymenttypedescription": "PAYPAL",
    "requesttypedescription": "AUTH",
    "sitereference": "test_site12345"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "baseamount": "2150",
    "customershippingbaseamount": "500",
    "parenttransactionreference":"72-32-20003",
    "paymenttypedescription":"PAYPAL",
    "requesttypedescription":"AUTH",
    "sitereference":"test_site12345"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <billing>
      <amount>2150</amount>
    </billing>
    <customer>
      <shippingamount>500</shippingamount>
    </customer>
    <operation>
      <parenttransactionreference>72-32-20003</parenttransactionreference>
      <sitereference>test_site12345</sitereference>
    </operation>
    <billing>
      <payment type="PAYPAL"/>
    </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”.
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.
baseamount XPath: /billing/amount	Numeric (11)	With the addition of the shipping fee, if the total order amount now differs from the baseamount submitted in the ORDER request, you must submit the baseamount with the updated total amount in the AUTH request. e.g. Final baseamount = the sum of (productbaseamount x productquantity) + the sum of (producttaxbaseamount x productquantity) + Final customershippingbaseamount The baseamount is submitted in base units, with no commas or decimal points, e.g. €10 is submitted as 1000.
customershippingbaseamount XPath: /customer/shippingamount	Numeric (11)	This amount is the total spent on shipping in base units. This must be the final shipping amount as this cannot be updated again prior to the customer completing the purchase. The customershippingbaseamount is submitted in base units, with no commas or decimal points, e.g. €10 is submitted as 1000.

AUTH response (ECS)

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 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u 'CREATED',
u 'authcode': u '44782-D149613359266',
u 'baseamount': u '2150',
u 'currencyiso3a': u 'GBP',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'livestatus': u '0',
u 'merchantname': u 'Test Merchant',
u 'operatorname': u 'webservices@example.com',
u 'parenttransactionreference': u '72-32-20003',
u 'paymenttypedescription': u 'PAYPAL',
u 'requesttypedescription': u 'AUTH',
u 'settleduedate': u '2020-06-01',
u 'settlestatus': u '0',
u 'transactionreference': u '72-32-20004',
u 'transactionstartedtimestamp': u '2020-06-01 15:36:20'
}]
}

array(3) {
  ["requestreference"] => string(9) "A58cdfkpy"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] =>array(17) {
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(7) "CREATED"
      ["authcode"] => string(19) "44782-D149613359266"
      ["baseamount"] => string(4) "2150"
      ["currencyiso3a"] => string(3) "GBP"
      ["errorcode"] => string(1) "0"
      ["errormessage"] => string(2) "Ok"
      ["livestatus"] => string(1) "0"
      ["merchantname"] => string(13) "Test Merchant"
      ["operatorname"] => string(23) "webservices@example.com"
      ["parenttransactionreference"] => string(11) "72-32-20003"
      ["paymenttypedescription"] => string(6) "PAYPAL"
      ["requesttypedescription"] => string(4) "AUTH"
      ["settleduedate"] => string(10) "2020-06-01"
      ["settlestatus"] => string(1) "0"
      ["transactionreference"] => string(11) "72-32-20004"
      ["transactionstartedtimestamp"] => string(19) "2020-06-01 15:36:20"
    }
  }
}

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"ECOM",
    "acquirerresponsecode":"CREATED",
    "authcode":"44782-D149613359266",
    "baseamount":"2150",
    "currencyiso3a":"GBP",
    "errorcode":"0",
    "errormessage":"Ok",
    "livestatus":"0",
    "merchantname":"Test Merchant",
    "operatorname":"webservices@example.com",
    "parenttransactionreference":"72-32-20003",
    "paymenttypedescription":"PAYPAL",
    "requesttypedescription":"AUTH",
    "settleduedate":"2020-06-01",
    "settlestatus":"0",
    "transactionreference":"72-32-20004",
    "transactionstartedtimestamp":"2020-06-01 15:36:20"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>X538160153</requestreference>
  <response type="AUTH">
    <acquirerresponsecode>CREATED</acquirerresponsecode>
    <authcode>83154-D140912749345</authcode>
    <billing>
      <amount currencycode="GBP">2150</amount>
      <payment type="PAYPAL"/>
    </billing>
    <error>
      <code>0</code>
      <message>Ok</message>
    </error>
    <live>0</live>
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <operatorname>webservices@example.com</operatorname>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
      <parenttransactionreference>72-32-20003</parenttransactionreference>
    </operation>
    <settlement>
      <settleduedate>2020-06-01</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <timestamp>2020-06-01 15:36:20</timestamp>
    <transactionreference>72-32-20004</transactionreference>
  </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.
baseamount XPath: /billing/amount	Numeric (11)	The total 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. 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.
errormessage XPath: /error/message	Alphanumeric (255)	This is the corresponding message to the above code. Click here for a full list of errorcode and message values.
livestatus XPath: /live	Numeric (1)	0 – Transaction processed using a test account. 1 – Transaction processed using a live account.
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. (See below for info on settlement)
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.
authcode XPath: /authcode	Alphanumeric (255)	The authorisation code provided by the issuing bank. Only returned if the transaction is authorised.
errordata XPath: /error/data	Alphanumeric (255)	Additional information to help troubleshoot the error. Only returned if there has been an error.
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.

5. Payment completion

Settlement

By default, once a PayPal transaction has been authorised, funds will typically be settled into your bank account within 24 hours:

Following authorisation, the Settle status is set to 0 to indicate settlement is pending.
On a daily basis, Trust Payments initiates the settlement process for pending PayPal transactions.
The Settle status of a PayPal transaction is updated to 10 when settlement is in progress.
Shortly afterwards, Trust Payments receives confirmation from PayPal that funds have been settled and the Settle status is updated to 100.

About Pay Later

When handling order enquiries from customers, please remember that a customer may have opted to spread the cost of the purchase via PayPal's Pay Later products.

Regardless of how the customer chose to fund the transaction, you will always be paid in full at time of purchase, as with a conventional PayPal transaction.

Alternative settlement flows

Deferred settlement

The settlement is deferred until you submit a TRANSACTIONUPDATE with settlestatus=0.

PayPal transactions can be deferred for up to 31 days.

Immediate settlement

Immediate settlement functionality is subject to additional requirements.

Before processing immediate settlement, you must contact our Support Team and request for this to be enabled on your account.

If PayPal needs more time to perform checks, the transaction may be temporarily set to Settle status 10.

Partial settlement

You can opt to settle a lower amount than was originally authorised. To do so, submit a TRANSACTIONUPDATE with a lower settlebaseamount.

Notifications

Before you begin testing, we recommend that you contact our Support Team and request that rules are enabled on your account, which submit URL notifications to your system in the following scenarios:

When a payment is authorised (AUTH has errorcode=0).
When funds have been settled (AUTH in settlestatus=100).

When contacting Support, please provide your site reference and the endpoint to which the notification will be sent.

On authorisation: If the settlestatus is “0”, “1” or “10”, the payment has been authorised and you are not required to take further action at this time. However, values of “2” or “3” indicate funds are not scheduled for settlement (deferred and cancelled, respectively).
On settlement: If the settlestatus has been updated to “100”, this indicates that the funds have been settled. Alternatively, if this has been updated to “3”, this indicates there has been a problem and the payment was subsequently cancelled.

Refunds

The process of processing PayPal refunds is the same as refunding a standard card transaction, but please first review the following:

To ensure your records with Trust Payments remain in sync with Paypal, we strongly recommend that you perform refunds exclusively using the Trust Payments platform, rather than through the PayPal admin portal.

You must ensure you refund the AUTH request, and NOT pass through references to any related ORDER or ORDERDETAILS requests.

Most PayPal refunds are settled immediately (settlestatus=100). However, under certain conditions defined by PayPal, refunds can be set to settlestatus=10 (“settling”), which is an intermediate step prior to settlement. If a PayPal refund on your account is in settlestatus=10, it is recommended you query it with our Support Team in case further actions need to be completed to ensure settlement.

About Pay Later

When handling refund enquiries from customers, please remember that a customer may have opted to spread the cost of the initial purchase via PayPal's Pay Later products.

When a refund is performed, the funds are debited from your bank account and PayPal is responsible for ensuring the customer is credited accordingly.

With the above notes in mind, click the links below to open instructions on performing PayPal refunds in a new tab:

Further reading on this topic