This functionality allows you to continue a recurring payment sequence that was originally started using a different Payment Service Provider than Trust Payments. The scheme reference data submitted provides a link to the payment history between your business and the customer.
About Visa scheme reference data
The scheme reference data required by Visa in Recurring and other types of Merchant Initiated Transaction (MIT) authorisation requests is called the Visa Transaction Identifier (Transaction ID).
The Visa Transaction ID is a unique identifier for each original authorisation request, which is a numeric value of up to 15 digits in length included in the Visa authorisation response returned, following the initial Customer Initiated Transaction authorisation submitted when the cardholder first signed up to the recurring or MIT agreement.
Example of a Visa Transaction ID: 987654321234567
Trust Payments require the Visa Transaction ID to be provided in the above format.
About Mastercard scheme reference data
The scheme reference data required by Mastercard in Recurring and other types of Merchant Initiated Transaction (MIT) authorisation requests is called the Mastercard Trace ID.
The Mastercard Trace ID is a combination of the Mastercard Financial Network Code, Banknet Reference Number and Banknet Settlement Date included in the Mastercard authorisation response returned, following the initial Customer Initiated Transaction authorisation submitted when the cardholder first signed up to the recurring or MIT agreement.
Example of a Mastercard Trace ID: "MCCABC1XY0101 "
Positions 1-3 = “MCC” = Financial Network Code
Positions 4-9 = “ABC1XY” = Banknet Reference Number
Positions 10-13 = “0101” = Banknet Settlement Date
Positions 14-15 = space filled
Trust Payments require the Mastercard Trace ID to be provided in the following format: "MCCABC1XY 0101"
Positions 1-3 = “MCC” = Financial Network Code
Positions 4-9 = “ABC1XY” = Banknet Reference Number
Positions 10-12 = “ ” = space filled
Positions 13-16 = Banknet Settlement Date
Requirements
- Before you proceed, you will need to contact our Support Team and request scheme reference data functionality is enabled on your site reference(s).
- This is functionality is only supported if you are processing payments with TRU Acquiring.
Submit request with scheme reference data
Request 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": "RECUR",
"currencyiso3a": "GBP",
"baseamount": "1050",
"orderreference": "My_Order_123",
"pan": "4111111111111111",
"expirydate": "12/2020",
"schemereferencedata": "123456789012345",
"subscriptiontype": "RECURRING",
"subscriptionnumber": "2",
"credentialsonfile": "2"
}
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' => 'RECUR',
'currencyiso3a' => 'GBP',
'baseamount' => '1050',
'orderreference' => 'My_Order_123',
'pan' => '4111111111111111',
'expirydate' => '12/2020',
'schemereferencedata' => '123456789012345',
'subscriptiontype' => 'RECURRING',
'subscriptionnumber' => '2',
'credentialsonfile' => '2'
);
$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",
"accounttypedescription": "RECUR",
"pan": "4111111111111111",
"expirydate": "12/2020",
"schemereferencedata": "123456789012345",
"subscriptiontype": "RECURRING",
"subscriptionnumber": "2",
"credentialsonfile": "2"
}]
}'
{
"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",
"accounttypedescription":"RECUR",
"pan":"4111111111111111",
"expirydate":"12/2020",
"schemereferencedata": "123456789012345",
"subscriptiontype":"RECURRING",
"subscriptionnumber":"2",
"credentialsonfile":"2"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="AUTH">
<merchant>
<orderreference>My_Order_123</orderreference>
</merchant>
<billing>
<payment>
<expirydate>12/2020</expirydate>
<pan>4111111111111111</pan>
</payment>
<amount currencycode="GBP">1050</amount>
<subscription type="RECURRING">
<number>2</number>
</subscription>
</billing>
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>RECUR</accounttypedescription>
<schemereferencedata>123456789012345</schemereferencedata>
<credentialsonfile>2</credentialsonfile>
</operation>
</request>
</requestblock>
Request field specification
An extra field is required in this use case:
| Field | Format | Description | |
| credentialsonfile XPath: /operation/credentialsonfile |
Numeric (1) |
This is required for Visa and Mastercard transactions where the merchant is utilising Credentials on File (CoF). Submit “2” in this field to indicate the payment is using previously-stored credentials. |
|
| schemereferencedata XPath: /operation/schemereferencedata |
If Mastercard scheme:
If Visa scheme:
|
Scheme reference data provided by your previous Payment Service Provider (PSP) following the initial payment in the sequence. This must be submitted unmodified. | |
| subscriptionnumber XPath: /billing/subscription/number |
Numeric (5) |
This is used to identify a payment’s position within a sequence of recurring transactions. For each subsequent payment, the number submitted should be incremented by 1 (without gaps). e.g. 2nd transaction is “2”, 3rd is “3”, then “4” etc. (You should only increment this number if the previous recurring payment request was successful) We do not impose limits on the number of payments made against a card. |
|
| subscriptiontype XPath: /billing/subscription/@type |
Alpha (11) |
This is the type of subscription: “RECURRING” is for when the customer is making a recurring payment for a new product/service each time. “INSTALLMENT” is for when a customer is purchasing a single order over several installments. Installments are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. |
Handling the response
The scheme reference data will be returned in the response:
| Field | Format | Description | |
|
schemereferencedata XPath: /operation/schemereferencedata |
If Mastercard scheme:
If Visa scheme:
|
Scheme reference data associated with this transaction, as returned by the card issuer. Note: In subsequent recurring payments, you must continue to submit the original scheme reference data that was submitted in the request. |
