👍

Required Fields

To get a comprehensive list of fields, please visit our Required Fields dedicated page.

Reversal (Void)

A "Reversal" or "Void" transaction in the Vortex API allows merchants to cancel a transaction that has been authorized but not yet settled. This can be a full reversal, where the entire transaction amount is voided, or a partial reversal, where only a portion of the amount is canceled. This action prevents 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

{
  "code": 422,
  "requestId": "Scenario_Visa_WS0.S61_2",
  "id": "162fec67-0c9f-4e0b-b6a3-b60a7cce83b1",
  "error": "Error: The external Id '894336631281994' is invalid: the provided amount (38.02) does not match the original payment (40.05)",
  "value": null,
  "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

Reversal transactions can fail due to several reasons, including but not limited to:

• Transaction Already Settled: The original transaction has already been settled, and funds have been transferred, making a reversal impossible.
• Invalid Transaction ID: The originalTransactionId provided does not correspond to any existing or valid transaction.
• Partial Amount Exceeds Original: In partial reversals, the amount specified to be reversed exceeds the original transaction amount.
• Technical Issues: Failures may also occur due to technical issues within the Vortex system or communication errors with the bank.

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.