Contents

Scheme update (API)

 

A scheme update is a request that your system can manually submit to Secure Trading 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

External
This document is designed to be read in conjunction with the recurring payments document.

Click here to open this document in a new tab.

 

 

 

 

 


 

Process overview

1
Prior to processing a new recurring payment, your system will need to manually submit a SCHEMEUPDATE request to Secure Trading using our Webservices API, and check the response returned.

 


Note: 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.

2
We will contact VAU or ABU – as applicable – and check the customer’s payment credentials are up-to-date.
3
VAU or ABU 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).

Tick
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.

 

Info
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 VAU and ABU before processing another request.

 

SCHEMEUPDATE request example


#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
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' => '[email protected]',
  '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 [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
"request": [{
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["SCHEMEUPDATE"],
  "parenttransactionreference": "23-9-80000"
}]}'

 

SCHEMEUPDATE response example


{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2018-11-28 11:18:01',
        u 'parenttransactionreference': u '72-9-80001',
        u 'credentialsonfile': u '1',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        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"
  ["response"] => array(1) {
    [0] => array(22) {
      ["transactionstartedtimestamp"] => string(19) "2018-11-28 11:18:01"
      ["parenttransactionreference"] => string(10) "72-9-80001"
      ["credentialsonfile"] => string(1) "1"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(16) "SecureTrading Test Issuer1"
      ["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","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"}

 

Field specification

Key

Field name Type Length Request Response Description
parenttransactionreference Alphanumeric including 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 VAU or ABU to check if there have been any updates.

requesttypedescriptions
Alpha 20  * You must submit “SCHEMEUPDATE”, as shown in the request example.

*In the response, the field ‘requesttypedescription’ is returned instead e.g. “requesttypedescription”:”SCHEMEUPDATE”

sitereference Alphanumeric including
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.

 

Info
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. Secure Trading contacts VAU or ABU

 

 

 

 

Calendar
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.

 

 


 

3. Handling the response

 

 

 

 

Info
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):

  • acquireradvicecode
  • acquirerresponsecode
  • acquirerresponsemessage
  • schemeresponsecode

 

 

 

Info
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:

 

Email report

You will receive an email from [email protected] for each day that Secure Trading 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).

Warning
The email will be sent from [email protected] 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

You will receive an email from [email protected] for each day that Secure Trading 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).

Warning
The email will be sent from [email protected] Please add a rule or filter to your email client to prevent the emails from being classified as junk mail / spam.

 

URL notification

You will receive a URL notification for each scheme update request submitted. These 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 Secure Trading. Click here to learn more about URL notifications.

 


 

Further reading

URL
To learn more, we recommend reading documentation provided by Visa and Mastercard: