Payment facilitator

Michael Buckley

September 06, 2023 09:51

This page outlines the specification that must be followed by Payment Facilitators when processing payments through the Trust Payments gateway.

The fields described on this page are only supported for Mastercard transactions. They are supported for merchants with a Trust Payments acquiring account, but if you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.

Process overview

There are two methods that can be used to include payment facilitator fields in requests submitted to the acquiring bank:

By assigning default values on your account
Using this method, the payment facilitator fields are automatically included in transactions processed on your account, with no additional configuration required. To configure your account to use this method, contact our Support Team, requesting that the payment facilitator functionality is enabled on your account, along with your preferred default values.
By manually including payment facilitator fields in your requests
Using this method allows you to specify different values on a request-by-request basis. To configure your account to use this method, contact our Support Team and request that the payment facilitator functionality is enabled on your account. Then you can update your requests using the following specification.

Submitting payment facilitator fields in a request

Failure to meet these requirements will result in an invalid field error being returned (30000).

Payment Pages

The payment facilitator fields can be included in the POST to Payment Pages, as shown in the following example:

It is imperative that the payment facilitator fields are included in the string used to generate your request site security hash. Failure to do so will result in the customer being shown an “Invalid details” error message.

(Example)

<form method="POST" action="<DOMAIN>/process/payments/choice">
  <input type="hidden" name="sitereference" value="test_site12345">
  <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="stprofile" value="default">
  <input type="hidden" name="chargedescription" value="TEST DESCRIPTOR">
  <input type="hidden" name="facilitatorid" value="98765432198">
  <input type="hidden" name="facilitatorname" value="FACILITATORS">
  <input type="hidden" name="independentsalesorgid" value="12345678912">
  <input type="hidden" name="submerchantid" value="000000000000000">
  <input type="submit" value="Pay">
</form>

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

JavaScript Library

The following is an example of a request where payment facilitator fields are included:

You will need to update the payload submitted within your JWT to include additional fields, as shown below. Submitting the payment facilitator fields in this way will always override any values stored on your account or inherited from a parent.

(Payload)

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "requesttypedescriptions":["THREEDQUERY","AUTH"],
    "chargedescription":"TEST DESCRIPTOR",
    "facilitatorid":"98765432198",
    "facilitatorname":"FACILITATORS",
    "independentsalesorgid":"12345678912",
    "submerchantid":"000000000000000"
  },
  "iat":1559033849,
  "iss":"jwt.user"
}

TRU Mobile (SDK)

The following is an example of a request where payment facilitator fields are included:

(Payload)

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener",
    "requesttypedescriptions":["THREEDQUERY","AUTH"],
    "chargedescription":"TEST DESCRIPTOR",
    "facilitatorid":"98765432198",
    "facilitatorname":"FACILITATORS",
    "independentsalesorgid":"12345678912",
    "submerchantid":"000000000000000"
  },
  "iat":1559033849,
  "iss":"jwt.user"
}

Webservices API

The following is an example of a request where payment facilitator fields are included:

You will need to update the request submitted to Trust Payments to include additional fields, as shown below. Submitting the payment facilitator fields in this way will always override any values stored on your account or inherited from a parent.

(Example)

#!/usr/bin/python
import securetrading

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

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "billingfirstname": "Joe",
  "billinglastname": "Bloggs",
  "billingpostcode": "TR456ST",
  "billingcountryiso2a": "GB",
  "chargedescription": "TEST DESCRIPTOR",
  "facilitatorid": "98765432198",
  "facilitatorname": "FACILITATORS",
  "independentsalesorgid": "12345678912",
  "submerchantid": "000000000000000",
  "pan": "4111111111111111",
  "expirydate": "12/2020",
  "securitycode": "123"
}

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(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'billingfirstname' => 'Joe',
  'billinglastname' => 'Bloggs',
  'billingpostcode' => 'TR456ST',
  'billingcountryiso2a' => 'GB',
  'chargedescription' => 'TEST DESCRIPTOR',
  'facilitatorid' => '98765432198',
  'facilitatorname' => 'FACILITATORS',
  'independentsalesorgid' => '12345678912',
  'submerchantid' => '000000000000000',
  'pan' => '4111111111111111',
  'expirydate' => '12/2020',
  'securitycode' => '123'
);

