Authorize using Card ID

There's no need to request your customers’ card details for every payment. Using cardId allows you to securely process their subsequent orders without having to re-enter their card number.

This endpoint creates a card payment using a card ID.

After your customer makes an initial order, Checkout.com securely stores the card information and returns to you a card ID code (cardId). This unique card ID replaces the card number in all future transactions, removing the need to exchange sensitive payment information. The cardId is useless to everyone except us!

From now on, every time your customer makes a purchase, Checkout.com only needs the cardId and their registered email address to complete the transaction. It's simple, fast, and secure!

The process for an authorization using a Card ID is detailed in the following diagram:

Click the image to zoom.

Click the image to zoom.

API: Authorizing a payment using Card ID

For a successful payment using cardId, the entered customer email address must match
Checkout.com's records. Any mismatch will cause the payment to fail.

Our API can be used on your server-side code to set up a card ID 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/card

Endpoint sandbox

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

Header parameters

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

API request example

curl https://api2.checkout.com/v2/charges/card
    -H "Authorization: sk_test_55aedccc-7f53-4ccc-b0a6-d943decc3c31"
    -H "Content-Type:application/json;charset=UTF-8"
    -X POST
    -d '{
          "autoCapTime": "24",
          "autoCapture": "Y",
          "chargeMode": 1,
          "email": "sarah.mitchell@checkout.com",
          "description": "The T-Shirt Store",
          "value": "2000",
          "currency": "USD",
          "trackId": "TRK12345",
          "transactionIndicator": "1",
          "customerIp":"96.125.185.51",
          "cardId": "card_9F2123D1-4F25-4F3D-AD68-344C01C28B59",
          "cvv": "100",
          "shippingDetails": {
            "addressLine1": "27 Acacia Tree Street",
            "addressLine2": "Apartment 15",
            "postcode": "01072",
            "country": "US",
            "city": "Shutesbury",
            "state": "Massachusetts",
            "phone": {
              "countryCode": "1",
              "number": "111 222-333"
             }
          },
          "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": "udf 1 value",
          "udf2": "udf 2 value",
          "udf3": "udf 3 value",
          "udf4": "udf 4 value",
          "udf5": "udf 5 value"
        }'
// Create payload
String cardId = "card_9F2123D1-4F25-4F3D-AD68-344C01C28B59";

CardIdCharge  cardIdChargePayload = new CardIdCharge();
cardIdChargePayload.autoCapTime=24;
cardIdChargePayload.autoCapture="Y";
cardIdChargePayload.chargeMode=1;
cardIdChargePayload.email = "testuser@email.com";
cardIdChargePayload.description = "charge description";
cardIdChargePayload.value="4298";
cardIdChargePayload.currency="usd";
cardIdChargePayload.trackId= "TRK12345";
cardIdChargePayload.transactionIndicator = "1";
cardIdChargePayload.customerIp="96.125.365.51";
cardIdChargePayload.cardId = cardId;

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

cardIdChargePayload.shippingDetails.phone = new Phone();
cardIdChargePayload.shippingDetails.phone.countryCode="44";
cardIdChargePayload.shippingDetails.phone.number = "0754617885";

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

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

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

cardIdChargePayload.udf1="udf 1 value";
cardIdChargePayload.udf2="udf 2 value";
cardIdChargePayload.udf3="udf 3 value";
cardIdChargePayload.udf4="udf 4 value";
cardIdChargePayload.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.chargeWithCardId(cardIdChargePayload);

    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

cardId
String
required

A string of characters that uniquely identifies a card associated with a customer. For example, if two customers use the same card, a different card ID is generated for each customer. (prefixed with card_)

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.
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.
Find out more.

cardToken
String
Optional

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

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. This string has a max. 100 characters.
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 max. of 10 KVP are allowed.

previousChargeId
String
Optional

Due to Visa and Mastercard requirements, this is a required field when authorizing an unscheduled merchant-initiated transaction or a digital wallet payment. Use it to reference either the previous transaction or the opening transaction of a payment series. Learn more at stored card details.

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 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, max. 100 characters.

The response

That's it! If a Payment Object returns, the payment was successful.

Received an error? Don’t worry! Even if the cardId worked in the past, there are many reasons why it might have failed now, for example, an invalid, canceled or expired card, or a valid card with insufficient funds.

By checking the status, responseMessage, and responseCode fields in the payment response, we can learn a lot about what went wrong.

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

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

Response example

{
  "id": "charge_test_405EF756CE6P7A8EBFCB",
  "liveMode": false,
  "created": "2016-06-20T16:10:13Z",
  "value": 2000,
  "currency": "USD",
  "trackId": "TRK12345",
  "description": "The T-Shirt Store",
  "email": "sarah.mitchell@checkout.com",
  "chargeMode": 1,
  "transactionIndicator": 1,
  "customerIp": "96.125.185.51",
  "responseMessage": "Approved",
  "responseAdvancedInfo": "Approved",
  "responseCode": "10000",
  "status": "Authorised",
  "authCode": "023928",
  "isCascaded": false,
  "autoCapture": "Y",
  "autoCapTime": 24,
  "card": {
    "customerId": "cust_FCC41F75-E68E-4B69-9CBD-2C7F3F80A2A3",
    "expiryMonth": "06",
    "expiryYear": "2018",
  	"billingDetails": {
    	"addressLine1": "27 Acacia Tree Street",
      "addressLine2": "Apartment 15",
      "postcode": "01072",
      "country": "US",
      "city": "Shutesbury",
      "state": "Massachusetts",
      "phone": {
      	"countryCode": "1",
      	"number": "111 222-333"
      }
    },
    "id": "card_9F2123D1-4F25-4F3D-AD68-344C01C28B59",
    "last4": "4242",
    "bin": "424242",  
    "paymentMethod": "Visa",
    "fingerprint": "F639CAB2745BEE4140BF86DF6B6D6E255C5945AAC3788D923FA047EA4C208622",
    "name": "Sarah Mitchell",
    "cvvCheck": "Y",
    "avsCheck": "S"
  },
  "riskCheck": true,
  "customerPaymentPlans": null,
  "metadata": {
    "key1": "value1"
  },
  "shippingDetails": {
    "addressLine1": "27 Acacia Tree Street",
    "addressLine2": "Apartment 15",
    "postcode": "01072",
    "country": "US",
    "city": "Shutesbury",
    "state": "Massachusetts",
    "phone": {
      "countryCode": "1",
      "number": "111 222-333"
    }
  },
  "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": "udf 1 value",
  "udf2": "udf 2 value",
  "udf3": "udf 3 value",
  "udf4": "udf 4 value",
  "udf5": "udf 5 value"
}

Can we help?

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