Testing SCHEMEUPDATE

The following article provides an overview on how to test your payment solution that utilises SCHEMEUPDATE.

Summary

SCHEMEUPDATE requests are submitted to the Trust Payments Gateway (TRU Connect) to check with the relevant card issuer that the customer's card used in a recurring payment sequence is still valid and up-to-date. If updates are needed, Trust Payments will automatically update their records so that future payments in the sequence use the updated card details. This process can be tested in our test environment prior to deployment in the production environment, by following the instructions provided below.

Requirements:

You will need access to your test site (prefixed with "test_").
Your test site will need SCHEMEUPDATE enabled on your ECOM/MOTO account. Please contact our Support Team to request this.

Testing with Recurring payments using our Webservices API

With this method, your system would submit an AUTH request to us at regular intervals as agreed with the customer. Click here to learn more.

Process the parent AUTH with test PAN 4000000000000671.
This simulates the customer starting a subscription with card 4000000000000671.

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "currencyiso3a":"GBP",
    "sitereference":"test_site12345",
    "credentialsonfile":"1",
    "subscriptiontype":"RECURRING",
    "subscriptionnumber":"1",
    "requesttypedescriptions":["THREEDQUERY","AUTH"]
  },
  "iat":1559033849,
  "iss":"jwt.user"
}

Ensure AUTH response returned contains errorcode 0, indicating request was processed successfully.
Click here for full documentation.

Process the SCHEMEUPDATE request. The card schemes state that this request is submitted 3 days before the date the next recurring payment is due.
This is to check the customer's card details haven't changed (i.e. PAN is still 4000000000000671).

#!/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' => '12-3-4567'
);

$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": "12-3-4567"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "sitereference":"test_site12345",
    "requesttypedescriptions":["SCHEMEUPDATE"],
    "parenttransactionreference":"12-3-4567"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="SCHEMEUPDATE">
    <operation>
      <parenttransactionreference>12-3-4567</parenttransactionreference>
      <sitereference>test_site12345</sitereference>
    </operation>
  </request>
</requestblock>

The SCHEMEUPDATE will be updated to settlestatus 100 within 3 days, and will have new pan 4000000000000051 on record.
This simulates the customer getting a new card 4000000000000051.
Click here for full documentation.

New card details returned may also include an updated expirydate.

Process the child AUTH. This will automatically inherit card details updated by the SCHEMEUPDATE.
This simulates the customer being debited for the second payment, but this time with new card 4000000000000051.

#!/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",
  "parenttransactionreference": "12-3-4567",
  "baseamount": "1050",
  "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',
  'parenttransactionreference' => '12-3-4567',
  'baseamount' => '1050',
  '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": [{
"sitereference": "test_site12345",
"requesttypedescriptions": ["AUTH"],
"accounttypedescription": "RECUR",
"parenttransactionreference": "12-3-4567",
"baseamount": "1050",
"subscriptiontype": "RECURRING",
"subscriptionnumber": "2",
"credentialsonfile": "2"
}]}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "sitereference":"test_site12345",
    "requesttypedescriptions":["AUTH"],
    "accounttypedescription":"RECUR",
    "parenttransactionreference":"12-3-4567",
    "baseamount":"1050",
    "subscriptiontype":"RECURRING",
    "subscriptionnumber":"2",
    "credentialsonfile":"2"
  }]
}

<requestblock version="3.67">
  <alias>webservices@example.com</alias>
  <request type="AUTH">
    <operation>
      <sitereference>test_site12345</sitereference>
      <accounttypedescription>RECUR</accounttypedescription>
      <parenttransactionreference>12-3-4567</parenttransactionreference>
      <credentialsonfile>2</credentialsonfile>
    </operation>
    <billing>
      <amount>1050</amount>
      <subscription type="RECURRING">
        <number>2</number>
      </subscription>
    </billing>
  </request>
</requestblock>

Ensure AUTH response returned contains errorcode 0, indicating request was processed successfully.
Click here for full documentation.

From here onwards, all subsequent child AUTH requests submitted to Trust Payments that use the original parent will use the updated PAN 4000000000000051.
This simulates the customer being debited for subsequent payments with new card 4000000000000051.

Other test cases

By substituting the given PAN in the payment flow described above when processing requests in our testing environment, you can elicit different responses from our test system. These are outlined below:

PAN submitted in parent AUTH request	Outcome when in test environment
4000000000000671	Once the SCHEMEUPDATE is updated to settlestatus 100, the PAN will update to 4000000000000051 (allow for up to 3 days for this to complete), which will be used in subsequent subscription payments in the sequence. This simulates the customer getting a new card, which is used in future payments.
4000000000000051	Once the SCHEMEUPDATE is updated to settlestatus 100, the PAN will update to 4111110000000914 (allow for up to 3 days for this to complete), which will be used in subsequent subscription payments in the sequence. This simulates the customer getting a new card, which is used in future payments.
4111110000000914	The SCHEMEUPDATE will update to show errorcode 70000 and settlestatus 3 (allow for up to 3 days for this to complete). If a SCHEMEUPDATE is declined in this manner, we recommend that you check the acquirerresponsecode and acquirerresponsemessage to determine the reason for the unsuccessful request. If the card scheme has requested that future payments must be stopped, your system must not process further payments in this subscription sequence. This simulates a situation where the card scheme has had a request from the customer to stop further recurring payments. Following this, we would recommend contacting the customer for clarification on the situation.

