Authorize a payment

Once you've successfully set-up one of our integration methods, you're able to start receiving and tokenizing - tokenizing - Tokenization is the industry standard process for protecting sensitive data by replacing it with an algorithmically generated number called a token. At Checkout.com we use tokenization to protect our customers' confidential payment information from fraudsters. Payment information is substituted with randomly generated numbers — the tokens — and passed to us over the internet. Using the token, we can locate the payment details from our secure vault and complete the request without the need to transfer any sensitive data. your customers' card details. After this tokenization process, you're ready to create a payment. To do this, you can use Checkout.com's API and your server-side code.

Please note:

This page covers the initial steps of creating a payment using a card token. For other methods of collecting payments, please see Payments with card ID or Payments with default card.

The process for a payment authorization is detailed in the following diagram:

Click on the image to zoom.

Click on the image to zoom.

API: Authorizing a payment

First, you need to create a new payment request using any of our Integration options. Then, on your server, collect the newly generated card token and use this authorizing a payment API to create a payment. Act fast, because card tokens are single use and only have a 15-minute lifespan.

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/token

Endpoint sandbox

https://sandbox.checkout.com/api2/v2/charges/token

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

Request example

This code snippet is an example of the request body, not all fields are required, so you can custom build your request based on the information you need. The table additional parameters lists all required and optional parameters.

curl https://sandbox.checkout.com/api2/v2/charges/token
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X POST
    -d '{
    			"autoCapTime": "24",
    			"autoCapture": "Y",
    			"email": "sarah.mitchell@checkout.com",
    			"value": "2000",
    			"currency": "USD",
    			"trackId": "TRK12345",
    			"cardToken": "card_tok_9EDE49BB-306D-41FF-842D-3FF32A52CC25"
   }
      }'
// Create payload
String cardToken = "card_tok_CB9C10E3-24CC-4A82-B50A-4DEFDCB15580";

CardTokenCharge cardTokenChargePayload = new CardTokenCharge();
cardTokenChargePayload.autoCapTime=24;
cardTokenChargePayload.autoCapture="Y";
cardTokenChargePayload.chargeMode=1;
cardTokenChargePayload.email = "testuser@email.com";
cardTokenChargePayload.description = "charge description";
cardTokenChargePayload.value="4298";
cardTokenChargePayload.currency="GBP";
cardTokenChargePayload.trackId= "TRK12345";
cardTokenChargePayload.transactionIndicator = "1";
cardTokenChargePayload.customerIp= "96.125.185.51";
cardTokenChargePayload.cardToken = cardToken;

cardTokenChargePayload.shippingDetails = new Address();
cardTokenChargePayload.shippingDetails.addressLine1 = "623 Slade Street";
cardTokenChargePayload.shippingDetails.addressLine2 = "Flat 9";
cardTokenChargePayload.shippingDetails.postcode = "E149SR";
cardTokenChargePayload.shippingDetails.country = "UK";
cardTokenChargePayload.shippingDetails.city =  "London";
cardTokenChargePayload.shippingDetails.state = "Greater London";

cardTokenChargePayload.shippingDetails.phone = new Phone();
cardTokenChargePayload.shippingDetails.phone.countryCode="44";
cardTokenChargePayload.shippingDetails.phone.number = "12345678";

cardTokenChargePayload.billingDetails = new Address();
cardTokenChargePayload.billingDetails.addressLine1 = "75-77 Margaret Street";
cardTokenChargePayload.billingDetails.addressLine2 = null;
cardTokenChargePayload.billingDetails.postcode = "W1W 8SY";
cardTokenChargePayload.billingDetails.country = null;
cardTokenChargePayload.billingDetails.city =  "London";
cardTokenChargePayload.billingDetails.state = "null";

cardTokenChargePayload.billingDetails.phone = new Phone();
cardTokenChargePayload.billingDetails.phone.countryCode="44";
cardTokenChargePayload.billingDetails.phone.number = "999 999 9999";

cardTokenChargePayload.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";

Product product2  =new Product();
product2.description= "Tablet 2 gold limited";
product2.name="Tablet 2 gold limited";
product1.price=200.0;
product2.quantity=2;
product2.shippingCost=10.0;
product2.sku= "1aab2aa";
product2.trackingUrl="https://www.tracker.com";

cardTokenChargePayload.products.add(product1);
cardTokenChargePayload.products.add(product2);

cardTokenChargePayload.metadata = new HashMap<String,String>();
cardTokenChargePayload.metadata.put("key1", "value1");

cardTokenChargePayload.udf1="udf 1 value";
cardTokenChargePayload.udf2="udf 2 value";
cardTokenChargePayload.udf3="udf 3 value";
cardTokenChargePayload.udf4="udf 4 value";
cardTokenChargePayload.udf5="udf 5 value";

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<Charge> apiResponse = ckoAPIClient.chargeService.chargeWithCardToken(cardTokenChargePayload);

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

Request payload fields

cardToken
String
required

A valid card token, with the prefix card_tok_.
A cardToken can only be used once and will expire after 15 minutes.

currency
String
required

