In the event that a customer returns faulty goods or a paid-for service cannot be provided, you may be required to refund or partially refund a processed transaction. This page explains how to process a refund with Webservices API.
Process overview
To process a refund, your system submits a REFUND request to Trust Payments. Once the request has been received, the refund will be processed either online or offline, as summarised below:
Visa: All refunds are processed online.
Mastercard: All refunds will be processed online from 4th November 2025.
Online refunds
- Merchant submits a REFUND request.
- Trust Payments validates the request and obtains authorisation from the card issuer to process the refund. The card issuer's response is then returned to the merchant.
- Once authorised, Trust Payments processes the refund with your acquirer.
- Your acquirer processes the refund and the cardholder receives the refunded amount.
Offline refunds
- Merchant submits a REFUND request.
- Trust Payments validates the request and returns a "REFUND ACCEPTED" response.
- Trust Payments processes the refund with your acquirer.
- Your acquirer processes the refund and the cardholder receives the refunded amount.
Requirements
- You can only refund payments with settle status “100”, which indicates the funds have been successfully transferred to your bank account. Learn more about settlement.
- You cannot refund a greater amount than was originally settled.
- A refund request will only be successful if the payment details are still valid (e.g. the request will not be successful if the card has passed its expiry date).
REFUND request
Full refund
The following example REFUND request performs a full refund on the specified AUTH:
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
refund= {
"requesttypedescriptions": ["REFUND"],
"sitereference": "test_site12345",
"parenttransactionreference": "1-2-345678"
}
strequest = securetrading.Request()
strequest.update(refund)
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('REFUND'),
'sitereference' => 'test_site12345',
'parenttransactionreference' => '1-2-345678'
);
$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": ["REFUND"],
"sitereference": "test_site12345",
"parenttransactionreference": "1-2-345678"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["REFUND"],
"sitereference":"test_site12345",
"parenttransactionreference":"1-2-345678"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="REFUND">
<operation>
<sitereference>test_site12345</sitereference>
<parenttransactionreference>1-2-345678</parenttransactionreference>
</operation>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. View full domain list.
Full refund with updated expiry date
The following example REFUND request performs a full refund on the specified AUTH, using a new card expiry date. The new expiry date is submitted in the expirydate field.
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
refund= {
"requesttypedescriptions": ["REFUND"],
"sitereference": "test_site12345",
"parenttransactionreference": "1-2-345678",
"expirydate": "05/2025"
}
strequest = securetrading.Request()
strequest.update(refund)
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('REFUND'),
'sitereference' => 'test_site12345',
'parenttransactionreference' => '1-2-345678',
'expirydate' => '05/2025'
);
$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": ["REFUND"],
"sitereference": "test_site12345",
"parenttransactionreference": "1-2-345678",
"expirydate": "05/2025"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["REFUND"],
"sitereference":"test_site12345",
"parenttransactionreference":"1-2-345678",
"expirydate":"05/2025"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="REFUND">
<billing>
<payment>
<expirydate>05/2025</expirydate>
</payment>
</billing>
<operation>
<sitereference>test_site12345</sitereference>
<parenttransactionreference>1-2-345678</parenttransactionreference>
</operation>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. View full domain list.
Partial refund
The following example REFUND request performs a partial refund on the specified AUTH. You can specify the amount to be refunded in the baseamount field.
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
refund= {
"requesttypedescriptions": ["REFUND"],
"sitereference": "test_site12345",
"parenttransactionreference": "1-2-345678",
"baseamount": "2001"
}
strequest = securetrading.Request()
strequest.update(refund)
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('REFUND'),
'sitereference' => 'test_site12345',
'parenttransactionreference' => '1-2-345678',
'baseamount' => '2001'
);
$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": ["REFUND"],
"sitereference": "test_site12345",
"parenttransactionreference": "1-2-345678",
"baseamount": "200"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["REFUND"],
"sitereference":"test_site12345",
"parenttransactionreference":"1-2-345678",
"baseamount":"200"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</alias>
<request type="REFUND">
<billing>
<amount>200</amount>
</billing>
<operation>
<sitereference>test_site12345</sitereference>
<parenttransactionreference>1-2-345678</parenttransactionreference>
</operation>
</request>
</requestblock>
Replace <DOMAIN> with a supported domain. View full domain list.
Field specification
When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.
| Field | Format | Description | |
| Required | parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
This field must contain the transaction reference of the AUTH request that you would like to refund. |
| Required | requesttypedescriptions XPath: /@type |
Alpha (20) | The request type required is “REFUND”. |
| Required | sitereference XPath: /operation/sitereference |
Alphanumeric & underscore (50) |
A unique reference that identifies your account. You receive this when you first sign up with us. The site reference submitted in the REFUND request must be the same as the site reference used to process the parent AUTH request. |
| Optional | baseamount XPath: /billing/amount |
Numeric (13) |
The refund amount in base units, with no commas or decimal points. e.g. £10.99 would be submitted as “1099” but ¥246 would be submitted as “246”. This amount cannot be greater than the final amount settled into your bank account. You can opt to perform a partial refund by submitting a lower amount here. If this field is not present, the full amount of the transaction will be refunded. (Max length of amount may vary depending on your acquiring bank – Contact your bank for further info) |
| Optional | chargedescription XPath: /merchant/chargedescription |
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. |
This is a description of the payment that appears on the customer’s bank statement. This is supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. Specification of this field will depend on your acquiring bank. For further information, please contact our Support Team. Valid characters:
|
| Optional | expirydate XPath: /billing/payment/expirydate |
Date MM/YYYY | If you would like to process a refund with an updated expiry date, the new value is submitted in this field. |
| Optional | orderreference XPath: /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. |
Your unique order reference that can be stored on the Trust Payments system. If this is not submitted, it is inherited from the parent AUTH request. |
REFUND response
After processing a refund, Trust Payments will return the following response:
The specification of the REFUND response is the same as the standard AUTH response, except the requesttypedescription field has value “REFUND”.
Online refund response
Visa: All refunds are processed online.
Mastercard: All refunds will be processed online from 4th November 2025.
If a refund has been declined, errorcode=70000 is returned in the response. When this occurs, we recommend contacting the customer directly to arrange the refund using an alternative method of payment (e.g. bank transfer).
{
'requestreference': 'A0bxh87wt',
'version': '1.00',
'responses': [{
'accounttypedescription': 'MOTO',
'acquirerresponsecode': '00',
'acquirerresponsemessage': 'Approved or completed Successfully',
'authcode': 'ABC123',
'baseamount': '1050',
'chargedescription': 'Test Merchant',
'cryptocurrencyindicator': '0',
'currencyiso3a': 'GBP',
'dccenabled': '0',
'debtrepayment': '0',
'errorcode': '0',
'errormessage': 'Ok',
'issuer': 'Test Issuer',
'issuercountryiso2a': 'ZZ',
'livestatus': '1',
'maskedpan': '411111######1111',
'merchantcategorycode': '5999',
'merchantcity': 'Test City',
'merchantcountryiso2a': 'GB',
'merchantname': 'Test Merchant',
'merchantnumber': '00000000',
'merchantzipcode': 'T45 6ST',
'operatorname': 'webservices@example.com',
'orderreference': 'MyOrder123',
'parenttransactionreference': '1-2-345678',
'paymenttypedescription': 'VISA',
'requesttypedescription': 'REFUND',
'retrievalreferencenumber': '333912345678',
'securityresponseaddress': '0',
'securityresponsepostcode': '0',
'securityresponsesecuritycode': '0',
'settleduedate': '2023-12-05',
'settlestatus': '100',
'stan': '123456',
'transactionreference': '1-2-345679',
'transactionstartedtimestamp': '2023-12-05 15:38:16'
}]
}
array(3) {
["requestreference"] => string(9) "A3579dkvx"
["version"] => string(4) "1.00"
["responses"] => array(1) {
[0] => array(36) {
["accounttypedescription"] => string(4) "MOTO"
["acquirerresponsecode"] => string(2) "00"
["acquirerresponsemessage"] => string(34) "Approved or completed Successfully"
["authcode"] => string(6) "ABC123"
["baseamount"] => string(4) "1050"
["chargedescription"] => string(13) "Test Merchant"
["cryptocurrencyindicator"] => string(1) "0"
["currencyiso3a"] => string(3) "GBP"
["dccenabled"] => string(1) "0"
["debtrepayment"] => string(1) "0"
["errorcode"] => string(1) "0"
["errormessage"] => string(2) "Ok"
["issuer"] => string(11) "Test Issuer"
["issuercountryiso2a"] => string(2) "ZZ"
["livestatus"] => string(1) "1"
["maskedpan"] => string(16) "411111######1111"
["merchantcategorycode"] => string(4) "5999"
["merchantcity"] => string(9) "Test City"
["merchantcountryiso2a"] => string(2) "GB"
["merchantname"] => string(13) "Test Merchant"
["merchantnumber"] => string(8) "00000000"
["merchantzipcode"] => string(8) "TR45 6ST"
["operatorname"] => string(23) "webservices@example.com"
["orderreference"] => string(10) "MyOrder123"
["parenttransactionreference"] => string(10) "1-2-345678"
["paymenttypedescription"] => string(4) "VISA"
["requesttypedescription"] => string(6) "REFUND"
["retrievalreferencenumber"] => string(12) "333912345678"
["securityresponseaddress"] => string(1) "0"
["securityresponsepostcode"] => string(1) "0"
["securityresponsesecuritycode"] => string(1) "0"
["settleduedate"] => string(10) "2023-12-05"
["settlestatus"] => string(3) "100"
["stan"] => string(6) "123456"
["transactionreference"] => string(10) "1-2-345679"
["transactionstartedtimestamp"] => string(19) "2023-12-05 15:38:16"
}
}
}
{
"requestreference": "W59-abcdeAbC",
"response": [
{
"accounttypedescription": "MOTO",
"acquirerresponsecode": "00",
"acquirerresponsemessage": "Approved or completed Successfully",
"authcode": "ABC123",
"baseamount": "1050",
"chargedescription": "Test Merchant",
"cryptocurrencyindicator": "0",
"currencyiso3a": "GBP",
"dccenabled": "0",
"debtrepayment": "0",
"errorcode": "0",
"errormessage": "Ok",
"issuer": "Test Issuer",
"issuercountryiso2a": "ZZ",
"livestatus": "1",
"maskedpan": "411111######1111",
"merchantcategorycode": "5999",
"merchantcity": "Test City",
"merchantcountryiso2a": "GB",
"merchantname": "Test Merchant",
"merchantnumber": "00000000",
"merchantzipcode": "T45 6ST",
"operatorname": "webservices@example.com",
"orderreference": "MyOrder123",
"parenttransactionreference": "1-2-345678",
"paymenttypedescription": "VISA",
"requesttypedescription": "REFUND",
"retrievalreferencenumber": "333912345678",
"securityresponseaddress": "0",
"securityresponsepostcode": "0",
"securityresponsesecuritycode": "0",
"settleduedate": "2023-12-05",
"settlestatus": "100",
"stan": "123456",
"transactionreference": "1-2-345679",
"transactionstartedtimestamp": "2023-12-05 15:38:16"
}
],
"secrand": "ui97",
"version": "1.00"
}
<responseblock version="3.67">
<requestreference>W59-abcdeAbC</requestreference>
<response type="REFUND">
<acquirerresponsecode>00</acquirerresponsecode>
<authcode>ABC123</authcode>
<billing>
<amount currencycode="GBP">1050</amount>
<dcc enabled="0"/>
<payment type="VISA">
<issuer>Test Issuer</issuer>
<issuercountry>ZZ</issuercountry>
<pan>411111######1111</pan>
</payment>
</billing>
<error>
<code>0</code>
<message>Ok</message>
</error>
<live>1</live>
<merchant>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Test Merchant</merchantname>
<merchantnumber>00000000</merchantnumber>
<operatorname>webservices@example.com</operatorname>
<orderreference>MyOrder123</orderreference>
<tid>27882788</tid>
</merchant>
<operation>
<accounttypedescription>MOTO</accounttypedescription>
<splitfinalnumber>1</splitfinalnumber>
</operation>
<other>
<retrievalreferencenumber>333912345678</retrievalreferencenumber>
<stan>123456</stan>
</other>
<security>
<address>0</address>
<postcode>0</postcode>
<securitycode>0</securitycode>
</security>
<settlement>
<settleduedate>2023-12-05</settleduedate>
<settlestatus>100</settlestatus>
</settlement>
<timestamp>2023-12-05 15:38:16</timestamp>
<transactionreference>1-2-345679</transactionreference>
</response>
<secrand>ui97</secrand>
</responseblock>
Offline refund response
{
'requestreference': 'Ak70u1ujh',
'version': '1.00',
'responses': [{
'accounttypedescription': 'ECOM',
'acquirerresponsecode': '00',
'authcode': 'TEST REFUND ACCEPTED',
'baseamount': '2001',
'currencyiso3a': 'GBP',
'dccenabled': '0',
'errorcode': '0',
'errormessage': 'Ok',
'issuer': 'SecureTrading Test Issuer1',
'issuercountryiso2a': 'US',
'livestatus': '0',
'maskedpan': '520000######1005',
'merchantcountryiso2a': 'GB',
'merchantname': 'Test Merchant',
'merchantnumber': '00000000',
'operatorname': 'webservices@example.com',
'orderreference': 'My_Order_123',
'parenttransactionreference': '1-2-345678',
'paymenttypedescription': 'MASTERCARD',
'requesttypedescription': 'REFUND',
'securityresponseaddress': '0',
'securityresponsepostcode': '0',
'securityresponsesecuritycode': '0',
'settleduedate': '2016-12-07',
'settlestatus': '0',
'tid': '27882788',
'transactionreference': '1-2-345679',
'transactionstartedtimestamp': '2016-12-07 15:14:00'
}]
}
array(3) {
["requestreference"] => string(9) "Acdefhwxy"
["version"] => string(4) "1.00"
["responses"] => array(1) {
[0] => array(28) {
["accounttypedescription"] => string(4) "ECOM"
["acquirerresponsecode"] => string(2) "00"
["authcode"] => string(20) "TEST REFUND ACCEPTED"
["baseamount"] => string(4) "2001"
["currencyiso3a"] => string(3) "GBP"
["dccenabled"] => string(1) "0"
["errorcode"] => string(1) "0"
["errormessage"] => string(2) "Ok"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["issuercountryiso2a"] => string(2) "US"
["livestatus"] => string(1) "0"
["maskedpan"] => string(16) "520000######1005"
["merchantcountryiso2a"] => string(2) "GB"
["merchantname"] => string(13) "Test Merchant"
["merchantnumber"] => string(8) "00000000"
["operatorname"] => string(23) "webservices@example.com"
["orderreference"] => string(12) "My_Order_123"
["parenttransactionreference"] => string(10) "1-2-345678"
["paymenttypedescription"] => string(10) "MASTERCARD"
["requesttypedescription"] => string(6) "REFUND"
["securityresponseaddress"] => string(1) "0"
["securityresponsepostcode"] => string(1) "0"
["securityresponsesecuritycode"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["settlestatus"] => string(1) "0"
["tid"] => string(8) "27882788"
["transactionreference"] => string(10) "1-2-345679"
["transactionstartedtimestamp"] => string(19) "2016-12-09 10:06:13"
}
}
}
{"requestreference":"W23-22rd4301",
"version":"1.00",
"response":[{
"accounttypedescription":"ECOM",
"acquirerresponsecode":"00",
"authcode":"TEST REFUND ACCEPTED",
"baseamount":"2001",
"currencyiso3a":"GBP",
"dccenabled":"0",
"errorcode":"0",
"errormessage":"Ok",
"issuer":"SecureTrading Test Issuer1",
"issuercountryiso2a":"US",
"livestatus":"0",
"maskedpan":"520000######1005",
"merchantcountryiso2a":"GB",
"merchantname":"Test Merchant",
"merchantnumber":"00000000",
"operatorname":"webservices@example.com",
"orderreference":"My_Order_123",
"parenttransactionreference":"1-2-345678",
"paymenttypedescription":"MASTERCARD",
"requesttypedescription":"REFUND",
"securityresponseaddress":"0",
"securityresponsepostcode":"0",
"securityresponsesecuritycode":"0",
"settleduedate":"2016-12-07",
"settlestatus":"0",
"tid":"27882788",
"transactionreference":"1-2-345679",
"transactionstartedtimestamp":"2016-12-07 15:31:48"
}],
"secrand":"SNQVg"}
<responseblock version="3.67">
<requestreference>Xk3mvyk5v</requestreference>
<response type="REFUND">
<authcode>TEST REFUND ACCEPTED</authcode>
<acquirerresponsecode>00</acquirerresponsecode>
<billing>
<amount currencycode="GBP">2001</amount>
<dcc enabled="0"/>
<payment type="MASTERCARD">
<issuer>SecureTrading Test Issuer1</issuer>
<issuercountry>US</issuercountry>
<pan>520000######1005</pan>
</payment>
</billing>
<error>
<code>0</code>
<message>Ok</message>
</error>
<live>0</live>
<merchant>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<merchantname>Test Merchant</merchantname>
<merchantnumber>00000000</merchantnumber>
<operatorname>webservices@example.com</operatorname>
<orderreference>My_Order_123</orderreference>
<tid>27882788</tid>
</merchant>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
<parenttransactionreference>1-2-345678</parenttransactionreference>
</operation>
<security>
<address>0</address>
<postcode>0</postcode>
<securitycode>0</securitycode>
</security>
<settlement>
<settleduedate>2012-10-08</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<timestamp>2012-10-08 12:46:11</timestamp>
<transactionreference>1-2-345679</transactionreference>
</response>
<secrand>f</secrand>
</responseblock>
