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 a payment, it is possible to pay the customer back by submitting a REFUND request. This page will walk you through the process.
Process overview
- Merchant submits REFUND request.
- Trust Payments validates the request and contacts the bank.
- Trust Payments processes the refund with the relevant acquirer.
- Trust Payments receives results of the request and passes this back to the merchant.
- Merchant receives and interprets this response.
Requirements
- You cannot refund a payment until Settlement has been performed. You can track the status of a transaction by looking at its settle status. A refund can only be processed if the settle status is “100”, which indicates the funds have been successfully transferred onto your bank account. Click here for further information on 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. Click here for a full 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. Click here for a full 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. Click here for a full list.
Field specification
When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.
| Field | Format | Description | |
| 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) |
|
| 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:
|
|
| 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. | |
| 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. |
|
| parenttransactionreference XPath: /operation/parenttransactionreference |
Alphanumeric & hyphens (25) |
This field must contain the transaction reference of the AUTH request that you would like to refund. | |
| requesttypedescriptions XPath: /@type |
Alpha (20) | The request type required is “REFUND”. | |
| 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. |
REFUND response
{
u 'requestreference': u 'Ak70u1ujh',
u 'version': u '1.00',
u 'responses': [{
u 'transactionstartedtimestamp': u '2016-12-07 15:14:00',
u 'parenttransactionreference': u '1-2-345678',
u 'livestatus': u '0',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'dccenabled': u '0',
u 'settleduedate': u '2016-12-07',
u 'errorcode': u '0',
u 'orderreference': u 'My_Order_123',
u 'tid': u '27882788',
u 'merchantnumber': u '00000000',
u 'merchantcountryiso2a': u 'GB',
u 'transactionreference': u '1-2-345679',
u 'merchantname': u 'Test Merchant',
u 'paymenttypedescription': u 'VISA',
u 'baseamount': u '2001',
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'requesttypedescription': u 'REFUND',
u 'securityresponsesecuritycode': u '0',
u 'currencyiso3a': u 'GBP',
u 'authcode': u 'TEST REFUND ACCEPTED',
u 'errormessage': u 'Ok',
u 'securityresponsepostcode': u '0',
u 'maskedpan': u '411111######1111',
u 'securityresponseaddress': u '0',
u 'issuercountryiso2a': u 'US',
u 'operatorname': u 'webservices@example.com',
u 'settlestatus': u '0'
}]
}
array(3) {
["requestreference"] => string(9) "Acdefhwxy"
["version"] => string(4) "1.00"
["responses"] => array(1) {
[0] => array(28) {
["transactionstartedtimestamp"] => string(19) "2016-12-09 10:06:13"
["parenttransactionreference"] => string(10) "1-2-345678"
["livestatus"] => string(1) "0"
["issuer"] => string(26) "SecureTrading Test Issuer1"
["dccenabled"] => string(1) "0"
["settleduedate"] => string(10) "2016-12-09"
["errorcode"] => string(1) "0"
["orderreference"] => string(12) "My_Order_123"
["tid"] => string(8) "27882788"
["merchantnumber"] => string(8) "00000000"
["securityresponsepostcode"] => string(1) "0"
["transactionreference"] => string(10) "1-2-345679"
["merchantname"] => string(13) "Test Merchant"
["paymenttypedescription"] => string(4) "VISA"
["baseamount"] => string(4) "2001"
["accounttypedescription"] => string(4) "ECOM"
["acquirerresponsecode"] => string(2) "00"
["requesttypedescription"] => string(6) "REFUND"
["securityresponsesecuritycode"] => string(1) "0"
["currencyiso3a"] => string(3) "GBP"
["authcode"] => string(20) "TEST REFUND ACCEPTED"
["errormessage"] => string(2) "Ok"
["merchantcountryiso2a"] => string(2) "GB"
["maskedpan"] => string(16) "411111######1111"
["securityresponseaddress"] => string(1) "0"
["issuercountryiso2a"] => string(2) "US"
["operatorname"] => string(23) "webservices@example.com"
["settlestatus"] => string(1) "0"
}
}
}
{"requestreference":"W23-22rd4301",
"version":"1.00",
"response":[{
"transactionstartedtimestamp":"2016-12-07 15:31:48",
"parenttransactionreference":"1-2-345678",
"livestatus":"0",
"issuer":"SecureTrading Test Issuer1",
"dccenabled":"0",
"settleduedate":"2016-12-07",
"errorcode":"0",
"baseamount":"2001",
"tid":"27882788",
"merchantnumber":"00000000",
"merchantcountryiso2a":"GB",
"transactionreference":"1-2-345679",
"merchantname":"Test Merchant",
"paymenttypedescription":"VISA",
"orderreference":"My_Order_123",
"accounttypedescription":"ECOM",
"acquirerresponsecode":"00",
"requesttypedescription":"REFUND",
"securityresponsesecuritycode":"0",
"currencyiso3a":"GBP",
"authcode":"TEST REFUND ACCEPTED",
"errormessage":"Ok",
"securityresponsepostcode":"0",
"maskedpan":"411111######1111",
"securityresponseaddress":"0",
"issuercountryiso2a":"US",
"operatorname":"webservices@example.com",
"settlestatus":"0"
}],
"secrand":"SNQVg"}
<responseblock version="3.67">
<requestreference>Xk3mvyk5v</requestreference>
<response type="REFUND">
<merchant>
<merchantname>Test Merchant</merchantname>
<orderreference>My_Order_123</orderreference>
<tid>27882788</tid>
<merchantnumber>00000000</merchantnumber>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<operatorname>webservices@example.com</operatorname>
</merchant>
<transactionreference>1-2-345679</transactionreference>
<billing>
<amount currencycode="GBP">2001</amount>
<payment type="VISA">
<issuer>SecureTrading Test Issuer1</issuer>
<issuercountry>US</issuercountry>
<pan>411111######1111</pan>
</payment>
<dcc enabled="0"/>
</billing>
<authcode>TEST REFUND ACCEPTED</authcode>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<timestamp>2012-10-08 12:46:11</timestamp>
<acquirerresponsecode>00</acquirerresponsecode>
<security>
<address>0</address>
<postcode>0</postcode>
<securitycode>0</securitycode>
</security>
<settlement>
<settleduedate>2012-10-08</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<operation>
<parenttransactionreference>1-2-345678</parenttransactionreference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</response>
<secrand>f</secrand>
</responseblock>
The specification of the REFUND response is the same as the standard AUTH response, except the requesttypedescription field has value “REFUND”. You will need to check the fields returned are correct. In particular, ensure the errorcode is “0” (indicating the request was processed successfully) and that the settlestatus is NOT “2” or “3” (indicating funds will not settle).