Three-letter ISO currency code representing the currency of the payment.

email or customerId
String
required

The email address or customer ID of the customer associated with the card ID.

If charging an existing customer, the email specified in the payment must match the email associated with them.

value
Integer
required

The value of the payment as a non-zero positive integer (no decimals).
Find out more

autoCapture
String
Optional, enabled by default.

If enabled, it automatically captures the payment following the autoCapTime period.
y = enable | n = disable
Authorized payments automatically expire after seven days (168 hours).

autoCapTime
Decimal
Optional, required if autoCapture is enabled.

Set the delayed capture time in hours. Use values 0 to 168 (0 to 7 days).

For more precise timings, use decimals: eg., 0.5 = 30 mins.

billingDetails
Hash
Optional

Billing address information.

Find out more. If the billing details parameter is omitted from the request, it will be assumed that the billing address is the same as the shipping address.

chargeMode
Integer
Optional, default value is 1.

Defines the Charge Mode.
1 = Non-3D | 2 = 3D

customerIp
String
Optional, default value is null.

Customer's IP address (e.g., 96.125.185.52)

customerName
String
Optional

The name of the customer. Maximum characters: 100.

Does not update the name of an existing customer.

description
String
Optional, default value is null.

A description of the payment.

failUrl
String
Optional

Specify the fail redirect URL

metadata
Hash
Optional, default value is {} .

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

Maximum length of keys and values is 100 each. A maximum of 10 KVP are allowed.

products
Array
Optional

An array of Product information.
Find out more

recipientDetails
Hash
Optional

Utilized only by financial institutions, this parameter enters the additional recipient details requested by Visa and Mastercard for domestic UK transactions.
Find out more

riskCheck
Boolean
Optional, default value is true.

If set to false, it allows the merchant to bypass all risk checks configured on the system (including blacklist).

The ability to set riskCheck is not available by default.

shippingDetails
Hash
Optional, default value is null.

Shipping address information.
Find out more.

successUrl
String
Optional

Specify the success redirect URL.

trackId
String
Optional, default value is null.

Recommended
Make tracking easy; assign a unique track-id to your payments.

A unique ID set by the merchant. The track ID remains the same throughout the lifetime of the payment. Maximum characters: 50.

transactionIndicator
String
Optional, default value is 1.

Type of transaction.
1 for regular
2 for recurring
3 for MOTO

udf1 to udf5
String
Optional, default value is null.

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

The response

Done! If a payment response object returns, you just charged a card.

If you received an error? Don’t fret! Let's try and figure out what went wrong in Understanding the response.

Successful authorization requests will return a message with either a 10000 response code or a 10100 response code for flagged transactions.

Response example

The possible values for the status field include Authorised, Captured, Declined, and Flagged.

{
    "id": "charge_test_BE2F499E242J73BD0AB8",
    "liveMode": false,
    "created": "2018-03-22T17:53:34Z",
    "value": 2000,
    "currency": "USD",
    "trackId": "TRK12345",
    "description": null,
    "email": "sarah.mitchell@checkout.com",
    "chargeMode": 1,
    "transactionIndicator": 1,
    "customerIp": null,
    "responseMessage": "Approved",
    "responseAdvancedInfo": "Approved",
    "responseCode": "10000",
    "status": "Authorised",
    "authCode": "541977",
    "isCascaded": false,
    "autoCapture": "Y",
    "autoCapTime": 24,
    "card": {
        "customerId": "cust_597C3BDE-E266-4B5C-B9D4-9D5115341B3F",
        "expiryMonth": "06",
        "expiryYear": "2018",
        "billingDetails": {
            "addressLine1": "27 Acacia Tree Street",
            "addressLine2": null,
            "postcode": "01072",
            "country": "US",
            "city": "Massachusetts",
            "state": null,
            "phone": {
                "countryCode": "1",
                "number": "111 222-333"
            }
        },
        "id": "card_C00F69AC-D2FD-4083-88C0-9E30BF225161",
        "last4": "4242",
        "bin": "424242",
        "paymentMethod": "Visa",
        "fingerprint": "F639CAB2745BEE4140BF86DF6B6D6E255C5945AAC3788D923FA047EA4C208622",
        "name": "Sarah Mitchell",
        "cvvCheck": "Y",
        "avsCheck": "S"
    },
    "riskCheck": true,
    "customerPaymentPlans": null,
    "metadata": {},
    "shippingDetails": {
        "addressLine1": null,
        "addressLine2": null,
        "postcode": null,
        "country": null,
        "city": null,
        "state": null,
        "phone": {}
    },
    "products": [],
    "udf1": null,
    "udf2": null,
    "udf3": null,
    "udf4": null,
    "udf5": null
}

Understanding the response

By looking at the status, responseMessage and responseCode fields in the payment response you can find out why the payment has not gone through. It's possible the payment has an invalid or expired card or a valid card with an insufficient available balance.

The following pages can be used as references when understanding the response message:

Notable elements in the response

Whereas all information within the response is useful, there are some particular elements that are especially noteworthy.

Can we help?

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

Authorize a payment