The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.
Read this article to learn more.
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:
- lowering the amount for an AUTH after authorisation and before settlement.
- suspending a REFUND, preventing settlement.
- changing the frequency payments are processed by a SUBSCRIPTION.
Requirements
You can only perform updates on requests of the following types:
- Authorisation (AUTH)
- Refund (REFUND)
- Subscription (SUBSCRIPTION)
You can only update AUTH and REFUND requests when they are in a pending settle 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 sitereference “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 Trust Payments, including:
- sitereference “test_site12345” (to identify the site on which the transaction was processed).
- transactionreference “1-2-3” (to identify the transaction that is to be updated).
- the updates to be made; in this example, settlestatus “2” (suspends payment).
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
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' => 'webservices@example.com',
'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 = \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": [{
"requesttypedescriptions": ["TRANSACTIONUPDATE"],
"filter":{
"sitereference": [{"value":"test_site12345"}],
"transactionreference": [{"value":"1-2-3"}]
},
"updates":{"settlestatus":"2"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-3"}]
},
"updates":{"settlestatus":"2"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>test_site12345</sitereference>
<transactionreference>1-2-3</transactionreference>
</filter>
<updates>
<settlement>
<settlestatus>2</settlestatus>
</settlement>
</updates>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
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.
Trust Payments 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 errorcode value returned is “0”, indicating a successful update.
The AUTH “1-2-3” on sitereference “test_site12345” has now been assigned settlestatus “2”, which will suspend the payment.
TRANSACTIONUPDATE request
The TRANSACTIONUPDATE request consists of two parts:
- The filters are used to specify the transaction to be updated.
- The updates are used to specify the updates to be performed on the transaction.
The following is an example of a TRANSACTIONUPDATE request:
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
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' => 'webservices@example.com',
'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 = \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": [{
"requesttypedescriptions": ["TRANSACTIONUPDATE"],
"filter":{
"sitereference": [{"value":"test_site12345"}],
"transactionreference": [{"value":"1-2-3"}]
},
"updates":{"settlestatus":"2"}
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["TRANSACTIONUPDATE"],
"filter":{
"sitereference":[{"value":"test_site12345"}],
"transactionreference":[{"value":"1-2-3"}]
},
"updates":{"settlestatus":"2"}
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="TRANSACTIONUPDATE">
<filter>
<sitereference>test_site12345</sitereference>
<transactionreference>1-2-3</transactionreference>
</filter>
<updates>
<settlement>
<settlestatus>2</settlestatus>
</settlement>
</updates>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Filters
| Field | Format | Description | |
| sitereference XPath: /filter/sitereference |
Alphanumeric including underscore (50) | The unique reference for the Trust Payments site associated with the transaction you would like to update. | |
| transactionreference XPath: /filter/transactionreference |
Alphanumeric including hyphens (25) | The unique Trust Payments 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 | Format | Description | |
| orderreference XPath: /updates/merchant/orderreference |
Alphanumeric including symbols (25) Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction. |
Update the unique order reference that can be stored on the Trust Payments system. | |
| settlebaseamount XPath: /updates/settlement/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 XPath: /updates/settlement/settleduedate |
Date YYYY-MM-DD | 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 XPath: /updates/settlement/settlestatus |
Numeric (3) | This value relates to the status of the transaction. |
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.
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 '2019-12-17 10:58:20',
u 'errormessage': u 'Ok',
u 'operatorname': u 'webservices@example.com'
}]
}
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) "2019-12-17 10:58:20"
["errormessage"] => string(2) "Ok"
["operatorname"] => string(23) "webservices@example.com"
}
}
}
{
"requestreference":"W23-tkrxwkc6",
"version":"1.00",
"response":[{
"errorcode":"0",
"requesttypedescription":"TRANSACTIONUPDATE",
"transactionstartedtimestamp":"2019-12-17 10:58:20",
"errormessage":"Ok",
"operatorname":"webservices@example.com"
}],
"secrand":"SptlJutnBnQ"
}
<responseblock version="3.67">
<requestreference>Xj73e17g4</requestreference>
<response type="TRANSACTIONUPDATE">
<timestamp>2019-12-17 10:58:20</timestamp>
<error>
<message>Ok</message>
<code>0</code>
</error>
</response>
<secrand>qfZtw074MBlmIq</secrand>
</responseblock>
Ensure the errorcode is “0”. This indicates the TRANSACTIONUPDATE request was processed successfully. If the errorcode is not “0”, the request may not have been processed as expected.
Troubleshooting
If you submit a TRANSACTIONUPDATE request immediately after the transaction you are trying to update, you may be returned a “20004 Missing parent” error. If this happens, please wait a few seconds and retry.
