Refund a payment

Use a refund to return a payment to a customer; either partially or in full.

There are two types of refunds you might need to process:

  • Full refund
    A full refund returns the total amount of the transaction to the customer — it can only be performed once.
  • Partial refund
    A partial refund returns a sum less than the captured amount. A payment can be refunded multiple times, but cannot exceed the original payment amount.

API: Refunding a payment

Refunds can be made in The Hub or by using this API endpoint . Once processed, it is not possible to cancel a refund.

To process a refund successfully, the merchant must send the payment ID of the captured transaction in the API. You can find the transaction' ID:

  • In the response to the Payment request
  • By querying the payment history
  • From the Webhook notification

For both full and partial refunds, the requests are the same. Any refunds for less than the original captured amount will be considered partial refunds.

Please note:

For payments with an automatic capture, the payment response will contain the ID of the authorization. This ID cannot be used for refunds.

The request

Refund requests are created using a POST request. Use the details below to set up your request.

Endpoint live

https://api2.checkout.com/v2/charges/{chargeId}/refund

Endpoint sandbox

https://sandbox.checkout.com/api2/v2/charges/{chargeId}/refund

Header and path parameters

Header
Value

Authorization
Required

secret key*

Content-Type
Required

application/json

*For authorization, use the valid secret key of your Checkout.com account. You can find this in The Hub.

Path
Value

chargeId
Required

The charge ID, embedded within the URI, prefixed with charge_ or charge_test_.

Request example

curl https://api2.checkout.com/v2/charges/charge_F2B8BA4C175P76BD3E07/refund
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X POST
    -d '{
          "value": "2000",
          "trackId": "TRK12345",
          "description": "The T-Shirt Store",
          "products": [
             {
               "description": "T-Shirt ladies medium",
               "image": null,
               "name": "T-Shirt ladies",
               "price": 2000,
               "quantity": 1,
               "shippingCost": 0,
               "sku": "tee123",
               "trackingUrl": "https://www.example.com"
            }
          ],
          "udf1": "null",
          "udf2": "null",
          "udf3": "null",
          "udf4": "null",
          "udf5": "null"
        }'
// Create payload
String chargeId = "charge_F2B8BA4C175P76BD3E07";

ChargeRefund refundPayload =new ChargeRefund();
refundPayload.value = "100";
refundPayload.trackId = "TRK12345";
refundPayload.description =  "Sample product";

refundPayload.metadata = new HashMap<String,String>();
refundPayload.metadata.put("testKey", "value");

refundPayload.products = new ArrayList<Product>();
Product product1 =new Product();
product1.description= "Tablet 2 gold limited";
product1.name="Tablet 32gb cellular";
product1.price=90.0;
product1.quantity=1;
product1.shippingCost=10.0;
product1.sku= "1aab";
product1.trackingUrl="https://www.tracker.com";
refundPayload.products.add(product1);

 try {
    // Create APIClient instance with your secret key
    APIClient ckoAPIClient= new APIClient("sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31",Environment.LIVE);
    // Submit your request and receive an apiResponse
    Response<Refund> apiResponse = ckoAPIClient.chargeService.refundRequest(chargeId,refundPayload);

    if(!apiResponse.hasError){
        // Access the response object retrieved from the api
        Refund refund = apiResponse.model;
    } else {
        // Api has returned an error object. You can access the details in the error property of the apiResponse.
        // apiResponse.error
    }
} catch (Exception e) {}

Additional parameters

Parameter
Description

description
String
Optional

A description of the refund.

metadata
Hash
Optional

A hash of FieldName and value pairs e.g. {'keys1': 'Value1'}.

Maximum length of key(s) and value(s) is 100 each. A max. of 10 KVP are allowed.

products
Array
Optional

An array of product information.
Find out more

trackId
String
Optional

An order tracking ID generated by the merchant.
Maximum length: 50 characters.

udf1 to udf5
String
Optional

User-defined fields 1 to 5, max.
Maximum length: 100 characters.

value
Integer
Optional

Positive integer (without decimal separator) representing the refund amount.

Cannot be greater than the original capture amount. Multiple refunds up to the original capture amount are allowed. Defaults to the captured amount if not specified.

The response

A successful refund will return a refund charge response object. If you received that, nice one!

If something went wrong, don't despair! Read our troubleshooting section.

Response example

{
  "id": "charge_test_8C5A496E242M73BD0AE1",
  "originalId": "charge_test_8F3A796E242G73BD0AC3",
  "liveMode": false,
  "created": "2018-03-22T18:03:13Z",
  "value": 2000,
  "currency": "USD",
  "trackId": "TRK12345",
  "description": "The T-Shirt Store",
  "chargeMode": 1,
  "responseMessage": "Approved",
  "responseAdvancedInfo": "Approved",
  "responseCode": "10000",
  "status": "Refunded",
  "hasChargeback": "N",
  "metadata": {
    "product": "T-Shirt"
  },
  "products": [
    {
      "name": "T-Shirt ladies",
      "description": "T-Shirt ladies medium",
      "sku": "tee123",
      "price": 2000,
      "quantity": 1,
      "image": null,
      "shippingCost": 0,
      "trackingUrl": "https://www.example.com"
    }
  ],
  "udf1": "null",
  "udf2": "null",
  "udf3": "null",
  "udf4": "null",
  "udf5": "null"
}

Troubleshooting

Let's take a look at what might have happened — this checklist might help to identify the problem:

  • Is the refund amount higher than the original payment?
  • Has the payment already been refunded?
  • Did you send the Auth ID instead of the Payment ID?

Still having problems? Contact our support team for help.

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at support@checkout.com.