Refund Method

Description

The Refund method allows the merchant to issue a refund (full or partial) of a settled CardNotPresent or MasterPass transaction.

Action

http://www.ecentricswitch.co.za/paymentgateway/v1/Refund

Style

Document

Input (Literal)

The input of this method is the document element RefundRequest having the structure defined by the following table.

ELEMENT	TYPE	SIZE(MAX)	DESCRIPTION
MessageHeader
MessageDateTime	datetime		The message timestamp.
MessageID	string	50	A unique identifier to identify the message.
Channel	string	50	An identifier to identify the source of the message.
RefundRequest Required
MerchantID Required	string	50	A unique identifier to identify the merchant. Also known as Merchant GUID.
TransactionID Required	string	50	A unique identifier provided by the merchant on the API call to identify the transaction.
PreviousTransactionID Required	string	50	A unique identifier to identify a preceding transaction (Capture or Payment).
TransactionDateTime	datetime		The transaction timestamp.
SaleReconID	string	100	A unique identifier for reconciliation purposes.
ReconID	string	50	A unique identifier for reconciliation purposes.
Amount Required	long		The refund amount in the lowest monetary unit.
CurrencyCode	string	3	The currency code according to the ISO 4217 standard. The default for South Africa is ZAR.
OrderNumber	string	50	The transaction order or reference number. Note: Only Alphanumeric characters i.e. [a..z], [A..Z], [0..9] are allowed. NO spaces or special characters are allowed. The first 12 characters of this field will be sent to the acquirer/bank as the Retrieval Reference Number (RRN). Therefore the first 12 characters must be unique. Duplicate RRN’s may cause transaction failures.
PaymentService Required	PaymentServiceType		The target payment service.
FirstName	string	50	The customer first name.
LastName	string	50	The customer last name.
BillingAddress	Address		The billing address.
ShippingAddress	Address		The shipping address.
Email	string	254	The customer email.
MobilePhone	string	20	The customer mobile phone number.
HomePhone	string	20	The customer home phone number.
WorkPhone	string	20	The customer work phone number.
MerchantCategoryCode	string	4	This parameter is optional. It is used when a merchant wishes to pass a unique MCC (MerchantCategoryCode) eg: 5399
CardOnFileScenario	CardOnFileScenario	10	An identifier allowing a merchant to indicate which specific CIT (customer initiated) or MIT (merchant initiated) transaction is being performed
SubMerchantID	string	15	This is the unique ID of the Sub Merchant. Applicable to aggregators. Max length is 15 characters

Output (Literal)

The output of this method is the document element RefundResponse having the structure defined by the following table.

ELEMENT	TYPE	SIZE(MAX)	DESCRIPTION
MessageHeader Required
MessageDateTime	datetime		The message timestamp.
MessageID	string	50	A unique identifier to identify the message.
Channel	string	50	An identifier to identify the source of the message.
RefundResponse Required
TransactionID Required	string	50	A unique identifier to identify the transaction.
TransactionDateTime Required	datetime		The transaction timestamp.
ReconID Required	string	50	A unique identifier for reconciliation purposes.
AuthCode	string	50	The result code definition.
TransactionStatus Required	TransactionStatusType		The transaction status (Success and Failure)
ResponseDetail Required	ResponseDetail		The transaction result code.

Sample Message

Request

Body

" <soapenv:Envelope
 	xmlns:soapenv=""http://schemas.xmlsoap.org/soap/envelope/""
 	xmlns:=""http://www.ecentricswitch.co.za/paymentgateway/v1"">
 	<soapenv:Header>
 		<MessageHeader></MessageHeader>
 	</soapenv:Header>
 	<soapenv:Body>
 		<RefundRequest>
 			<MerchantID>8B67BF88-BB8D-4EB5-ADFC-0F5C97C7ED67</MerchantID>
 			<MerchantUserID>978e566b-d62a-42c0-9843-381b3588f333</MerchantUserID>
 			<TransactionID>0f7d0c09-63af-484b-b20b-ae8d4ef67016</TransactionID>
 			<PreviousTransactionID>c3d941ad-7e52-4882-9334-5165cdab2d9c</PreviousTransactionID>
 			<CurrencyCode>ZAR</CurrencyCode>
 			<Amount>50</Amount>
 			<OrderNumber>MR28152151</OrderNumber>
 			<Card>
 			<Token>081C1396-493D-4E09-81F9-749CE53E0CDE</Token>
 			<SecurityCode>360</SecurityCode>
 			</Card>
 		</RefundRequest>
 	</soapenv:Body>
 </soapenv:Envelope>"

Response

Body

<s:Envelope
	xmlns:s=""http://schemas.xmlsoap.org/soap/envelope/"">
	<s:Header>
		<h:MessageHeader
			xmlns:h=""http://www.ecentricswitch.co.za/paymentgateway/v1""
			xmlns=""http://www.ecentricswitch.co.za/paymentgateway/v1""
			xmlns:xsd=""http://www.w3.org/2001/XMLSchema""
			xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"">
			<MessageDateTime>2024-11-07T12:26:50.12</MessageDateTime>
			<MessageID>90F05E4E-72FB-4B23-BD6F-C28E8C9F61D6</MessageID>
			<Channel xsi:nil=""true""/>
		</h:MessageHeader>
	</s:Header>
	<s:Body
		xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance""
		xmlns:xsd=""http://www.w3.org/2001/XMLSchema"">
		<RefundResponse xmlns=""http://www.ecentricswitch.co.za/paymentgateway/v1"">
			<TransactionID>0f7d0c09-63af-484b-b20b-ae8d4ef67016</TransactionID>
			<TransactionDateTime>2024-11-07T12:26:49.107</TransactionDateTime>
			<SaleReconID xsi:nil=""true""/>
			<ReconID/>
			<AuthCode xsi:nil=""true""/>
			<TransactionStatus>Success</TransactionStatus>
			<ResponseDetail>
				<Source>Acquirer</Source>
				<Code>00</Code>
				<Description>Approved or completed successfully</Description>
				<ClientMessage>Approved.</ClientMessage>
			</ResponseDetail>
		</RefundResponse>
	</s:Body>
</s:Envelope>