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.
-
products containing an array of JSON objects, each containing the following fields for each product in the customer's order:
-
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.
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.
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.
#!/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:
|
|
| 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 |
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:
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:
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:
|
{
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&useraction=commit&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&useraction=commit&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&useraction=commit&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&useraction=commit&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.
|
|
| errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. | |
| livestatus XPath: /live |
Numeric (1) |
|
|
| operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. | |
| paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | The value returned is “PAYPAL”. | |
| paypaltoken XPath: /paypal/token |
Alphanumeric (255) | The token relates to the customer’s session within PayPal’s system. You should log this, as you can then use it in relation to any relevant queries you may have with PayPal. | |
| redirecturl XPath: /paypal/redirecturl |
URL (255) | Redirect the customer’s browser to this URL, to allow them to sign in to their PayPal account. | |
| requesttypedescription XPath: /@type |
Alpha (20) | The value returned is “ORDER”. | |
| settleduedate XPath: /settlement/settleduedate |
Date YYYY-MM-DD | The date on which the transaction will be settled. | |
| settlestatus XPath: /settlement/settlestatus |
Numeric (3) |
|
|
| transactionreference XPath: /transactionreference |
Alphanumeric including hyphens (25) |
A unique reference for the request assigned by Trust Payments. | |
| transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the request was processed. | |
| 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: |
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.
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 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. |
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.
Remember to check the error response in both ORDERDETAILS and AUTH responses. |
|
| 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. |
|
| livestatus XPath: /live |
Numeric (1) |
|
|
| operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. | |
| 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) |
(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
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 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.
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
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.
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 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.
#!/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 |
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:
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:
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:
|
|
| 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:
|
{
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&useraction=commit&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&useraction=commit&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&useraction=commit&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&useraction=commit&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.
|
|
| errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. | |
| livestatus XPath: /live |
Numeric (1) |
|
|
| operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. | |
| paymenttypedescription XPath: /billing/payment/@type |
Alpha (20) | The value returned is “PAYPAL”. | |
| paypaltoken XPath: /paypal/token |
Alphanumeric (255) | The token relates to the customer’s session within PayPal’s system. You should log this, as you can then use it in relation to any relevant queries you may have with PayPal. | |
| redirecturl XPath: /paypal/redirecturl |
URL (255) | Redirect the customer’s browser to this URL, to allow them to sign in to their PayPal account. | |
| requesttypedescription XPath: /@type |
Alpha (20) | The value returned is “ORDER”. | |
| settleduedate XPath: /settlement/settleduedate |
Date YYYY-MM-DD | The date on which the transaction will be settled. | |
| settlestatus XPath: /settlement/settlestatus |
Numeric (3) |
|
|
| transactionreference XPath: /transactionreference |
Alphanumeric including hyphens (25) |
A unique reference for the request assigned by Trust Payments. | |
| transactionstartedtimestamp XPath: /timestamp |
Date time YYYY-MM-DD hh:mm:ss | The time the request was processed. | |
| 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 to the endpoint as follows: |
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.
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. 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.
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. |
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.
|
|
| errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. | |
| livestatus XPath: /live |
Numeric (1) |
|
|
| operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. | |
| 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) |
|
|
| 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
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.
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. |
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
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”. | |
| 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.
|
|
| errormessage XPath: /error/message |
Alphanumeric (255) | This is the corresponding message to the above code. | |
| livestatus XPath: /live |
Numeric (1) |
|
|
| operatorname XPath: /merchant/operatorname |
Alphanumeric (255) | The value of this field contains the name of the user that processed the request. | |
| 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.
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
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 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.
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:
