Getting started with Payment Pages

  Before proceeding, please ensure you have met all requirements
Click here to open this information in a new tab

 

Our Payment Pages solution is for merchants who want a simple and easily implemented way of adding e-payment capability to their online commerce systems. Payment Pages work with custom-designed e-commerce systems as well as with many commercially available shopping cart applications.

  Features:

  • Process payments on our own dedicated HTTPS servers (that use the SSL protocol) that allow you to process secure and reliable transactions.
  • Process payments without storing credit card details on your server.
  • Customise the Payment Pages with custom CSS to maintain the look and feel of your online store.
  • Accept a large variety of currencies.
  • Track all transactions using our online transaction management system, MyST.

Please follow the steps below to get started with Payment Pages:

 

             

 

1. Construct a basic payment form

Web_Developer_Flatline.png

Here is an example HTML form that can be used as a template when redirecting your customers to the Payment Pages. Start by copying and pasting the below to a text file and save as an HTML form.

<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="currencyiso3a" value="USD">
<input type="hidden" name="mainamount" value="100.00">
<input type="hidden" name="version" value="2">
<input type="submit" value="Pay">
</form>
</body>
</html>

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

 

Change the site reference in the HTML to include the test site reference provided when you signed up. Update the other fields as needed, using the table below. For now, we’re only covering the required fields, but you can submit more fields if needed (click here for a full list).

Required fields Description
sitereference The unique reference that you receive when you sign up.
currencyiso3a The transaction currency code (in ISO3A format).
mainamount

The amount of the transaction should be in main units.

Only include the amount value and the decimal place (no commas).

e.g. £10.99 would be submitted as 10.99

Currencies such as Japanese Yen which do not require a decimal place are submitted without. e.g. 1000 Yen would be 1000

version This value will be set to 2.
stprofile

Used to specify the styling used to render the Payment Pages. When using the default appearance, this is set to “default” (click here for further information on profiles).

  Click here for full field specification

 

Save the above as an HTML file. You can open this in your web browser, and a “Pay” button will be displayed. Click this button, and you will be redirected to your test site, where you can process test payments.

If you have configured the HTML above correctly, you should be able to view the following Payment Page hosted by Trust Payments:

ppg-quickstart-01.png

When testing, you can use the following test card details to simulate a “Successful” response:

  • Visa card ‘4111 1111 1111 1111’ or Mastercard ‘5100 0000 0000 0511’
  • Set expiry date to any valid date in the future
  • Use security code “123”

 

             

 

2. Redirect customer's browser following payment

Order_Confirmed_Flatline.png

By default, when a transaction has been processed, our response page will be displayed to the customer. This displays a message indicating whether or not the transaction was successful, along with details regarding the payment for the customer’s records. Alternatively, you may prefer to host a response page on your own server to be displayed following a successful transaction.

Redirects can be configured on your site by adding the following to your POST to Payment Pages:

<!--Enables rule that redirects the customer following a successful transaction-->
<input type=hidden name="ruleidentifier" value="STR-6">

<!--Update the below with the URL for the redirect-->
<input type=hidden name="successfulurlredirect" value="http://yourwebsite.com/successful">

The URL of your hosted response page must be externally facing. We cannot redirect to internal, intranet, private or loopback addresses.

  We recommend only redirecting to secure HTTPS pages. When using iframes, some web browsers will refuse to redirect to non-secure pages as a security measure.

  If an error occurs (e.g. decline), we will redisplay the payment form with an error, prompting them to try a different method of payment (recommended). Alternatively, you can instead opt to redirect customers back to your site when an error occurs. Click here to learn more.

  Click here for redirects documentation

 

             

 

3. Configure notifications to your server

Data_Center_Flatline.png

You can request notifications be sent following transactions on the Payment Pages.

 

Configuring notifications

Click the headings below to learn how to configure notifications that are sent following different transaction outcomes:

Customer email receipt

These are sent to the email address specified in the billingemail field. They are configured to be sent to customers following payment, summarising the transaction and acting as a receipt of payment for their records. By default, they look like this:

ppg-notifications-customer.png

 

It is simple to enable email notifications on a transaction-by-transaction basis. For requests where you would like to receive customer email notifications, you will need to add the following fields to your POST to the Payment Pages:

<!--Sends email confirmation to the customer, following successful transaction:-->
<input type=hidden name="ruleidentifier" value="STR-2">

<!--Sends email confirmation to the customer, following declined transaction:-->
<input type=hidden name="ruleidentifier" value="STR-3">

  You can customise the appearance of emails sent to the customer:

  • Swap out the Trust Payments logo for your own company logo.
  • Customise layout and appearance of email by uploading your own markup.

