Skip to main content
The doTransaction method allows you to process refunds. There are two primary scenarios for this operation:
  • Standard Refund: Done on the same terminal where the original sale occurred.
  • External Refund: Done on a different terminal, requiring additional metadata for server-side validation.
To perform a Refund transaction, save the originalTransactionId from the original transaction.

​
Standard Refund

A Standard Refund is utilized when a transaction needs to be reversed or partially returned using the same terminal that processed the original sale.

​
Request

The following example shows a typical request body for a standard refund:
JSON
{
  "jsonrpc": "2.0",
  "method": "doTransaction",
  "id": "123454352",
  "params": [
    "engine",
    {
      "vuid": "80b45894",
      "amount": 100,
      "originalTransactionId": "2022052432",
      "tranType": 2
    }
  ]
}

​
External Refund [from other device]

To refund a transaction initiated on a different terminal, the system requires the following metadata from the original transaction to ensure security and validity:
  • transactionOriginalTime
  • transactionOriginalAmount
  • transactionOriginalRequestId
  • mainBoardSerial
  • hwSerial

​
Request

The following example shows a typical request body for an external refund: 
{
  "jsonrpc": "2.0",
  "method": "doTransaction",
  "id": "123454352",
  "params": [
    "engine",
    {
      "vuid": "$guid",
      "amount": 13,
      "originalTransactionId": "2037037300",
      "originalSiteId": 1,
      "transactionOriginalTime": "2025-02-17 03:04:40.760",
      "transactionOriginalAmount": 13,
      "transactionOriginalRequestId": "afbae618-678f-45a9-ad87-5073c36419a2",
      "mainBoardSerial": "543654645",
      "hwSerial": "1231412",
      "tranType": 2
    }
  ]
}

​
Response

A successful request will return a response similar to the one in the code block below: 
{
  "jsonrpc": "2.0",
  "id": "123454352",
  "result": {
    "statusCode": 0,
    "statusMessage": "TRANSACTION APPROVED",
    "appVersion": "01.06.62",
    "vuid": "123454",
    "amount": 100,
    "transactionId": "2022052432",
    "entryMode": 1,
    "transactionOriginalRequestId": "6439809e-619f-414b-8c3e-f1a9f3c3bc49",
    "transactionOriginalTime": "0001-01-01 00:00:00.000",
    "transactionOriginalAmount": 100,
    "serverResultMessage": "Refund is Approved",
    "tranType": 2,
    "dtId": "1741246498022399011",
    "currencyCode": "USD",
    "currencyISOCode": "840",
    "mainBoardSerial": "000177234933444",
    "hwSerial": "0900044624102737"
  }
}

​
Refund Request Parameters

To perform a refund, you must include the following parameters within the params object of the doTransaction method.
NameTypeDescription
jsonrpcstringJSON-RPC protocol version (e.g., “2.0”).
methodstringThe API method to call: doTransaction.
vuidstringVendor unique identifier.
amountintegerThe refund amount (in the smallest currency unit, e.g., cents).
originalTransactionIdstringMandatory. The ID of the transaction to be refunded.
tranTypeintegerMandatory. Set to 2 for Refund transactions.
originalSiteIdintegerConditional. Required for external refunds to identify the source site.
transactionOriginalTimestringConditional. Original timestamp in YYYY-MM-DD HH:MM:SS.mmm format.
transactionOriginalAmountintegerConditional. The original amount of the initial transaction.
transactionOriginalRequestIdstringConditional. The original request GUID/ID.
mainBoardSerialstringConditional. Mainboard serial of the original device.
hwSerialstringConditional. Hardware serial of the original device.

​
Refund Response Parameters

Below are the parameters returned in the result object following a refund request:
NameTypeDescription
statusCodeinteger0 for success; non-zero for errors or declines.
statusMessagestringHigh-level status text (e.g., “TRANSACTION APPROVED”).
appVersionstringThe current version of the application.
vuidstringVendor unique identifier for the transaction.
amountintegerThe amount processed for the refund.
transactionIdstringThe unique ID assigned to this refund attempt.
entryModeintegerMethod used to enter the card data.
transactionOriginalRequestIdstringMatches the request ID of the original transaction.
transactionOriginalTimestringThe timestamp recorded for the original transaction.
transactionOriginalAmountintegerThe total amount of the original transaction.
serverResultMessagestringDetailed message from the processor (e.g., “Refund is Approved”).
tranTypeintegerTransaction type identifier (e.g., 2).
dtIdstringDevice-specific transaction identifier.
currencyCodestringAlphanumeric currency code (e.g., “USD”).
currencyISOCodestringNumeric ISO currency code (e.g., “840”).
mainBoardSerialstringSerial number of the processing device’s main board.
hwSerialstringHardware serial number of the processing device.