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:


  1. 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.

  2. 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.

     

  3. 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.

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

 


 

CP89.png

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:

  Express Checkout Mark (ECM)   Express Checkout Shortcut (ECS)

  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.

CW21-EN.png

  • 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)

piggy-icon.jpg

 

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

  1. Contact our Support Team and enquire about enabling PayPal on your TRU Connect account.
  2. Our Support Team will provide you with a URL to complete the setup.
  3. 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.
  4. 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.
  5. 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.
  6. 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

wsapi-ecm-05.png

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)
Python PHP cURL Raw JSON Raw XML
#!/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

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

  Field Format Description
X1-EN.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Only “ECOM” (e-commerce) is supported.
X1-EN.png 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.

X1-EN.png cancelurl
XPath: /merchant/cancelurl
URL (2048) The URL that the customer will be returned to if they cancel the authorisation on their PayPal account.
X1-EN.png 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.

X1-EN.png 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.

X1-EN.png 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.

X1-EN.png customertown
XPath: /customer/town
Alphanumeric including symbols (127)

The delivery address town.

X1-EN.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value must be submitted as “PAYPAL”.
X1-EN.png 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.
X1-EN.png 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.
X1-EN.png 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.

X1-EN.png products » productcurrencyiso3a
XPath: /operation/products/amount/@currencycode
ISO3A

The currency associated with the productbaseamount. If submitted, this must be the same as currencyiso3a.

X1-EN.png products » productquantity
XPath: /operation/products/quantity
Numeric (10) Quantity of the given product in the order.
X1-EN.png products » producttitle
XPath: /operation/products/title
Alphanumeric (127) The name or title of the given product.
X2-EN.png 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.

X2-EN.png 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.

X2-EN.png 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.

X2-EN.png

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.

X2-EN.png 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.

X1-EN.png requesttypedescription
XPath: /@type
Alpha (20) The value in the request must be “ORDER”.
X1-EN.png returnurl
XPath: /merchant/returnurl
URL (2048) The URL that the customer will be returned to following a successful authorisation on their PayPal account.
X1-EN.png 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.
X2-EN.png 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

X2-EN.png 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.

X2-EN.png 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.

X2-EN.png 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.

X2-EN.png customerpremise
XPath: /customer/premise
Alphanumeric including symbols (25)

The first line of the delivery address.

Required if paypaladdressoverride is set to "1". Otherwise, optional.

X2-EN.png 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.

X2-EN.png 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.

X2-EN.png 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.

X2-EN.png 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.

X3-EN.png 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".

X3-EN.png customermiddlename
XPath: /customer/name/middle
Alphanumeric including symbols (127)

The customer’s middle name(s).

X3-EN.png 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.

X3-EN.png customerstreet
XPath: /customer/street
Alphanumeric including symbols (127)

The second line of the delivery address.

X3-EN.png customershippingcurrencyiso3a
XPath: /customer/shippingamount/@currencycode
ISO3A

The currency associated with the customershippingbaseamount. If submitted, this must be the same as currencyiso3a.

X3-EN.png customersuffixname
XPath: /customer/name/suffix
Alphanumeric including symbols (25)

The customer’s suffix name (e.g. Bsc).

X3-EN.png 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.

X3-EN.png 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).

X3-EN.png 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)
Python PHP Raw JSON Raw XML
{
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'
}]
}

 

Field specification

  Field Format Description
X4-EN.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) The value returned is “ECOM”.
X4-EN.png 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.

X4-EN.png 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.

X4-EN.png livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
X4-EN.png operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
X4-EN.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) The value returned is “PAYPAL”.
X4-EN.png 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.
X4-EN.png redirecturl
XPath: /paypal/redirecturl
URL (255) Redirect the customer’s browser to this URL, to allow them to sign in to their PayPal account.
X4-EN.png requesttypedescription
XPath: /@type
Alpha (20) The value returned is “ORDER”.
X4-EN.png settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
X4-EN.png 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.
X4-EN.png transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
A unique reference for the request assigned by Trust Payments.
X4-EN.png transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time the request was processed.
X2-EN.png 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. Your system will need to redirect the customer’s browser to this URL, which is a page hosted by PayPal, in order to process the payment.

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

Python PHP cURL Raw JSON Raw XML
#!/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

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

  Field Format Description
X1-EN.png parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
Submit the transactionreference returned in the preceding ORDER response.
X1-EN.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value must be submitted as “PAYPAL”.
X1-EN.png

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.
X1-EN.png 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).

Python PHP Raw JSON Raw XML
{
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'

}]
}

 

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
X4-EN.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) The value returned is “ECOM”.
X4-EN.png 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.

X4-EN.png 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.

X4-EN.png livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
X4-EN.png operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
X4-EN.png 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.
X4-EN.png
Only returned in AUTH response
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) The value returned is “PAYPAL”.
X4-EN.png
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”.
X4-EN.png
Only returned in ORDERDETAILS response
paypalpayerid
XPath: /paypal/payerid
Alphanumeric (255) Unique PayPal customer account number.
X4-EN.png
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”.

X4-EN.png requesttypedescription
XPath: /@type
Alpha (20) “ORDERDETAILS” and “AUTH” are returned in their respective responses.
X4-EN.png settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
X4-EN.png 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)

X4-EN.png transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
Unique references for both requests, assigned by Trust Payments.
X4-EN.png transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time each request was processed.

X2-EN.png

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.

X2-EN.png

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.

X2-EN.png

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.

X2-EN.png

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.

X2-EN.png

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.

X2-EN.png

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.

X2-EN.png

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.

X2-EN.png

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.

X2-EN.png

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.

X2-EN.png 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.

X2-EN.png 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:

  1. Following authorisation, the Settle status is set to 0 to indicate settlement is pending.
  2. On a daily basis, Trust Payments initiates the settlement process for pending PayPal transactions.
  3. The Settle status of a PayPal transaction is updated to 10 when settlement is in progress.
  4. 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:

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request