A Payment Facilitator is an entity that facilitates payment processing for sponsored sub-merchants that accept card payments. The Payment Facilitator owns the relationship with their sponsored sub-merchants and receives funding for the transactions processed, and then funds the sponsored sub-merchants accordingly. This page specifies the field names that Trust Payments Payment Facilitator customers must include in requests sent to the Trust Payments gateway. For more information on becoming a Payment Facilitator, please contact our commercial team.
Submitting payment facilitator fields in a request
Failure to meet these requirements will result in an invalid field error being returned (30000).
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",
"pan":"4900490000000501",
"expirydate":"12/2030",
"securitycode":"123",
"facilitatorid":"987654",
"facilitatorname":"FAC",
"submerchantid":"999999999999999",
"chargedescription":"Test Sub Mer Name",
"merchantstreet":"1 Test Street",
"merchantcity":"Test City",
"merchantzipcode":"TR45 6ST",
"merchantcountryiso2a":"GB",
"requesttypedescriptions":["THREEDQUERY","AUTH"]
},
"iat":1559033849,
"iss":"jwt.user"
}
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 = {
"currencyiso3a": "GBP",
"requesttypedescriptions": ["AUTH"],
"sitereference": "test_site12345",
"baseamount": "1050",
"accounttypedescription": "MOTO",
"pan": "4111111111111111",
"expirydate": "12/2030",
"securitycode": "123",
"facilitatorid": "987654",
"facilitatorname": "FAC",
"submerchantid": "999999999999999",
"chargedescription": "Test Sub Mer Name",
"merchantstreet": "1 Test Street",
"merchantcity": "Test City",
"merchantzipcode": "TR45 6ST",
"merchantcountryiso2a": "GB"
}
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(
'currencyiso3a' => 'GBP',
'requesttypedescriptions' => array('AUTH'),
'sitereference' => 'test_site12345',
'baseamount' => '1050',
'accounttypedescription' => 'MOTO',
'pan' => '4111111111111111',
'expirydate' => '12/2030',
'securitycode' => '123',
'facilitatorid' => '987654',
'facilitatorname' => 'FAC',
'submerchantid' => '999999999999999',
'chargedescription' => 'Test Sub Mer Name',
'merchantstreet' => '1 Test Street',
'merchantcity' => 'Test City',
'merchantzipcode' => 'TR45 6ST',
'merchantcountryiso2a' => 'GB'
);
$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",
"accounttypedescription": "MOTO",
"pan": "4111111111111111",
"expirydate": "12/2030",
"securitycode": "123",
"facilitatorid": "987654",
"facilitatorname": "FAC",
"submerchantid": "999999999999999",
"chargedescription": "Test Sub Mer Name",
"merchantstreet": "1 Test Street",
"merchantcity": "Test City",
"merchantzipcode": "TR45 6ST",
"merchantcountryiso2a": "GB"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"currencyiso3a":"GBP",
"requesttypedescriptions":["AUTH"],
"sitereference":"test_site12345",
"baseamount":"1050",
"accounttypedescription":"MOTO",
"pan":"4111111111111111",
"expirydate":"12/2030",
"securitycode":"123",
"facilitatorid":"987654",
"facilitatorname":"FAC",
"submerchantid":"999999999999999",
"chargedescription":"Test Sub Mer Name",
"merchantstreet":"1 Test Street",
"merchantcity":"Test City",
"merchantzipcode":"TR45 6ST",
"merchantcountryiso2a":"GB"
}]
}
<requestblock version="3.67" >
<alias>webservices@example.com</alias>
<request type="AUTH">
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>MOTO</accounttypedescription>
</operation>
<merchant>
<facilitatorid>987654</facilitatorid>
<facilitatorname>FAC</facilitatorname>
<submerchantid>999999999999999</submerchantid>
<chargedescription>Test Sub Mer Name</chargedescription>
<merchantstreet>1 Test Street</merchantstreet>
<merchantcity>Test City</merchantcity>
<merchantzipcode>TR45 6ST</merchantzipcode>
<merchantcountryiso2a>GB</merchantcountryiso2a>
</merchant>
<billing>
<amount currencycode="GBP">1050</amount>
<payment type="VISA">
<expirydate>12/2030</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) |
The charge description is a field that we provide to the acquiring bank during a transaction. You must submit the sub-merchant name in this field. |
|
| expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY | The expiry date printed on the card. | |
| facilitatorid XPath: /merchant/facilitatorid |
Numeric (11) |
The payment facilitator id assigned by Visa/Mastercard at time of registration. Note that separate IDs are assigned by Visa and Mastercard. |
|
|
|
facilitatorname XPath: /merchant/facilitatorname |
Alphanumeric including spaces and special characters (3, 7 or 12) |
The payment facilitator name or abbreviated name agreed with Visa/Mastercard. (This will appear before the sponsored sub-merchant name followed by an * character on cardholder's bank statements. E.g. "FAC*Test Sub Mer Name") |
|
|
merchantcity XPath: /merchant/merchantcity |
Alphanumeric (13) |
Sponsored sub-merchant city or town. |
|
|
merchantcountryiso2a XPath: /merchant/merchantcountryiso2a |
Alpha (2) |
Sponsored sub-merchant ISO2A country code. |
|
|
merchantstreet XPath: /merchant/merchantstreet |
Alphanumeric (33) |
Sponsored sub-merchant street address. |
|
|
merchantzipcode XPath: /merchant/merchantzipcode |
Alphanumeric (10) |
Sponsored sub-merchant zip or postal code. This must be a valid postcode/ZIP code for the merchantcountryiso2a submitted. |
| pan XPath: /billing/payment/pan |
Numeric (12-19) | This is the long number printed on the front of the customer’s card. | |
|
|
submerchantid XPath: /merchant/submerchantid |
Alphanumeric including spaces and special characters (15) |
Sponsored sub-merchant identifier assigned by the Payment Facilitator. Must be unique for each sponsored sub-merchant. |
|
|
independentsalesorgid XPath: /merchant/independentsalesorgid |
Numeric (11) |
The ISO (Independent Sales Organisation) id assigned by Mastercard at time of registration. |
| securitycode XPath: /billing/payment/securitycode |
Numeric (3-4) |
This is the 3-digit security code printed on the back of the card.
(For AMEX cards, this is a 4-digit code found on the front of the card) This field is not strictly required by Trust Payments, but it is highly recommended for the processing of security code checks. Additionally, some banks may decline the payment if the security code is not present. |
Related articles
JavaScript Library
The JavaScript Library is a collection of pre-built code that simplifies the process of accepting card payments from your customers.
AUTH Specification
This article provides code examples and field specification for standard authorisation requests processed via our Webservices API.
