Support

Recent Posts

Archive

Tags

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.

API: Authorizing a payment using Card ID

For a successful payment using cardId, the entered customer email address must matchCheckout.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.

Additional parameters

Request payload fields

cardIdStringrequired

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

currencyStringrequired

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

emailorcustomerIdStringrequired

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.

valueIntegerrequired

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

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.

billingDetailsHashOptional

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.

cardTokenStringOptional

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

chargeModeIntegerOptional, default value is 1.

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

customerIpStringOptional, default value is null.

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

customerNameStringOptional

The name of the customer. This string has a max. 100 characters.Does not update the name of an existing customer.

descriptionStringOptional, default value is null.

A description of the payment.

failUrlStringOptional

Specify the fail redirect URL

metadataHashOptional, 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.

previousChargeIdStringOptional

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.

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

Maximum characters: 50.

transactionIndicatorStringOptional, default value is 1.

Type of transaction.1 for regular2 for recurring3 for MOTO

udf1 to udf5StringOptional, 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