Tokenized Card

What is a Tokenized Card?

A tokenized card is a secure digital representation of a payment card, where sensitive card details are replaced with a unique, non-sensitive token for safe transactions. While a tokenized card can be used as part of a backend integration workflow in Ecart Pay, its usage depends on a merchant's specific needs, and is therefore not strictly required for all cases.

Tokenized Cards are useful to configure Interest-free and Fixed Installments options before creating an order through your backend.

Card Validation Process

To ensure the validity and liquidity of a card before tokenization, our API performs a temporary validation process. This security measure verifies that the card is active and has sufficient funds.

How it Works

When you request to permanently tokenize a card (by setting tokenization: true), the following workflow is automatically triggered:

1. Validation Hold (Presale):

   • A temporary hold of $10.00 MXN is placed on the card.
   • The API waits for this validation to be approved before proceeding with the tokenization.
   • If the validation is declined (e.g., insufficient funds, invalid card), the tokenization request will fail immediately, and an error will be returned.

2. Token Generation:

   • Once the validation is approved, the card is successfully tokenized.
   • The API responds immediately with your new token_id.

3. Automatic Release (Background Process):

   • After the token is generated, our system automatically handles the release of the held funds in a background process.
   • The $10.00 hold is finalized for a nominal amount of $0.01 MXN to complete the transaction cycle.
   • Immediately after, this $0.01 transaction is cancelled to fully void the charge.

Note for Cardholders: Users may briefly see a pending transaction or hold on their bank statement. This is a standard validation procedure. The charge is automatically voided, and the funds will be released by their issuing bank according to their specific policies (usually within a few business days).

⚠️

IMPORTANT

To follow the steps below, it is essential to have the corresponding Authorization Token. For more information, please refer to the following documentation page: Authorization Token

Create Tokenized Card

💻

Visit our API Reference to test this endpoint.

Endpoint

POST {{baseURL}}/api/tokens

Headers

• Authorization: {token}

Request Payload

The tokenization endpoint accepts a card identifier or raw card details to generate a secure token.

Core Fields

• id: Optional. String value for the card ID. If provided, the system retrieves saved card details from the database. See Customer Cards for further details.
• cvc: Optional. String (3-4 digits). The security code of the card.
  • If id is provided: This overrides the saved CVC (or provides it if not stored).
  • If id is NOT provided: This is required for a valid token.
• tokenization: Optional. Boolean.
  • true: Performs Permanent Tokenization. This triggers the Card Validation Process ($10.00 hold/presale) and stores the card in the secure vault.
  • false (default): Generates a Temporary Token. Valid for 15 minutes; no validation hold is performed.

Card Details (Required if id is NOT provided)

• number: Required. String. The full credit or debit card number (no spaces or dashes).
• name: Required. String. The cardholder's name exactly as it appears on the card.
• exp_month: Required. String. Two-digit expiration month (e.g., "05").
• exp_year: Required. String. Two-digit or four-digit expiration year (e.g., "26" or "2026").

Installment Settings (Optional)

These parameters can be bundled into the token to pre-configure payment options:

• installments: Optional. Integer. Supports 3, 6, 9, 12, or 18 month periods.
• fixed_installments: Optional. Boolean.
  • true: The order will be processed with Fixed Installments (Deferred Payments).
  • false: The order will be processed with Interest-free installments.

Contextual Fields

• source: Optional. String. Identifies the origin of the request (e.g., one_click_checkout).
  • Note: If source is one_click_checkout and an id is provided, tokenization is automatically set to true.

Examples

Request

curl --location 'http://sandbox.ecartpay.com/api/tokens' \
--header 'Authorization: {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "id": "691f28027e1d5b8fb9288552",
  "tokenization": true
}'

curl --location --request POST 'https://sandbox.ecartpay.com/api/tokens' \
--header 'Authorization: {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "id": "691f28027e1d5b8fb9288552",
  "fixed_installments": true,
  "installments": 3,
  "tokenization": true
}'

curl --location 'http://sandbox.ecartpay.com/api/tokens' \
--header 'Authorization: {{token}}' \
--header 'Content-Type: application/json' \
--data '{
  "number": "5200000000002235",
  "name": "Test card",
  "exp_month": "01",
  "exp_year": "2050",
  "cvc": "123"
}'

Response

{
    "token": "6994c62bef227f96aa390686"
}

{
    "token": "ca_a4185916ef417702c"
}