1. TRU Connect   
  2. Webservices API
  3. Request / Response Schema

REFUND with Webservices API

​  Last updated: 

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

  • All Visa refunds submitted via new site references registered on our system after 13th December 2023 will automatically be processed online.
  • All Visa refunds submitted via established site references registered on our system before 13th December 2023 will automatically be processed online from 21st March 2024 onwards.
  • Please contact our Support Team for further information.

Offline refunds

  1. Merchant submits REFUND request.
  2. Trust Payments validates the request and returns a "REFUND ACCEPTED" response to the merchant.
  3. Trust Payments processes the refund with the relevant acquirer.
  4. The relevant acquirer processes the refund and the cardholder receives the refunded amount.

Online refunds

  1. Merchant submits REFUND request.
  2. Trust Payments validates the request and requests authorisation from the card issuer to process the refund and returns the card issuer's response to the merchant.
  3. When step 2 returns an authorised response, Trust Payments processes the refund with the relevant acquirer.
  4. The relevant acquirer processes the refund and the cardholder receives the refunded amount.

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

 

Requirements

  • You can only refund payments with settle status “100”, which indicates the funds have been successfully transferred to 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
  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:

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

  AUTH field specification      Info on handling responses

 

Offline refund response

Python PHP Raw JSON Raw XML 
{
u 'requestreference': u 'Ak70u1ujh',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'ECOM',
u 'acquirerresponsecode': u '00',
u 'authcode': u 'TEST REFUND ACCEPTED',
u 'baseamount': u '2001',
u 'currencyiso3a': u 'GBP',
u 'dccenabled': u '0',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'issuer': u 'SecureTrading Test Issuer1',
u 'issuercountryiso2a': u 'US',
u 'livestatus': u '0',
u 'maskedpan': u '520000######1005',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Test Merchant',
u 'merchantnumber': u '00000000',
u 'operatorname': u 'webservices@example.com',
u 'orderreference': u 'My_Order_123',
u 'parenttransactionreference': u '1-2-345678',
u 'paymenttypedescription': u 'MASTERCARD',
u 'requesttypedescription': u 'REFUND',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '0',
u 'settleduedate': u '2016-12-07',
u 'settlestatus': u '0',
u 'tid': u '27882788',
u 'transactionreference': u '1-2-345679',
u 'transactionstartedtimestamp': u '2016-12-07 15:14:00'
}]
}

 

Online refund response

  • All Visa refunds submitted via new site references registered on our system after 13th December 2023 will automatically be processed online.
  • All Visa refunds submitted via established site references registered on our system before 13th December 2023 will automatically be processed online from 21st March 2024 onwards.
  • Please contact our Support Team for further information.
Python PHP Raw JSON Raw XML 
{
u 'requestreference': u 'A0bxh87wt',
u 'version': u '1.00',
u 'responses': [{
u 'accounttypedescription': u 'MOTO',
u 'acquirerresponsecode': u '00',
u 'acquirerresponsemessage': u 'Approved or completed Successfully',
u 'authcode': u 'ABC123',
u 'baseamount': u '1050',
u 'chargedescription': u 'Test Merchant',
u 'cryptocurrencyindicator': u '0',
u 'currencyiso3a': u 'GBP',
u 'dccenabled': u '0',
u 'debtrepayment': u '0',
u 'errorcode': u '0',
u 'errormessage': u 'Ok',
u 'issuer': u 'Test Issuer',
u 'issuercountryiso2a': u 'ZZ',
u 'livestatus': u '1',
u 'maskedpan': u '411111######1111',
u 'merchantcategorycode': u '5999',
u 'merchantcity': u 'Test City',
u 'merchantcountryiso2a': u 'GB',
u 'merchantname': u 'Test Merchant',
u 'merchantnumber': u '00000000',
u 'merchantzipcode': u 'T45 6ST',
u 'operatorname': u 'webservices@example.com',
u 'orderreference': u 'MyOrder123',
u 'parenttransactionreference': u '1-2-345678',
u 'paymenttypedescription': u 'VISA',
u 'requesttypedescription': u 'REFUND',
u 'retrievalreferencenumber': u '333912345678',
u 'securityresponseaddress': u '0',
u 'securityresponsepostcode': u '0',
u 'securityresponsesecuritycode': u '0',
u 'settleduedate': u '2023-12-05',
u 'settlestatus': u '100',
u 'stan': u '123456',
u 'transactionreference': u '1-2-345679',
u 'transactionstartedtimestamp': u '2023-12-05 15:38:16'
}]
}

 

  Additional resources

Was this article helpful?
0 out of 0 found this helpful
Avatar
Michael Buckley