Void a payment

After authorizing a card payment, the actual transaction is not complete until it has been captured. Capture time depends on the merchant's settings,—but assuming it is not instant—then it is possible to void a transaction either in The Hub or using the following API request.

This endpoint voids an authorized, but not yet captured, card payment.

API: Voiding a payment

Our Void API request can be used on your server-side code to set up a payment request. New to our APIs? Read our API quickstart first!

The request

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}/void

Endpoint sandbox

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

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_.

API request example

curl https://api2.checkout.com/v2/charges/charge_F2B8BA4C175P76BD3E07/void
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X POST
    -d '{
          "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";

ChargeVoid chargeVoidPayload =new ChargeVoid();
chargeVoidPayload.trackId = "TRK12345";
chargeVoidPayload.description =  "Sample product";

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

chargeVoidPayload.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";
chargeVoidPayload.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<Void> apiResponse = ckoAPIClient.chargeService.voidCharge(chargeId,chargeVoidPayload);

    if(!apiResponse.hasError){
        // Access the response object retrieved from the api
        Void chargeVoid = 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

FieldName
Description

description
String
Optional

The description of the payment action.

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

The order tracking ID generated by the merchant.

Maximum length 50 characters.

udf1 to udf5
String
Optional

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

The response

You’re all done! Congrats! A successful void request returns a void payment response — we've provided an example of one below.

Be sure to contact our support team if you run into any problems.

The id is the unique identifier of the transaction and the originalId is the id of the parent transaction (for example, in a captured transaction, the originalId will be the id of the original authorised transaction).

Response example

{
  "id": "charge_test_CC4A596E242G73BD0AF7",
  "originalId": "charge_test_9F5A696E242S73BD0AF4",
  "liveMode": false,
  "created": "2018-03-22T18:02:12Z",
  "value": 2000,
  "currency": "USD",
  "trackId": "TRK12345",
  "description": "The T-Shirt Store",
  "chargeMode": 1,
  "responseMessage": "Approved",
  "responseAdvancedInfo": "Approved",
  "responseCode": "10000",
  "status": "Voided",
  "metadata": null,
  "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"
}

Can we help?

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


Find out more

Refund a payment