Contents

Transaction updates

After processing requests and transactions with us, you can update some of the details at a later time by submitting a TRANSACTIONUPDATE request.

 

Process overview

Here are some examples of the updates that can be performed using this feature:

 

Requirements

You can only perform updates on requests of the following types:

Info
You can only update AUTH and REFUND requests when they are in a pending settlement status (‘0’, ‘1’ or ‘2’) and NOT when in cancelled (‘3’) or settled (‘100’) status. Click here for further information on possible settle status values.

 

Walkthrough

You have previously processed a successful AUTH (with transactionreference “1-2-3”) on your site (with Site Reference “test_site12345”). It has a settlestatus of “1”, meaning it will be settled automatically within 24 hours. You wish to update the settlestatus to “2”, which will suspend the Settlement of funds to your bank account.

Step 1: Your system submits a TRANSACTIONUPDATE request to Secure Trading, including:


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
   },
   "updates":{"settlestatus":"2"}
}
  
strequest = securetrading.Request()
strequest.update(update)
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(
'requesttypedescriptions' => array('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-3'))
),
'updates' => array('settlestatus' => '2')
);

$api = Securetradingapi($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": [{
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
},
"updates":{"settlestatus":"2"}
}]}'

Info

When performing a single TRANSACTIONUPDATE request:

  • You can only update one transaction. (Updating multiple transactions necessitates one TRANSACTIONUPDATE request per transaction)
  • You can update multiple fields in a single transaction by using a single TRANSACTIONUPDATE request.

Secure Trading receives and interprets the TRANSACTIONUPDATE request and performs the updates on the specified transaction, providing the request submitted was valid (otherwise returns an error).

Step 2: Your system receives and interprets a TRANSACTIONUPDATE response and updates your records, as appropriate. Your system should ensure the error code value returned is “0”, indicating a successful update.

The AUTH “1-2-3” on site “test_site12345” has now been assigned settlestatus “2”, which will suspend the payment.

 

TRANSACTIONUPDATE request

The TRANSACTIONUPDATE request consists of two parts:

The following is an example of a TRANSACTIONUPDATE request:


#!/usr/bin/python
import securetrading
  
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
  
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
   },
   "updates":{"settlestatus":"2"}
}
  
strequest = securetrading.Request()
strequest.update(update)
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(
'requesttypedescriptions' => array('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-3'))
),
'updates' => array('settlestatus' => '2')
);

$api = Securetradingapi($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": [{
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
},
"updates":{"settlestatus":"2"}
}]}'

 

Filters

Key

Field name Type Length Request Description
sitereference Alphanumeric including underscore 50 The unique reference for the Secure Trading site associated with the transaction you would like to update.
transactionreference Alphanumeric including hyphens 25 The unique Secure Trading reference for the transaction you would like to update.

 

Updates

The following fields can be updated when performing updates on AUTH and REFUND requests.

Field name Type Length Request Description
orderreference Alphanumeric including
symbols
255 Update the unique order reference that can be stored on Secure Trading’s system.
settlebaseamount Numeric 13 The amount of the transaction in base units, with no commas or decimal points, so £10.50 would be 1050. This value must be above zero and less than or equal to the original authorisation amount.
settleduedate Date YYYY-MM-DD 10 Date the transaction will be settled. If today or earlier, the transaction will settle when Settlement is next run (providing not suspended or cancelled).
settlestatus Numeric 3 This value relates to the status of the transaction.

URL
Different update fields are required when updating different request types. Please refer to the following resources for further information:

 

About settle status

 

  • A suspended (status 2) transaction will be automatically reversed or cancelled (status 3) after 7 days from authorisation, as the authorisation code will have expired. (Authorisation codes are valid for 7 days).
  • Once a transaction is set to reversed/cancelled (status 3), the transaction will not settle and the status cannot be changed.

Click here for further information on the settle status.

 

TRANSACTIONUPDATE response

Please find below an example of a TRANSACTIONUPDATE response that was returned following a successful transaction update.


{
  u 'requestreference': u 'A3jbd6w7a',
    u 'version': u '1.00',
    u 'responses': [{
      u 'errorcode': u '0',
        u 'requesttypedescription': u 'TRANSACTIONUPDATE',
        u 'transactionstartedtimestamp': u '2016-12-07 14:30:18',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A057aegmt"
  ["version"] => string(4) "1.00"
  ["responses"] => array(1) {
    [0] => array(5) {
      ["errorcode"] => string(1) "0"
      ["requesttypedescription"] => string(17) "TRANSACTIONUPDATE"
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 10:01:55"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
    }
  }
}
{
  "requestreference": "W23-tkrxwkc6",
  "version": "1.00",
  "response": [{
    "errorcode": "0",
    "requesttypedescription": "TRANSACTIONUPDATE",
    "transactionstartedtimestamp": "2016-12-07 15:17:24",
    "errormessage": "Ok",
    "operatorname": "[email protected]"
  }],
  "secrand": "SptlJutnBnQ"
}

Ensure the Error Code is “0”. This indicates the TRANSACTIONUPDATE request was processed successfully. If the error code is not “0”, the request may not have been processed as expected. If you are experiencing difficulties, read our Troubleshooting page.

 


 

Additional resources