2Checkout Documentation

Refund Invoice

The refund_invoice call is used to attempt to issue a full or partial refund on an invoice. This call will send the REFUND_ISSUED INS message.



Input Parameters

Parameter Description
sale_id Order number/sale ID to issue a refund on. Optional when invoice_id is specified, otherwise required.
invoice_id Invoice ID to issue a refund on. Optional when sale_id is specified and sale only has 1 invoice.
amount The amount to refund. Only needed when issuing a partial refund. If an amount is not specified, the remaining amount for the invoice is assumed.
currency Currency type of refund amount. Can be ‘usd’, ‘vendor’ or ‘customer’. Only required if amount is used.
comment Message explaining why the refund was issued. Required. May not contain ‘<’ or ‘>’. (5000 character max)
category ID representing the reason the refund was issued. Required. (values: 1-17 from the following list can be used except for 7 as it is for internal use only)
ID Description
1 Did not receive order
2 Did not like item
3 Item(s) not as described
4 Fraud
5 Other
6 Item not available
7 Do Not Use (Internal use only)
8 No response from merchant
9 Recurring last installment
10 Cancellation
11 Billed in error
12 Prohibited product
13 Service refunded at merchants request
14 Non delivery
15 Not as described
16 Out of stock
17 Duplicate

Data Returned

Parameter Description
response_code Tells the user whether or not the operation was successful
response_message Tells the user why the operation was or was not successful

Example API Call


$args = array(
    'sale_id' => 4753371371,
    'category' => 1,
    'comment' => 'Order never sent.'

try {
    $result = Twocheckout_Sale::refund($args);
} catch (Twocheckout_Error $e) {
Twocheckout::API.credentials = {
  :username => 'APIuser1817037',
  :password => 'APIpass1817037'

  sale = Twocheckout::Sale.find(:sale_id => 4786293822)
  invoice = sale.invoices.first
  invoice.refund!({:comment => "test refund", :category => 1})
  result = sale.reauth
rescue Twocheckout::TwocheckoutError => e
  puts e.message
var tco = new Twocheckout({
    apiUser: "APIuser1817037",
    apiPass: "APIpass1817037"

args = {
    sale_id: "4774380224",
    comment: "test",
    category: "5"

tco.sales.refund(args, function (error, data) {
    if (error) {
    } else {
    'username': APIuser1817037',
    'password': 'APIpass1817037'

params = {
    'sale_id': 4834917619,
    'category': 1,
    'comment': "Refunding Sale"

    sale = twocheckout.Sale.find(params)
    invoice = sale.invoices[0]
    result = invoice.refund(params)
except TwocheckoutError as error:
    print error.message
TwoCheckoutConfig.ApiUsername = "APIuser1817037";
TwoCheckoutConfig.ApiPassword = "APIpass1817037";

    var ServiceObject = new SaleService();
    var ArgsObject = new SaleRefundServiceOptions();
    ArgsObject.invoice_id = invoice_id;
    ArgsObject.comment = "test refund";
    ArgsObject.category = 5;

    var result = ServiceObject.Refund(ArgsObject);
catch (TwoCheckoutException e)
TwoCheckoutConfig.ApiUsername = "APIuser1817037";
TwoCheckoutConfig.ApiPassword = "APIpass1817037";

HashMap params = new HashMap();
params.put("comment", "test");
params.put("category", "1");

try {
    Sale sale = TwocheckoutSale.retrieve("4774380224");
    TwocheckoutResponse result = sale.refund(params);
} catch (TwocheckoutException e) {
    String message = e.toString();
curl -X POST \
    -u 'username:password' -d 'sale_id=1234567890' -d 'amount=1.00' \
    -d 'currency=true' -d 'category=13' -H 'Accept: application/json' \
    -d 'comment=Buyer deserved a refund.'

Example Successful Response

       "response_code" : "OK",
       "response_message" : "refund added to invoice"

Common Error Codes

Code Description
PARAMETER_MISSING Required parameter missing:
PARAMETER_INVALID Invalid value for parameter:
RECORD_NOT_FOUND Unable to find record.
FORBIDDEN Access denied to sale.

Method-Specific Error Codes

Code Description
FORBIDDEN Permission denied to set refund category to 7.
FORBIDDEN Access denied to invoice.
AMBIGUOUS Ambiguous request. Multiple invoices on sale. invoice_id parameter required.
TOO_LOW Amount must be at least 0.01.
NOTHING_TO_DO Invoice was already refunded.
TOO_HIGH Amount greater than remaining balance on invoice.
TOO_LATE Invoice too old to refund. (Will occur if sale is over 180 days)