Contents

Refunds

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

 

Requirements

 

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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/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"
}]}'

 

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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/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"
}]}'

 

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 = Securetradingapi($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user webservices@example.com:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{"alias": "webservices@example.com",
"version": "2001",
"request": [{
  "requesttypedescriptions": ["REFUND"],
  "sitereference": "test_site12345",
  "parenttransactionreference": "1-2-345678",
  "baseamount": "200"
}]}'

 

Field specification

Info
When reading the following specification, please ensure that you reference the relevant code examples for your chosen language.

 

Key

Field name Type Length Request Description
requesttypedescriptions Alpha 20 The request type required is “REFUND”.
sitereference Alphanumeric including 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.

parenttransactionreference Alphanumeric including hyphens 25 This field must contain the transaction reference of the AUTH request that you would like to refund.
expirydate Date MM/YYYY 7 If you would like to process a refund with an updated expiry date, the new value is submitted in this field.
baseamount 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)

orderreference Alphanumeric including symbols 255 Your unique order reference that can be stored on Secure Trading’s system.

If this is not submitted, it is inherited from the parent AUTH request.

chargedescription Alphanumeric including symbols 25 This is a description of the payment that appears on the customer’s bank statement.

Only supported by certain acquiring banks.

Specification of this field will depend on your acquiring bank. For further information, please contact our Support team.

Valid characters:

  • Uppercase/lowercase A-Z
  • Numbers 0-9
  • Spaces
  • Punctuation: + – _ . @ ( )

 

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"
}

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).

 


 

Additional resources