$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": [{
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "orderreference": "My_Order_123",
    "billingfirstname": "Joe",
    "billinglastname": "Bloggs",
    "billingpostcode": "TR456ST",
    "billingcountryiso2a": "GB",
    "chargedescription": "TEST DESCRIPTOR",
    "facilitatorid": "98765432198",
    "facilitatorname": "FACILITATORS",
    "independentsalesorgid": "12345678912",
    "submerchantid": "000000000000000",
    "accounttypedescription": "ECOM",
    "pan": "4111111111111111",
    "expirydate": "12/2020",
    "securitycode": "123"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_site12345",
    "baseamount":"1050",
    "orderreference":"My_Order_123",
    "billingfirstname":"Joe",
    "billinglastname":"Bloggs",
    "billingpostcode":"TR456ST",
    "billingcountryiso2a":"GB",
    "chargedescription":"TEST DESCRIPTOR",
    "facilitatorid":"98765432198",
    "facilitatorname":"FACILITATORS",
    "independentsalesorgid":"12345678912",
    "submerchantid":"000000000000000",
    "accounttypedescription":"ECOM",
    "pan":"4111111111111111",
    "expirydate":"12/2020",
    "securitycode":"123"
  }]
}

<requestblock version="3.67" >
  <alias>SECURETRADING</alias>
  <request type="AUTH">
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <merchant>
      <orderreference>My_Order_123</orderreference>
      <chargedescription>TEST DESCRIPTOR</chargedescription>
      <facilitatorid>98765432198</facilitatorid>
      <facilitatorname>FACILITATORS</facilitatorname>
      <independentsalesorgid>12345678912</independentsalesorgid>
      <submerchantid>000000000000000</submerchantid>
    </merchant>
    <billing>
      <name>
        <first>Joe</first>
        <last>Bloggs</last>
      </name>
      <amount currencycode="GBP">1900</amount>
      <country>GB</country>
      <postcode>TR456ST</postcode>
      <payment type="VISA">
        <expirydate>12/2020</expirydate>
        <pan>4111111111111111</pan>
        <securitycode>123</securitycode>
      </payment>
    </billing>
  </request>
</requestblock>

Field specification

All fields listed below are returned in the response if sent on to the acquiring bank.

Field	Format	Description
chargedescription XPath: /merchant/chargedescription	Alphanumeric including spaces and special characters (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.	The charge description is a field that we provide to the acquiring bank during a transaction. It is a basic description of the transaction that is shown on the customer’s bank statement. Only certain combinations of these fields can be submitted in the request. See below for further information.
facilitatorid XPath: /merchant/facilitatorid	Numeric (11)	The payment facilitator id assigned by Mastercard at time of registration. Only certain combinations of these fields can be submitted in the request. See below for further information.
facilitatorname XPath: /merchant/facilitatorname	Alphanumeric including spaces and special characters (3, 7 or 12)	The payment facilitator name agreed with Mastercard. Only certain combinations of these fields can be submitted in the request. See below for further information.
independentsalesorgid XPath: /merchant/independentsalesorgid	Numeric (11)	The ISO (Independent Sales Organisation) id assigned by Mastercard at time of registration. Only certain combinations of these fields can be submitted in the request. See below for further information.
submerchantid XPath: /merchant/submerchantid	Alphanumeric including spaces and special characters (15)	Value assigned by the payment facilitator when involved in the transaction. Only certain combinations of these fields can be submitted in the request. See below for further information.

The following payment facilitator field combinations are valid for a request:

chargedescription, facilitatorid, facilitatorname, independentsalesorgid, submerchantid.
chargedescription, facilitatorid, facilitatorname, submerchantid.
chargedescription, facilitatorname, independentsalesorgid

An invalid combination of facilitator fields sent in the request will result in an invalid field error (30000).

Additional notes

Supported request types

The payment facilitator fields can be submitted in the following request types using our Webservices API:

ACCOUNTCHECK
AUTH
REFUND
THREEDQUERY

Click here for a full list of request types.

Inheriting from parent requests

If you do not submit the payment facilitator fields in a request, and a parent transaction reference is specified, the payment facilitator fields are inherited from said parent, unless the parent request type is AUTH or REFUND.

Process overview

Submitting payment facilitator fields in a request

Field specification

Additional notes

Supported request types

Inheriting from parent requests

Articles in this section