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 POST submitted to Trust Payments to include additional information on all products in the customer's order.
Each POST 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.
The full field specification can be found in the Configuration section below.
Merchants operating in certain sectors that PayPal deems to be high risk will also need to update the POST to submit the following additional fields:
- The products array above must also include the following additional fields for each product in the customer's order:
- productcode - The Stock Keeping Unit (SKU) of the product.
- productdescription - A description of the product.
- producttaxmainamount - The tax applied to the product.
- producttaxcurrencyiso3a - The currency associated with the tax applied.
- producttype - Choose a product type from "digital", "physical" or "gift".
- paypaltransactionriskcontextdata containing an array of JSON objects, each containing the fields paypaltransactionriskcontextdatakey and paypaltransactionriskcontextdatavalue.
-
You can now submit the shipping amount to Trust Payments during the checkout process.
-
If you know the final shipping amount at the start of the order, this should be submitted in the POST in the customershippingmainamount 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.
- 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.
-
-
If you have configured URL notifications or email notifications to include the fields paypaladdressstatus and paypalpayerstatus, these fields have been deprecated. Because of this, paypaladdressstatus will now always return "Unconfirmed" and paypalpayerstatus will always return "unverified".
Only the changes above are needed to upgrade your PayPal integration to the latest platform, delivering an improved customer experience on your Payment Pages checkout. Providing the transaction meets the requirements defined by PayPal, Pay Later options will also be shown on your pages automatically following the upgrade.
We recommend you first deploy these changes to a staging environment and test your integration before deploying to a production environment. In particular, you should ensure you understand the new Pay Later options that can now be displayed and ensure your solution accounts for this. 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.
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. |
How it works
Overview
Pay Later
The Payment Pages will automatically display a "Pay Later" button for transactions that meet PayPal's requirements for this functionality. Selecting this option presents customers with additional options to spread out the cost of their purchase. They can complete the transaction using PayPal Credit or instalments.
If a transaction does not meet PayPal's requirements, the "Pay Later" button will not be shown. In that case, customers can still complete a standard PayPal transaction or use other available payment methods.
The Buttons
Once PayPal has been enabled, there will be two additional buttons displayed to allow customers to check out with PayPal:
- PayPal Checkout - Designed to capture the attention of customers looking for a streamlined way to pay in full.
- Pay Later - This will present customers with options to spread the cost of the purchase by allowing payment via credit or instalments.
As seen on the Choice Page
As seen on the Details Page
Using PayPal
Clicking either of the PayPal buttons described above will display a pop-up window above the Payment Pages checkout, which itself will be darkened to better focus the attention of the customer on the pop-up. If the customer is not already logged into their PayPal account, they will be prompted to do so before continuing.
The rest of the checkout experience is hosted by PayPal from within the pop-up window:
When clicking the PayPal Checkout button, the pop-up will typically ask the customer to select from their previously-saved credit/debit cards or bank accounts, or alternatively add a new method of payment to facilitate the transaction.
If the requirements for Pay Later are met, the customer will also be presented with "PayPal Credit" and "Pay in 3" options. If the customer selects one of the Pay Later options, the flow will seamlessly adapt to accommodate these preferences.
Pay Later services are overseen by PayPal and are subject to change. When a customer checks out with PayPal, they will be clearly presented the terms of payment. The terms agreed to by the customer at checkout are final.
When clicking the Pay Later button, the pop-up will prompt the customer to choose between the Pay Later options available in their region. The options available and associated terms differ depending on the country in which your business operates.
Click here to learn more (link to external site)
Pay Later services are overseen by PayPal and are subject to change. When a customer checks out with PayPal, they will be clearly presented the terms of payment. The terms agreed to by the customer at checkout are final.
If the customer decides they'd prefer to pay in full immediately, they can select "Pay now" from the tabs along the top of the pop-up to seamlessly switch over to that flow, where they can select their preferred method of payment to facilitate the purchase.
In all flows, the customer will be presented with a summary of the order to review, explaining the amount to be paid today and, if applicable, when subsequent payments will be debited from their account to facilitate a Pay Later order. The customer can then complete the transaction and will be shown a success message.
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.
- You will need to register a Personal User in PayPal's sandbox environment in order to perform test transactions.
Click here to register the sandbox user with PayPal (link to external site). - PayPal does not support Payment Pages in an iframe. If you are deploying Payment Pages in an iframe to process card payments and would also like to add PayPal, you will need to look at our Webservices API integration options and consider deploying our ECM solution.
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.
Configuration
Update the POST to Payment Pages on your checkout
Once you have completed the above, you will need to modify your POST to Payment Pages with additional fields. Please refer to the example and accompanying field specification below:
The following example includes the required fields for PayPal transactions. However, we recommend posting as much product information as you have available. Please refer to the table below for a full list of product fields.
<html>
<body>
<form method="POST" action="<DOMAIN>/process/payments/choice">
<input type="hidden" name="sitereference" value="test_site12345">
<input type="hidden" name="stprofile" value="default">
<input type="hidden" name="mainamount" value="20.00">
<input type="hidden" name="currencyiso3a" value="GBP">
<input type="hidden" name="version" value="2">
<input type="hidden" name="orderreference" value="TEST">
<input type="hidden" name="customercountryiso2a" value="GB">
<input type="hidden" name="customerpostcode" value="TR45 6ST">
<input type="hidden" name="customertown" value="Bangor">
<input type="hidden" name="products" value='[
{
"productmainamount": "2.00",
"productcurrencyiso3a": "GBP",
"productquantity": "5",
"producttitle": "Item 1"
},
{
"productmainamount": "5.00",
"productcurrencyiso3a": "GBP",
"productquantity": "1",
"producttitle": "Item 2"
}
]'>
<input type="submit" value="Pay">
</form>
</body>
</html>
| Field | Format | Description | |
|
The fields below should be considered in addition to the required fields listed in the Getting started article. If you haven't already read this, we recommend starting there. |
|||
| products | Array of JSON Objects | An HTML input element must be included in the HTML form in the POST including the name="products" attribute and the following subfields must also be included in an array of JSON Objects in the value= attribute. The array of JSON Objects in the value= attribute is repeated where multiple products make up the total main amount. Please refer to the example POST above. | |
| products » productmainamount | Numeric (12) |
This amount is the price of the given product in main units. This is per unit, e.g. it doesn't matter if the customer purchases 1 or 5 of this product - the productmainamount will stay the same. This amount does not include tax or shipping. |
|
| products » productcurrencyiso3a | ISO3A |
The currency associated with the productmainamount. |
|
| products » productquantity | Numeric (10) | Quantity of the given product in the order. | |
| products » producttitle | Alphanumeric (127) | The name or title of the given product. | |
| products » productcode | 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 | 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 » producttaxcurrencyiso3a | ISO3A |
The currency associated with the producttaxmainamount. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure. |
|
| products » producttaxmainamount | Numeric (12) |
Tax amount for 1 unit of the given product, in main units. Required by merchants operating in certain sectors that PayPal deems to be high risk. Contact our Support Team if you're unsure. |
|
| products » producttype | 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. |
|
| customercountryiso2a | ISO2A |
The delivery address country. This will need to be in ISO2A format. Click here for a full list of country codes. Required when paypaladdressoverride submitted is 1. |
|
| customercounty |
Alphanumeric including symbols (127) |
The delivery address county. This is displayed as “State code (eg. NY)” on pages with US locale and “County” on other configurations. 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 |
Alphanumeric including symbols (127) |
The customer's first name. Required if paypaladdressoverride is set to "1" or "2". Otherwise, optional. |
|
| customerlastname |
Alphanumeric including symbols (127) |
The customer's last name. Required if paypaladdressoverride is set to "1" or "2". Otherwise, optional. |
|
| customerpostcode | Alphanumeric (25) |
The delivery address postcode or ZIP code. This must be a valid postcode/ZIP code for the customercountryiso2a submitted. Required when paypaladdressoverride submitted is 1. |
|
| customerprefixname | 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 |
Alphanumeric including symbols (25) |
The delivery address house name or number. Required when paypaladdressoverride submitted is 1. |
|
| customertown |
Alphanumeric including symbols (127) |
The delivery address town. Required when paypaladdressoverride submitted is 1. |
|
| paypaltransactionriskcontextdata | Array of JSON Objects |
This array of JSON Objects 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 | 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 | 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. |
|
| paypaltransactionriskcontextdata » 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. |
|
| billingemail | Email (255) | The billing email address. This can then be used for correspondence with the customer. Maximum length of 255 (maximum of 64 characters before the ”@” symbol). | |
| 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". |
|
| customershippingcurrencyiso3a | ISO3A | The currency associated with the customershippingbaseamount. | |
| customershippingmainamount | Numeric (12) | This amount is the total spent on shipping in main units. | |
| customerstreet | Alphanumeric including symbols (127) |
The customer’s street name. |
|
| orderreference |
Alphanumeric including 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 own reference for the transaction. This can be useful when matching transactions to orders within your system. | |
| paypaladdressoverride | Numeric (20) |
By default, the customer selects their delivery address from their PayPal account. Alternatively, the customer can use the address entered on your website. This behaviour is controlled by sending the paypaladdressoverride field in the initial POST to the Payment Pages:
|
|
| paypallocaleiso2a | ISO2A | Use this field to localise the content displayed on the PayPal checkout. For a full list of supported values that can be submitted in this field (e.g. paypallocaleiso2a=GB for the UK), please refer to PayPal’s documentation (link to external site). | |
| settlestatus | Numeric (3) |
This determines the settlement flow. Submit one of the following:
You can have your site reference(s) configured to request PayPal transactions are settled immediately. |
|
If you are submitting the customer's delivery address and paypaladdressoverride=1 or 2 in the POST to Payment Pages, we recommend that you protect the delivery fields listed above from unauthorised changes by adding them to the list of designated fields for your request site security.
Testing
You will need to test your solution before you can begin processing live payments. Test transactions are processed through your test Site Reference.
When performing test transactions, 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. Follow the instructions on-screen to complete a payment, after which, you will be redirected back to the Payment Pages.
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 POST to Payment Pages.
The settlement is deferred until you update the transaction with Settle status "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 POST to Payment Pages.
Trust Payments will attempt to settle funds immediately following 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, update the transaction with a lower Settle amount.
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.
- 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.