Testing with Subscriptions using our Payment Pages

Using our Payment Pages solution, you can schedule payments to be processed automatically by the Trust Payments subscription engine at the interval specified in the request. Click here to learn more about subscriptions.

The request (POST) to Payment Pages needs to include subscription-specific fields that define the interval of the subscription. Using your test site, complete a transaction using Payment Pages using test PAN 4000000000000051.
This simulates the customer starting a subscription with card 4000000000000051.

For testing purposes, we recommend specifying an interval of 1 MONTH, as shown in the example below:

<html>
<head> 
</head> 
<body> 
<form method="POST" action="<DOMAIN>/process/payments/choice"> 
<input type="hidden" name="sitereference" value="test_site12345"> 
<input type="hidden" name="currencyiso3a" value="GBP"> 
<input type="hidden" name="mainamount" value="10.00">
<input type="hidden" name="stprofile" value="default"> 
<input type="hidden" name="version" value="2"> 
<input type="hidden" name="subscriptionunit" value="MONTH">
<input type="hidden" name="subscriptionfrequency" value="1">
<input type="hidden" name="subscriptionnumber" value="1">
<input type="hidden" name="subscriptionfinalnumber" value="12">
<input type="hidden" name="subscriptiontype" value="RECURRING">
<input type="hidden" name="credentialsonfile" value="1">
<input type="submit" value="Pay"> 
</form> 
</body> 
</html>

Click here for full documentation.

Behind the scenes, a SCHEMEUPDATE request is automatically triggered 3 days prior to processing of an automated subscription payment. Following this, a new PAN 4111110000000914 should be retrieved and stored in the SCHEMEUPDATE record and the masked version of this is visible in Portal (allow for up to 3 days for this to complete). When the next subscription payment in the sequence is processed, it will use the new 4111110000000914 PAN.
This is to check the customer's card details haven't changed (i.e. PAN was still 4000000000000051), and our records were subsequently updated to use 4111110000000914 for subscription payments going forward, because the customer was issued a new card.
3 days prior to the third subscription payment being processed, another SCHEMEUPDATE is automatically triggered. The SCHEMEUPDATE will update to show errorcode 70000 and settlestatus 3 (allow for up to 3 days for this to complete). If a SCHEMEUPDATE is declined in this manner, we recommend that you check the acquirerresponsecode and acquirerresponsemessage to determine the reason for the unsuccessful request. If the card scheme has requested that future payments must be stopped, the subscription engine will not process further payments in this subscription sequence.
This simulates a situation where the card scheme has had a request from the customer to stop further recurring payments. Following this, we would recommend contacting the customer for clarification on the situation.

Testing with Subscriptions using our JavaScript Library

Using our JavaScript Library solution, you can schedule payments to be processed automatically by Trust Payments subscription engine at the interval specified in the request. Click here to learn more about subscriptions.

Process a combined THREEDQUERY, AUTH and SUBSCRIPTION request with test PAN 4000000000000051.
This simulates the customer starting a subscription with card 4000000000000051.

{
  "payload":{
    "accounttypedescription":"ECOM",
    "baseamount":"1050",
    "currencycode":"GBP",
    "sitereference":"test_site12345",
    "subscriptiontype":"RECURRING",
    "subscriptionunit":"MONTH",
    "subscriptionfrequency":"1",
    "subscriptionnumber":"1",
    "subscriptionfinalnumber":"12",
    "subscriptionbegindate":"2022-01-01",
    "credentialsonfile":"1",
    "requesttypedescriptions":["THREEDQUERY","AUTH","SUBSCRIPTION"]
  },
  "iat":"1567701632",
  "iss":"jwt.user"
}

Ensure AUTH response returned contains errorcode 0, indicating request was processed successfully.
Click here for full documentation.

Behind the scenes, a SCHEMEUPDATE request is automatically triggered 3 days prior to processing of an automated subscription payment. Following this, a new PAN 4111110000000914 should be retrieved and stored in the SCHEMEUPDATE record and the masked version of this is visible in Portal (allow for up to 3 days for this to complete). When the next subscription payment in the sequence is processed, it will use the new 4111110000000914 PAN.
This is to check the customer's card details haven't changed (i.e. PAN was still 4000000000000051), and our records were subsequently updated to use 4111110000000914 for subscription payments going forward, because the customer was issued a new card.
3 days prior to the third subscription payment being processed, another SCHEMEUPDATE is automatically triggered. The SCHEMEUPDATE will update to show errorcode 70000 and settlestatus 3 (allow for up to 3 days for this to complete). If a SCHEMEUPDATE is declined in this manner, we recommend that you check the acquirerresponsecode and acquirerresponsemessage to determine the reason for the unsuccessful request. If the card scheme has requested that future payments must be stopped, the subscription engine will not process further payments in this subscription sequence.
This simulates a situation where the card scheme has had a request from the customer to stop further recurring payments. Following this, we would recommend contacting the customer for clarification on the situation.

Further reading on this topic