Refund (Return)
This guide details the process for executing Refund (Return) transactions in Vortex, emphasizing the importance of authorization IDs and the flexibility to incorporate additional fields to cater to diverse refund scenarios. It aims to provide merchants with the knowledge to manage refunds seamlessly.
Required Fields
To get a comprehensive list of fields, please visit our Required Fields dedicated page.
Refund (Return)
A "Refund" or "Return" transaction in the Vortex API allows merchants to return previously captured funds to a customer's account. This transaction is typically processed in response to a return of goods or services and can be executed with only the authorization ID of the original sale transaction as the primary validation point.
Use Cases
- Product Returns: When a customer returns a product for any reason, and a refund is warranted.
- Service Cancellations: If a service is canceled and requires a refund to the customer.
- Overcharges and Adjustments: To correct any overcharges or adjustments to the original transaction amount.
Examples
Create a Refund Transaction
Request Body
{
"arguments": [
{
"ecom": false,
"moto": false,
"externalId": "663031987774850",
"transactionType": "Return",
"totalAmount": 40.05,
"currencyCode": "840",
"merchant": {
"accountId": "261559",
"name": "PPS Engineering UAT 2",
"sic": "7399",
"address": {
"street1": "2001 Westside",
"city": "Alpharetta",
"state": "GA",
"postalCode": "30004"
},
"number": "518089240725465",
"processor": {
"name": "TSYS",
"bankNumber": "8739"
},
"sponsor": {
"ica": "3583",
"bin": "470780"
}
},
"meta": {
"created": "2024-02-21"
},
"account": {
"form": "plastic",
"expiry": "2025-12",
"number": "4761340000000050"
},
"device": {
"accountCaptureMethod": "manual"
},
"recurring": false
}
],
"procedure": "card.create",
"class": "rpc",
"requestId": "Scenario_Visa_WS0.S2_1"
}
Response Body
{
"code": 200,
"requestId": "Scenario_Visa_WS0.S2_1",
"id": "95dbe80b-2b83-439c-83bb-454a3d2cd4ee",
"error": null,
"value": {
"authCode": "PPS67a",
"code": 0,
"productId": "V",
"cardType": "Visa",
"validationCode": "VI59",
"message": "Approved and completed successfully",
"transactionId": "050000000019259",
"network": "visa",
"reference": "405200901031",
"authorization": {
"request": "AQByPGSBCGCANhBHYTQAAAAAUCAAAAAAAABABQIhAAAAkBAxAAAAAiElEnOZCEABAHEGQIZE9PD18vDw+fDx8PPx9fH48Pj58vTw9/L19Pb119fiQMWVh4mVhYWZiZWHQOTB40DyQEBAQMGTl4iBmYWjo4FAQEBAQAhACvHz8PDw8/Dw8PQGQAAAAAAACYAAAAAAAAAA6AWAAAAAAg==",
"response": "ARASIgAADhBABAAAAABABQIhAAAAkBAxAiH08PXy8PD58PHw8/HX1+L294Hw8AHlCEAX4AACAAAAAADVAFAAAAABklnlyfX55UA=",
"authorized": true,
"networkResponseMessage": {
"mti": "0110",
"bitmap1": "122200000E104004",
"fields": [
{
"bitmap": 4,
"dataType": "BinaryCodedDecimal",
"name": "TransactionAmount",
"value": "40.05"
},
{
"bitmap": 7,
"dataType": "BinaryCodedDecimal",
"name": "TransmissionDateTime",
"value": "0221000000"
},
{
"bitmap": 11,
"dataType": "BinaryCodedDecimal",
"name": "SystemTraceAuditNumber",
"value": "901031"
},
{
"bitmap": 15,
"dataType": "BinaryCodedDecimal",
"name": "SettlementDate",
"value": "0221"
},
{
"bitmap": 37,
"dataType": "AlphaNumeric",
"name": "RetrievalReferenceNumber",
"value": "405200901031"
},
{
"bitmap": 38,
"dataType": "AlphaNumeric",
"name": "AuthorizationIdentificationResponse",
"value": "PPS67a"
},
{
"bitmap": 39,
"dataType": "AlphaNumeric",
"name": "ResponseCode",
"value": "00"
},
{
"bitmap": 44,
"dataType": "AlphaNumeric",
"name": "AdditionalResponseData",
"length": 1,
"value": "V"
},
{
"bitmap": 50,
"dataType": "BinaryCodedDecimal",
"name": "SettlementCurrencyCode",
"value": "840"
},
{
"bitmap": 62,
"dataType": "Binary",
"name": "PrivateUse62",
"length": 23,
"value": "E000020000000000D50050000000019259E5C9F5F9E540"
}
]
},
"source": "V",
"acceptorId": "518089240725465",
"processingTime": "00:00:00.3441080",
"reversed": false,
"networkRequestMessage": {
"mti": "0100",
"bitmap1": "723C648108608036",
"fields": [
{
"bitmap": 2,
"dataType": "BinaryCodedDecimal",
"name": "PrimaryAccountNumber",
"length": 16,
"value": "4761340000000050"
},
{
"bitmap": 3,
"dataType": "BinaryCodedDecimal",
"name": "ProcessingCode",
"value": "200000"
},
{
"bitmap": 4,
"dataType": "BinaryCodedDecimal",
"name": "TransactionAmount",
"value": "40.05"
},
{
"bitmap": 7,
"dataType": "BinaryCodedDecimal",
"name": "TransmissionDateTime",
"value": "0221000000"
},
{
"bitmap": 11,
"dataType": "BinaryCodedDecimal",
"name": "SystemTraceAuditNumber",
"value": "901031"
},
{
"bitmap": 12,
"dataType": "BinaryCodedDecimal",
"name": "TransactionTimeLocal",
"value": "000000"
},
{
"bitmap": 13,
"dataType": "BinaryCodedDecimal",
"name": "TransactionDateLocal",
"value": "0221"
},
{
"bitmap": 14,
"dataType": "BinaryCodedDecimal",
"name": "ExpirationDate",
"value": "2512"
},
{
"bitmap": 18,
"dataType": "BinaryCodedDecimal",
"name": "MerchantType",
"value": "7399"
},
{
"bitmap": 19,
"dataType": "BinaryCodedDecimal",
"name": "AcquiringInstitutionCountryCode",
"value": "840"
},
{
"bitmap": 22,
"dataType": "BinaryCodedDecimal",
"name": "PointOfServiceEntryMode",
"value": "100"
},
{
"bitmap": 25,
"dataType": "BinaryCodedDecimal",
"name": "PointOfServiceConditionCode",
"value": "71"
},
{
"bitmap": 32,
"dataType": "BinaryCodedDecimal",
"name": "AcquiringInstitutionIdCode",
"length": 6,
"value": "408644"
},
{
"bitmap": 37,
"dataType": "AlphaNumeric",
"name": "RetrievalReferenceNumber",
"value": "405200901031"
},
{
"bitmap": 42,
"dataType": "AlphaNumeric",
"name": "CardAcceptorIdentification",
"value": "518089240725465"
},
{
"bitmap": 43,
"dataType": "Binary",
"name": "CardAcceptorNameLocation",
"value": "D7D7E240C59587899585859989958740E4C1E340F240404040C1939788819985A3A3814040404040"
},
{
"bitmap": 49,
"dataType": "BinaryCodedDecimal",
"name": "TransactionCurrencyCode",
"value": "0840"
},
{
"bitmap": 59,
"dataType": "AlphaNumericSpecial",
"name": "NationalUse59",
"length": 10,
"value": "1300030004"
},
{
"bitmap": 60,
"dataType": "BinaryCodedDecimal",
"name": "AdviceReasonCode",
"length": 12,
"value": "400000000000"
},
{
"bitmap": 62,
"dataType": "Binary",
"name": "PrivateUse62",
"length": 9,
"value": "8000000000000000E8"
},
{
"bitmap": 63,
"dataType": "Binary",
"name": "PrivateUse63",
"length": 5,
"value": "8000000002"
}
]
},
"responseCode": "00",
"accountCaptureMethod": 1
},
"totalAmount": 40.05,
"approved": true,
"declined": false,
"originalAmount": 40.05,
"cardBin": {
"country": {
"iso": "702",
"name": "Singapore",
"abbreviation2": "SG",
"info": "",
"abbreviation3": "SGP"
},
"bank": {
"phone": "6468 5566",
"www": "www.hsbc.com.sg",
"name": "HSBC"
},
"business": false,
"level": "CLASSIC",
"regulated": false,
"bin": "47613400",
"reloadable": false,
"prepaid": false,
"id": "47613400",
"source": "pci.bindb.com",
"type": "CREDIT",
"brand": "VISA"
},
"lossPrevention": {},
"aciResponse": "N",
"requestedAmount": 40.05,
"id": "nJqdUNwpSuG/Qc64x284Bg==",
"partial": false,
"reversed": false
},
"class": "response"
}
Failed Scenarios
To get a comprehensive list of Error Codes to help you understand the Failed Scenarios, please visit our Error Codes dedicated page
Refund transactions can encounter failures due to several reasons, including:
- Invalid Authorization ID: The
originalAuthorizationIddoes not match any existing or valid transaction. - Transaction Not Eligible for Refund: The original transaction may not be eligible for a refund due to its status or timeframe since the transaction date.
- Amount Exceeds Original Transaction: Attempting to refund more than the original transaction amount.
- Technical Issues: Systematic errors within Vortex or communication issues with the banking network.
Implementation Notes
When processing a refund, ensure the originalAuthorizationId is correct and corresponds to a transaction that is eligible for a refund. Carefully review the scenarios/fields schema to identify and include any additional fields that may be relevant to the specific refund scenario you are processing. Understanding the potential reasons for refund failures can also help in troubleshooting and providing better customer service.
Updated over 1 year ago