A scheme update is a request that your system can manually submit to Trust Payments using our Webservices API, in the days preceding a recurring payment, to check if the customer’s stored payment credentials are still up-to-date. As part of this process, we will contact the Visa Account Updater (VAU) and Mastercard’s Automatic Billing Updater (ABU) systems to check for updates, and store any updated payment credentials on our secure servers for future payments.
Requirements
This document is designed to be read in conjunction with the recurring payments document.
Click here to open this document in a new tab.
- We support both Visa Account Updater (VAU) and Mastercard’s Automatic Billing Updater (ABU) systems. Therefore the scheme update request will support any Mastercard and Visa-branded cards.
- Card scheme updates are only supported by participating card issuers. If the card issuer doesn’t contact Visa or Mastercard to provide updated payment credentials when a new card is issued, we will be unable to successfully retrieve the updated payment credentials.
- If you haven’t already done so, you will need to contact our Support Team before implementing scheme updates. They will be able to assist you in determining whether we support scheme updates for your acquiring bank, and then enable the functionality on your site reference(s).
- When enabling scheme updates, our Support Team will also configure notifications that send the results of scheme update checks back to your system (we explain these in greater detail later in this document):
- Email reports – We send an email to an address of your choosing, which contains a table of the results of scheme updates, received by Trust Payments in the last 24 hours.
- URL notifications – Your system will receive one URL notification for each scheme update, containing any updated payment credentials.
Process overview
- Prior to processing a new recurring payment, your system will need to manually submit a SCHEMEUPDATE request to Trust Payments using our Webservices API, and check the response returned.
Depending on the acquirer, this may take a number of days to process. We recommend submitting the SCHEMEUPDATE request three business days ahead of when you need to process a new payment.
- We will contact Visa or Mastercard – as applicable – and check the customer’s payment credentials are up-to-date.
- Visa or Mastercard will return information on the status of the customer’s payment credentials, and we will pass this onto your system via a URL notification. We will store the updated payment type, card number and expiry date. These details will be passed back to your system via URL notification (the card number is masked for security purposes)
Once your system has received the URL notification regarding the scheme update, your system can then submit the AUTH request, as documented in the recurring payments document.
1. Submit the scheme update
Your system will manually submit a SCHEMEUPDATE request and then parse and interpret the response returned.
Do not process multiple scheme updates regarding the same payment credentials
It may take a number of days for the checks to be completed (we recommend allowing up to three business days). Please wait until you have received the URL notification with the results of the checks from the scheme update before processing another request.
SCHEMEUPDATE request example
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
schemeupdate = {
"sitereference": "test_site12345",
"requesttypedescriptions": ["SCHEMEUPDATE"],
"parenttransactionreference": "23-9-80000"
}
strequest = securetrading.Request()
strequest.update(schemeupdate)
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('SCHEMEUPDATE'),
'parenttransactionreference' => '23-9-80000'
);
$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": [{
"sitereference": "test_site12345",
"requesttypedescriptions": ["SCHEMEUPDATE"],
"parenttransactionreference": "23-9-80000"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"sitereference":"test_site12345",
"requesttypedescriptions":["SCHEMEUPDATE"],
"parenttransactionreference":"23-9-80000"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="SCHEMEUPDATE">
<operation>
<parenttransactionreference>23-9-80000</parenttransactionreference>
<sitereference>test_site12345</sitereference>
</operation>
</request>
</requestblock>
Replace <DOMAIN>
with a supported domain. Click here for a full list.
Field specification
Field | Format | Description | |
parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
You will need to submit the transaction reference of the original AUTH transaction (the “parent” request, as described in the recurring payments document).
We will inherit the stored payment credentials from this transaction, and send these off to the relevant card scheme to check if there have been any updates. |
|
requesttypedescriptions XPath: /@type |
Alpha (20) | You must submit “SCHEMEUPDATE”, as shown in the request example. | |
sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support Team. |
SCHEMEUPDATE response example
{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'transactionstartedtimestamp': u '2018-11-28 11:18:01',
u 'parenttransactionreference': u '72-9-80001',
u 'credentialsonfile': u '1',
u 'livestatus': u '0',
u 'merchantcategorycode': u '0000',
u 'issuer': u 'Test Issuer',
u 'dccenabled': u '0',
u 'settleduedate': u '2018-11-28',
u 'errorcode': u '0',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '72-9-80002',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '100',
u 'accounttypedescription': u 'ECOM',
u 'requesttypedescription': u 'SCHEMEUPDATE',
u 'currencyiso3a': u 'GBP',
u 'maskedpan': u '411111######1111',
u 'errormessage': u 'Ok',
u 'issuercountryiso2a': u 'US',
u 'settlestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "A3579dkvx"
["version"] => string(4) "1.00"
["responses"] => array(1) {
[0] => array(23) {
["transactionstartedtimestamp"] => string(19) "2018-11-28 11:18:01"
["parenttransactionreference"] => string(10) "72-9-80001"
["credentialsonfile"] => string(1) "1"
["livestatus"] => string(1) "0"
["merchantcategorycode"] => string(4) "0000"
["issuer"] => string(16) "Test Issuer"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2018-11-28"
["errorcode"] => string(1) "0"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["merchantcountryiso2a"] => string(2) "GB"
["transactionreference"] => string(10) "72-9-80002"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["baseamount"] => string(3) "100"
["accounttypedescription"] => string(4) "ECOM"
["requesttypedescription"] => string(12) "SCHEMEUPDATE"
["currencyiso3a"] => string(3) "GBP"
["maskedpan"] => string(16) "411111######1111"
["errormessage"] => string(2) "Ok"
["issuercountryiso2a"] => string(2) "US"
["settlestatus"] => string(1) "0"
}
}
}
{
"requestreference":"W23-fjgvn3d8",
"version":"1.00",
"response":[{
"transactionstartedtimestamp":"2018-11-28 11:18:01",
"parenttransactionreference":"72-9-80001",
"credentialsonfile":"1",
"livestatus":"0",
"merchantcategorycode":"0000",
"issuer":"SecureTrading Test Issuer1",
"dccenabled":"0",
"settleduedate":"2018-11-28",
"errorcode":"0",
"tid":"27882788",
"merchantnumber":"00000000",
"merchantcountryiso2a":"GB",
"transactionreference":"72-9-80002",
"merchantname":"Test Merchant",
"paymenttypedescription":"VISA",
"baseamount":"100",
"accounttypedescription":"ECOM",
"requesttypedescription":"SCHEMEUPDATE",
"currencyiso3a":"GBP",
"maskedpan":"411111######1111",
"errormessage":"Ok",
"issuercountryiso2a":"US",
"settlestatus":"0"
}],
"secrand":"zO9"
}
<responseblock version="3.67">
<requestreference>X12345</requestreference>
<response type="SCHEMEUPDATE">
<merchant>
<merchantcategorycode>0000</merchantcategorycode>
<tid>00000000</tid>
<merchantnumber>00000000</merchantnumber>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Merchant test site</merchantname>
</merchant>
<transactionreference>72-5-118</transactionreference>
<billing>
<amount currencycode="GBP">1234</amount>
<payment type="VISA">
<pan>411111######0211</pan>
<issuercountry>ZZ</issuercountry>
<issuer>Test Issuer</issuer>
</payment>
<dcc enabled="0"/>
</billing>
<timestamp>2019-09-19 12:26:06</timestamp>
<error>
<message>Ok</message>
<code>0</code>
</error>
<live>0</live>
<operation>
<parenttransactionreference>72-5-117</parenttransactionreference>
<accounttypedescription>ECOM</accounttypedescription>
<credentialsonfile>1</credentialsonfile>
</operation>
<settlement>
<settleduedate>2019-09-19</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
</response>
<secrand>Yb3SR5Pq</secrand>
</responseblock>
If the response contains errorcode = “0” and settlestatus = “0”, this indicates your request was successful.
If this is not the case, you will need to look at the errorcode and errormessage values in order to troubleshoot the problem.
2. Trust Payments contacts the card schemes
- Trust Payments will gather all payment credentials where scheme updates have been requested, and submit a batch of these details to the card schemes on a daily-basis.
- Once the payment credentials have been submitted to the card schemes, the settlestatus of each SCHEMEUPDATE is updated to “10”.
- After the card schemes have gathered the information needed regarding any changes to payment credentials, they will submit the results of their checks back to Trust Payments.
We recommend allowing up to three business days for this process to complete
For this reason, we also recommend performing SCHEMEUPDATE requests three days before recurring payments need to be performed.
- Once we have received a response from the card schemes, the settlestatus of each SCHEMEUPDATE is updated to their final state:
- “100” if the checks completed successfully.
- “3” if the checks raised an issue.
3. Handling the response
- Once completed, you will receive a URL notification for each SCHEMEUPDATE request submitted. We will also email you daily reports that summarise the results of scheme updates performed. See below for greater detail.
- If the settlestatus of the SCHEMEUPDATE has been updated to “100”, this means the checks were performed successfully, and if the payment credentials were updated, our own records are updated to always use the latest information for all future scheduled payments.
- If the settlestatus has instead been updated to “3”, this indicates that the scheme update checks have raised an issue that needs to be addressed before processing further recurring payments with the customer. Your system should perform the following additional checks:
- If the settlestatus is “3” and the errorcode is showing as “70000”, this indicates that the card scheme has had a request from the customer to stop further recurring payments. You must desist from processing further recurring payments in the sequence. We recommend contacting the customer for clarification on the situation.
- If the settlestatus is “3” and the errorcode is not “70000”, this indicates a problem has occurred when performing the checks, requiring manual investigation. You will need to refer to our list of error codes to determine the cause of the error and handle the response appropriately.
To find further information on the results of scheme update checks, you can look at the following fields (the availability of this information is dependent on your acquiring bank):
Field | Format | Description |
acquireradvicecode | Numeric (1) |
A numeric value returned following a repeat payment request, indicating if further payments can be processed.
Mapping:
|
acquirerresponsecode | Alphanumeric (255) |
Used by your acquirer to indicate the outcome of the request.
|
acquirerresponsemessage | Alphanumeric (255) |
- Any future recurring payments that are processed from the original parent transaction included in the SCHEMEUPDATE request will automatically use the latest payment credentials.
- Once the scheme updates have been performed, we recommend performing the recurring payment within 6 days, to reduce the chance of the payment credentials being updated before the latest payments are processed.
In the interest of maintaining an accurate record of your transaction history, we will never modify the payment credentials of previously-processed transactions with updated details, as part of the scheme update process.
Or in other words, if you are looking at a previously-processed recurring payment in MyST, you will always see the payment credentials used to facilitate that specific transaction, rather than the most up-to-date payment credentials retrieved by scheme updates.
About notifications
The results of scheme update checks are returned to your system via notifications:
URL notification
You will need to contact our Support Team to enable URL notificiations that are automatically sent following each scheme update request submitted. You will need to provide your site reference and the URL endpoint to which the notification will be sent.
Once configured, the URL notification received will contain the updated payment credentials (payment type, expiry date and masked card number). If the payment credentials haven’t been updated, the existing payment credentials are returned. You will need to parse these notifications and send a response back to Trust Payments. Click here to learn more about URL notifications.
Email report
To enable email reports, you will need to contact our Support Team to enable URL notficiations that are automatically sent following each scheme update request submitted. You will need to provide your site reference and the URL endpoint to which the notification will be sent.
Once enabled, you will receive an email from no-reply@trustpayments.com for each day that Trust Payments receives results for scheme update checks from Visa Account Updater (VAU) and Mastercard’s Automatic Billing Updater (ABU) systems, including updated payment credentials (payment type, expiry date and masked card number). They are presented in the format of a table. You will receive a maximum of one email per day (if there are no updates, you will not receive an email).
The email will be sent from no-reply@trustpayments.com. Please add a rule or filter to your email client to prevent the emails from being classified as junk mail / spam.
“Stopped” subscription email report
To enable email reports, you will need to contact our Support Team to enable URL notficiations that are automatically sent following each scheme update request submitted. You will need to provide your site reference and the URL endpoint to which the notification will be sent.
Once enabled, you will receive an email from no-reply@trustpayments.com for each day that Trust Payments receives any requests to stop active subscriptions, from Visa Account Updater (VAU) and Mastercard’s Automatic Billing Updater (ABU) systems. They are presented in the format of a table. You will receive a maximum of one email per day (if there are no updates, you will not receive an email).
The email will be sent from no-reply@trustpayments.com. Please add a rule or filter to your email client to prevent the emails from being classified as junk mail / spam.