Click here to learn more.

Merchant email notifications

These are configured to be sent to members of your company or organisation, and are sent to an email address of your choosing. By default, they look like this:

ppg-notifications-merchant.png

 

It is simple to enable email notifications on a transaction-by-transaction basis. For requests where you would like to receive merchant email notifications, you will need to add the following fields to your POST to the Payment Pages:

<!--Sends email confirmation to the merchant, following successful transaction:-->
<input type=hidden name="ruleidentifier" value="STR-4">

<!--Sends email confirmation to the merchant, following declined transaction:-->
<input type=hidden name="ruleidentifier" value="STR-5">

<!--IMPORTANT: You also need to include the merchant’s email address for merchant emails to work-->
<input type=hidden name="merchantemail" value="merchant@email.com">
URL notifications (Webhooks)

You can configure URL notifications (webhooks) to be submitted to your system automatically whenever transactions are processed on your site. We support three types of URL notifications, which can be enabled/disabled independently of each other, by updating your HTTPS POST with the examples below:

Success case Decline case All payments
<!--This enables the successful URL notification rule-->
<input type=hidden name="ruleidentifier" value="STR-8">

<!--Successful URL notification destination-->
<input type=hidden name="successfulurlnotification" value="http://yourwebsite.com/successful">

Handling URL notifications

You must configure your system to accept the incoming URL notifications on port 443. If the response site security hash is correct (see below), your system must respond with an HTTP 200 OK response (e.g. “HTTP/1.0 200 OK”) within 8 seconds of receiving a notification.

One notification is sent per request, but if your system does not respond, Trust Payments will continue to resend notifications for up to 48 hours until confirmation is received.

If we do not receive confirmation within 48 hours, we will send an email with further details to the default email address associated with your site reference (contact our Support Team to update this address).

 

Fields returned

URL notifications using system rules (STR-x) will include the following fields of information, by default:

  • transactionreference
  • requestreference
  • orderreference
  • sitereference
  • errorcode
  • settlestatus
  • paymenttypedescription

 

Please refer to the following resources for further information:

  Customer email notifications   Merchant email notifications   URL notifications

 

             

 

4. Secure your requests using Site Security

Completed_task__Flatline.png

For security reasons, your system must include the additional field sitesecurity in the POST, to ensure requests to the Payment Pages cannot be modified by a customer or third party. This field contains a hash that is generated from a selection of designated fields, including a password that has been established with the Support Team.

 First, you will need to learn how to generate the site security hash:

Click here to open the instructions in a new tab on how to generate the sitesecurity hash.
Follow these instructions carefully and then look at the final step below to submit the hash in your POST.

When posting to the Payment Pages, you will need to include the sitesecurity and sitesecuritytimestamp fields in the POST, as shown below:

<html>
<head>
</head>
<body>
<!--YOUR HTML-->
<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="currencyiso3a" value="USD">
<input type="hidden" name="mainamount" value="100.00">
<input type="hidden" name="version" value="2">
<input type="hidden" name="orderreference" value="myorder12345">
<input type="hidden" name="sitesecurity" value="hee879a9ab97753b3a768925d50842f10e19fea03fef0b820026b6df92d415866">
<input type="hidden" name="sitesecuritytimestamp" value="2019-05-28 14:22:37">
<input type="submit" value="Pay">
</form>
</body>
</html>

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

As accurately as possible, the sitesecuritytimestamp should reflect the time the customer’s browser is to be redirected to the Payment Pages.

The value submitted in this field must be in the format YYYY-MM-DD hh:mm:ss.
The timestamp must be in the UTC time zone. (e.g. “2019-05-28 14:22:37”)

The customer has 3 hours from the time specified to complete the transaction, otherwise an error will be displayed on screen.

 

For any payment that is attempted with an incorrect hash, the customer will be presented with an error (example below) and no payment will be processed:

ppg-site-security-for-requests.png

 

Response site security

After request site security has been enabled on your site, the redirects and URL notifications configured above will also include the response site security hash. This is in the form of a hashed responsesitesecurity value in any URL notifications sent to your system. You must recalculate the responsesitesecurity hash returned, to ensure it has not been modified by a customer or third party and that the fields were sent by Trust Payments.

Checklist__Flatline.png

  Once you have completed the steps above, we recommend returning to the Getting started page to learn more about enabling add-ons, testing your solution and going live.

Click here to open the Getting started page.

 

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