REFUND with Webservices API

  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

  1. Merchant submits REFUND request.
  2. Trust Payments validates the request and contacts the bank.
  3. Trust Payments processes the refund with the relevant acquirer.
  4. Trust Payments receives results of the request and passes this back to the merchant.
  5. 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:

Python PHP cURL Raw JSON Raw XML
#!/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

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.

Python PHP cURL Raw JSON Raw XML
#!/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

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.

Python PHP cURL Raw JSON Raw XML
#!/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

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
X3-EN.png 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)

X3-EN.png 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:

  • Uppercase/lowercase A-Z
  • Numbers 0-9
  • Spaces
  • Punctuation: + – _ . @ ( )
X3-EN.png 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.
X3-EN.png 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.

X1-EN.png parenttransactionreference
XPath: /operation/parenttransactionreference
Alphanumeric
& hyphens (25)
This field must contain the transaction reference of the AUTH request that you would like to refund.
X1-EN.png requesttypedescriptions
XPath: /@type
Alpha (20) The request type required is “REFUND”.
X1-EN.png 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

Python PHP Raw JSON Raw XML
{
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'
}]
}

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

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request