Capture a payment

Checkout.com's two-step authorization and capture process enables a merchant to capture payments either automatically or manually. When a payment is authorized, the funds are held on the customer's card for seven days. With auto-capture disabled, a merchant can either capture a payment directly from The Hub or by using this API. The transaction is canceled if the merchant doesn't capture the authorization within seven days. Authorized payments can be captured either in full or partially.

Looking to cancel a payment?

You can cancel an authorized payment at any time by voiding it. However, captured payments can only be refunded.

API: Capturing a payment

Our manual capture API can be used on your server-side code to capture a payment.

This endpoint manually captures an authorized card payment either in full or partially. Any capture amount less than the original transaction will be treated as a partial capture.

If a payment is created with autoCapture set to 'n', you must either use this endpoint to capture the payment or capture it from The Hub. Manual capture is not allowed if autoCapture is set to y.

The request

Capture a payment by sending a POST API request to the URI below. In the URI, replace {chargeId} with the chargeId of the authorized transaction, however, first add the prefix charge_ or charge_test_ to your ID.

Endpoint live

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

Endpoint sandbox

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

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_88EDAABC175O76BD3E88/capture
    -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",
          "metadata": {
            "product": "T-Shirt"
          },
          "products": [
             {
               "description": "T-Shirt ladies medium",
               "image": null,
               "name": "T-Shirt ladies",
               "price": 2000,
               "quantity": 1,
               "shippingCost": 0,
               "sku": "tee123",
               "trackingUrl": "https://www.tracker.com"
            }
          ],
          "udf1": "test udf 1",
          "udf2": "test udf 2",
          "udf3": "test udf 3",
          "udf4": "test udf 4",
          "udf5": "test udf 5"
        }'
// Create payload
String chargeId = "charge_88EDAABC175O76BD3E88";

ChargeCapture chargeCapturePayload =new ChargeCapture();
cardChargePayload.value = "3880";
chargeCapturePayload.trackId = "TRK12345";
chargeCapturePayload.description = "capture description";

chargeCapturePayload.metadata = new HashMap<String,String>();
chargeCapturePayload.metadata.put("product", "ipad 2");

chargeCapturePayload.products = new ArrayList<Product>();
Product product1 =new Product();
product1.description= "Tablet 1 gold limited";
product1.name="Tablet 1 gold limited";
product1.price=100.0;
product1.quantity=1;
product1.shippingCost=10.0;
product1.sku= "1aab2aa";
product1.trackingUrl="https://www.tracker.com";
chargeCapturePayload.products.add(product1);

chargeCapturePayload.udf1= "test udf 1";
chargeCapturePayload.udf2= "test udf 2";
chargeCapturePayload.udf3= "test udf 3";
chargeCapturePayload.udf4= "test udf 4";
chargeCapturePayload.udf5= "test udf 5";

 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<Capture> apiResponse = ckoAPIClient.chargeService.captureCharge(chargeId,chargeCapturePayload);

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

Field name
Description

description
String
Optional

A description string of the payment capture.

metadata
Hash
Optional

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

Max 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 string generated by the merchant.
Max length 50 characters.

udf1 to udf5
String
Optional

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

value
Integer
Optional

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

Cannot exceed the authorized payment amount. Partial captures (amounts less than the authorized amount) are permitted. Only one partial capture is allowed per authorized payment. If not specified, the default is the authorization payment amount.


The response

If a capture payment response object returns, then your capture was successful. That's great! If you're having problems with this API, then speak to our support team for help.

Take a look at the example response below.

Response example

{
    "id": "charge_test_8F3A796E242G73BD0AC3",
    "originalId": "charge_test_BE5FE99E242R73BD0AD7",
    "liveMode": false,
    "created": "2018-03-22T18:00:25Z",
    "value": 2000,
    "currency": "USD",
    "trackId": "TRK12345",
    "description": "The T-Shirt Store",
    "chargeMode": 1,
    "responseMessage": "Approved",
    "responseAdvancedInfo": "Approved",
    "responseCode": "10000",
    "status": "Captured",
    "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.tracker.com"
        }
    ],
    "udf1": "test udf 1",
    "udf2": "test udf 2",
    "udf3": "test udf 3",
    "udf4": "test udf 4",
    "udf5": "test udf 5"
}

Configuring auto capture

Checkout.com’s payment object contains two fields for configuring authorize and capture settings.

autoCapture

  • Set to y to authorize a payment and automatically capture it after a specified time period.
  • Set to n to authorize a payment and manually capture it using our Capture a payment API or The Hub.

autoCapTime

  • If autoCapture = y, autoCapTime will define the number of hours (0-168) between the payment authorization and automatic capture. Set to autoCapTime ='0' to authorize and capture a payment at the same time.

Can we help?

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

Capture a payment