Reversal (Void)

This page provides an overview of how to initiate and manage reversal (void) transactions using the Vortex API. It explains the types of reversals, use cases, potential failure scenarios, and implementation tips.

In this guide, you’ll find:

• An explanation of full and partial reversals and when to use each type.
• A list of common failure scenarios that can prevent a reversal from being processed.
• Key implementation considerations for successfully processing reversal transactions.

A "Reversal" or "Void" transaction in the Vortex API enables merchants to cancel a transaction that has been authorized but not yet settled.

Reversals prevent the transfer of funds from the customer's account, effectively negating the transaction.

Use Cases

• Full Reversal: Used when the entire transaction needs to be canceled, typically due to an error in the original transaction, cancellation of services, or a customer's request to cancel the purchase.
• Partial Reversal: Applicable when only a part of the transaction is to be canceled. This could occur in situations where the customer decides to reduce their order or when a mistake was made in the original amount charged.

Examples

Full Reversal

Request Body

{
  "arguments": [
    {
      "ecom": false,
      "moto": false,
      "externalId": "844171414052141",
      "transactionType": "Void",
      "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,
      "authCode": "PPSca8",
      "originalExternalId": "425570141719573"
    }
  ],
  "procedure": "card.create",
  "class": "rpc",
  "requestId": "Scenario_Visa_WS0.S490_03"
}

Response Body

{
  "code": 200,
  "requestId": "Scenario_Visa_WS0.S490_03",
  "id": "5648f1cb-7fc6-40f5-800b-59bac5a663cd",
  "error": null,
  "value": {
    "authCode": "PPSca8",
    "code": 0,
    "cardType": "Visa",
    "message": "Void Approved",
    "network": "visa",
    "authorization": {
      "authorized": false,
      "processingTime": "00:00:00",
      "reversed": false
    },
    "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"
    },
    "requestedAmount": 40.05,
    "id": "WT1nKNIPBGvYfxM2uf/dbg==",
    "partial": false,
    "reversed": false
  },
  "class": "response"
}

Partial Reversal

Request Body

{
  "arguments": [
    {
      "ecom": false,
      "moto": false,
      "externalId": "884152323103865",
      "transactionType": "Reversal",
      "totalAmount": 38.02,
      "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,
      "authCode": "PPS4ef",
      "originalExternalId": "894336631281994"
    }
  ],
  "procedure": "card.create",
  "class": "rpc",
  "requestId": "Scenario_Visa_WS0.S61_2"
}

Response Body

{"authCode":"S941J3","code":0,"message":"Void Approved","declined":false,"approved":true,"reversed":false,"partial":false,"totalAmount":38.02,"requestedAmount":38.02,"originalAmount":38.02,"authorization":{"processingTime":"00:00:00","authorized":false,"reversed":false,"incremental":false},"cardType":"Visa","network":"visa","cardBin":{"type":"CREDIT","bank":{"www":"www.hsbc.com.sg","name":"HSBC","phone":"6468 5566"},"bin":"47613400","brand":"VISA","country":{"iso":"702","info":"","name":"Singapore","abbreviation2":"SG","abbreviation3":"SGP"},"id":"47613400","source":"pci.bindb.com","level":"CLASSIC","prepaid":false,"reloadable":false,"business":false,"regulated":false},"accountNumberMask":"0050","id":"LqUA8etaHzz+MT00md1guQ==","meta":{"id":"LqUA8etaHzz+MT00md1guQ==","externalId":"1748627202124","received":"2025-05-30T17:46:44.349Z","tenantId":"A1A9550E-830C-474E-9836-DFD4DB492BC0","tenantName":"Test Tenant","replicationGroup":"qa","virtualEnv":"qa-atl","originatingInstance":"natl","environment":"default"}}`

Failed Scenarios

Reversal transactions may fail under certain conditions. Common failure scenarios include:

• Transaction already settled:
  The transaction has been settled and funds have already been transferred, making a reversal impossible.

• Invalid transaction ID:
  The originalTransactionId provided does not correspond to a valid or existing transaction.

• Partial amount exceeds original:
  For partial reversals, the amount specified exceeds the original transaction amount.

• Technical Issues:
  Failures may also occur due to system-level issues within Vortex or communication errors with the bank.

For a comprehensive list of error codes to help troubleshoot reversal failures, visit the Error Codes page.
—

Implementation Notes

• When initiating a reversal, ensure that the originalTransactionId is accurately provided and that the transaction is in a state that allows for reversal.
• For partial reversals, it's crucial to specify the amount to be reversed clearly and ensure it does not exceed the original transaction amount.

Understanding and anticipating common failure scenarios can aid in troubleshooting and resolving issues promptly.