Refund

Overview

This page will show you how to initiate a refund. A refund should be used once the transaction you are refunding has settled. If you are trying to cancel a transaction that is still in the currently open batch, you should void the transaction instead. By default, this endpoint will perform a full refund on a given transaction. However, partial refunds are possible by including the optional amount parameter field.

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": "refund",
    "refnum": "124444201"
}'

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

Response

{
  "type": "transaction",
  "key": "2nf57pywqh09zjs",
  "refnum": "124445986",
  "is_duplicate": "N",
  "result_code": "A",
  "result": "Approved",
  "authcode": "445986",
  "avs": {
    "result_code": "   ",
    "result": "Unmapped AVS response (   )"
  },
  "batch": {
    "type": "batch",
    "key": "0t1k3yx5xs37cvb",
    "sequence": "1"
  }
}

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

After a refund is successfully sent to the server via this REST API call, the current batch will show an entry which reverses the specified transaction (in part or in full).

Post Refund Batch Screen

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 refund
amount	string/double	This is an optional quantity, 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	integer	Unique key for the transaction record
refnum	string	Transaction reference number
is_duplicate	char(Y/N)	If Y, a duplicate transaction was detected. The system is showing the response from the original transaction, rather than running a duplicate.
result_code	char	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
avs	object	Object which contains the verification status of the AVS response system
batch	object	Object which contains the batch details which the transaction belongs to.

Sample Code

List of available refund commands

Quick Refund	Refund	Credit Card	Check	Cash	Check Credit
quickrefund	refund	cc:refund	check:refund	cash:refund	check:credit

Quick Refund

A refund amount is required for quick refund. To make a quick refund:

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

This cURL request is an example of a merchant who is trying to refund a sale.

{  
   "type":"transaction",
   "key":"jnfwh1pbb9dd8xb",
   "refnum":"21726009",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"21736032",
   "avs":{  
      "result_code":"   ",
      "result":"Unmapped AVS response (   )"
   },
   "batch":{  
      "type":"batch",
      "key":"0t1hkmb63g4h968",
      "sequence":"2"
   }
}

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

Refund

To make a refund:

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

This cURL request is an example of a merchant who is trying to refund a sale.

{  
   "type":"transaction",
   "key":"mnfky8sgsdyyh6h",
   "refnum":"21726012",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"726012",
   "avs":{  
      "result_code":"   ",
      "result":"Unmapped AVS response (   )"
   },
   "batch":{  
      "type":"batch",
      "key":"0t1hkmb63g4h968",
      "sequence":"2"
   }
}

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

Credit Card Refund

To make a credit card refund:

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

This cURL request is an example of a merchant who is trying to refund a credit card sale.

{  
   "type":"transaction",
   "key":"pnfkgynn0jx82ts",
   "refnum":"21726015",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"726015",
   "avs":{  
      "result_code":"   ",
      "result":"Unmapped AVS response (   )"
   },
   "batch":{  
      "type":"batch",
      "key":"0t1hkmb63g4h968",
      "sequence":"2"
   }
}

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

Check Refund

To refund a check:

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

This cURL request is an example of a merchant who is trying to refund a check.

{  
   "type":"transaction",
   "key":"6nfj34qh3n8qbhw",
   "refnum":"21726542",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"TM5CA5",
   "proc_refnum":"17092106017626"
}

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

Cash Refund

Performs a cash refund. Requires an amount field, while the refnum field is not supported. Also accepts optional fields creditcard or check for providing additional details.

curl -X POST https://sandbox.usaepay.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
  '{
    "command": "cash:refund",
    "creditcard": {
        "cardholder": "John Doe",
        "number": "4000100011112224",
        "expiration": "0919",
        "cvc": "123",
        "avs_street": "1234 Main",
        "avs_zip": "12345"
    },
    "amount" : "5.00"
}'

This cURL request is an example of a merchant who is trying to refund using cash.

{  
   "type":"transaction",
   "key":"0nfkxj95sv47xqs",
   "refnum":"21726510",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"",
   "creditcard":{  
      "number":"4000xxxxxxxx2224"
   }
}

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

Check Credit

Performs a check credit. This uses ACH to send funds to a customer, employee, vendor, etc. It can be used to refund a sale or make a payment to someone (ie payroll). This transaction type is “stand alone” and does not pull the account and routing number from a previous sale. You must provide check information to use this.


curl -X POST https://sandbox.usaepay.com/api/v2/transactions
  -H "Content-Type: application/json"
  -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
  -d
  '{
    "command": "check:credit",
    "check": {
        "accountholder": "John Doe",
        "account": "324523524",
        "routing": "123456789"
    },
    "amount" : "5.00"
    }
}'

This cURL request is an example of a merchant who is trying to send a check credit.

{  
   "type":"transaction",
   "key":"6nfj34qh3n8qbhw",
   "refnum":"21726542",
   "is_duplicate":"N",
   "result_code":"A",
   "result":"Approved",
   "authcode":"TM5CA5",
   "proc_refnum":"17092106017626"
}

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

Common Errors

Refunding more than transaction amount

If you attempt to refund a larger amount than was charged, you will get the following response.

{
  "type": "transaction",
  "key": "",
  "refnum": "",
  "is_duplicate": "N",
  "result_code": "E",
  "result": "Error",
  "error": "Amount exceeds original transaction amount.",
  "error_code": "10133",
  "batch": {
    "type": "batch",
    "key": "0t1nqryfrcnsktb",
    "sequence": "2"
  }
}

Change Log

Date	Change
2017-08-01	Added page.
2018-03-14	Corrected `transid` to `refnum`.

Click here for the full REST API change log.