Void

Overview

This page will show you how to void a transaction. Once a transaction has been voided, it will not show up on the customer's credit card statement. Customers who have online banking that allows them to see "Pending" transactions may see the voided transaction for a few days before it disappears.

You can only void a transaction that hasn't been settled yet. A transaction is settled when the batch that it is in has been closed. If the transaction has been settled, you must run a credit instead using a refund transaction. If you run a credit, both the credit and the initial charge will show up on the customer's credit card statement. (See the refund method for more details.)

The API endpoint is as follows:

POST /api/v2/transactions

Quick Start

Request

curl -X POST https://sandbox.usaepay.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "void",
    "refnum": "124444201"
}'

This cURL request is an example of how to perform a void.

Response

{  
   "type":"transaction",
   "key":"bnfkqy54w4qwtmq",
   "refnum":"21725793",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"000973"
}

This is the sample response object sent back from the server.

After a void is successfully sent to the server via this REST API call, the specified transaction will show as voided.

Request Parameters

This is a complete overview of the request parameters that are sent. Note that each command type may only accept a subset of the parameters.

Parameter Name	Type	Description
Command	string	This specified the type of transaction to run. Look here for the list of supported commands.
refnum	string	This is the 8-digit transaction id of the sale you wish to void
amount	string/double	This is an optional quantity for creditvoid, which will allow for the partial refund of a transaction. Note: The request will fail if the refund amount exceeds the transaction amount.

Response Variables

Variable	Type	Description
type	string	The type of sale performed. Successful sales return a value of 'transaction'.
key	string	Unique key for the transaction record
refnum	string	Transaction reference number
is_duplicate	bool	If Y, a duplicate transaction was detected. The system is showing the response from the original transaction, rather than running a duplicate.
result_code	string	Result code ('A' = Approved, 'P' = Partial Approval, 'D' = Declined, 'E' = Error or 'V' = Verification Required)
result	string	Long version of above result_code ('Approved', etc.)
authcode	integer	Authorization code

Sample Code

List of available void commands

| Void | Credit Card Void Release | Unvoid | Credit Void | |--|--|--|--|--|--| | void | cc:void:release | unvoid | creditvoid |

Void

To void a transaction:

curl -X POST https://sandbox.usaepay.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "void",
    "refnum": "124444201"
}'

This cURL request is an example of a merchant who is trying to void a transaction.

{  
   "type":"transaction",
   "key":"bnfkqy54w4qwtmq",
   "refnum":"21725793",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"000973"
}

This is the sample response object sent back from the server.

Credit Card Void Release

To void a transaction and release funds:

curl -X POST https://sandbox.usaepay.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
  '{
    "command": "cc:void:release",
    "refnum" : "21726107"
}'

This cURL request is an example of a merchant who is trying to void a credit card transaction and release funds.

{  
   "type":"transaction",
   "key":"dnft1yqgm9rh6b0",
   "refnum":"21726107",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"001788"
}

This is the sample response object sent back from the server.

Unvoid

Unvoids a previously voided transaction:

curl -X POST https://sandbox.usaepay.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "unvoid",
    "refnum": "124444201"
}'

This cURL request is an example of a merchant who is trying to unvoid a transaction.

{
   "type":"transaction",
   "key":"bnfkqy54w4qwtmq",
   "refnum":"21725793",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"000973"
}

This is the sample response object sent back from the server.

Credit Void

This allows you to void or credit back a transaction. The command automatically checks the status of the transaction, if the transaction has been settled then a credit (for all or part of the initial transaction) is entered into the current batch. If the transaction has not been settled then it will be voided. Has an optional amount field which must be equal to or less than the original transaction. If no amount is specified, the full amount will be refunded.

curl -X POST https://sandbox.usaepay.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
  '{
    "command": "creditvoid",
    "refnum" : "21725595"
    }'

This cURL request is an example of a merchant who is trying to perform a creditvoid.

{  
   "type":"transaction",
   "key":"cnfy6dkxccp2xkd",
   "refnum":"21726496",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"726496",
   "avs":{  
      "result_code":"   ",
      "result":"Unmapped AVS response (   )"
   },
   "batch":{  
      "type":"batch",
      "key":"0t1mf43qwmcsgb3",
      "sequence":"2"
   }
}

This is the sample response object sent back from the server.

Common Errors

Voiding a tranasaction that already has been voided

If you attempt to void a transaction that has already been voided, you will get the following response.

{  
   "type":"transaction",
   "key":"",
   "refnum":"",
   "is_duplicate":"N",
   "result_code":"E",
   "result":"Error",
   "error":"Transaction already voided.",
   "error_code":"24"
}

Change Log

Date	Change
2017-11-29	Added page.
2018-03-14	Corrected transid to refnum.

Click here for the full REST API change log.