Refund

This page covers the process of initiating a refund or return transaction through the Vortex API. It outlines the key requirements, common use cases, potential failures, and essential implementation details for handling refunds effectively.

In this guide, you’ll find:

Common use cases for refunds, such as product returns, service cancellations, and overcharge adjustments.
A list of potential failure scenarios and their causes to help troubleshoot issues.
Key implementation notes to ensure a smooth and accurate refund process.

Refund (Return) in Vortex

A "Refund" or "Return" transaction in the Vortex API enables merchants to return previously captured funds to a customer's account.

The primary validation for initiating a refund is the originalAuthorizationId of the original sale transaction.

Use Cases

Refund transactions are applicable in various scenarios, including:

Product returns: Issuing refunds when customers return products, regardless of the reason.
Service cancellations: Reimbursing customers when a service is canceled.
Overcharges and adjustments: Correcting billing errors, such as overcharges or adjustments to the 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

Refund transactions can fail due to several reasons. Common failure scenarios include:

Invalid authorization ID:
The provided originalAuthorizationId does not match any valid or existing transaction.
Transaction not eligible for refund:
The original transaction is either not eligible for a refund due to its status or exceeds the allowable refund timeframe.
Amount exceeds original transaction:
Attempting to refund more than the total amount of the original transaction.
Technical issues:
System-related errors within Vortex or communication failures with the banking network.

For a detailed list of error codes and their descriptions, visit our Error Codes dedicated page

Implementation Notes

When processing a refund transaction, follow these best practices to ensure successful execution:

Verify the authorization ID:
Ensure the originalAuthorizationId corresponds to a valid and eligible transaction.
Check refund eligibility:
Confirm that the transaction meets the requirements for refunds, including status and timeframe constraints.
Validate the refund amount:
Ensure the refund amount does not exceed the total of the original transaction.
Review additional fields:
Consult the refund schema and include any additional fields relevant to the specific refund scenario.
Anticipate and mitigate Failures:
Familiarize yourself with potential failure scenarios and error codes to troubleshoot issues efficiently and provide better customer support.