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.