CardTokenClient: Secure Card Tokenization Reference

CardTokenClient provides PCI-compliant card tokenization for the Mercado Pago Java SDK. A card token is a short-lived, single-use identifier that represents sensitive card data (card number, CVV, expiry) without exposing it to your server. Tokens are created in the frontend using the MercadoPago.js SDK or Checkout Bricks and are then sent to your backend where they are used to create a payment. Card tokens cannot be reused across payment attempts — if a payment fails, a new token must be generated. For recurring payment scenarios where you want to save a card permanently, tokenize the card and then attach it to a customer using CustomerCardClient.

CardTokenClient

Package: com.mercadopago.client.cardtoken

Constructors

// Uses the default HTTP client configured in MercadoPagoConfig
CardTokenClient()

// Supply a custom MPHttpClient (useful for testing or proxy scenarios)
CardTokenClient(MPHttpClient httpClient)

Methods

`create`

Creates a new card token from a saved customer card. This is the server-side tokenization path used when re-charging a card that has already been saved to a Customer — you supply the cardId and customerId, along with the CVV to generate a fresh single-use token.

CardToken create(CardTokenRequest request) throws MPException, MPApiException
CardToken create(CardTokenRequest request, MPRequestOptions requestOptions) throws MPException, MPApiException

request

CardTokenRequest

required

Card token request parameters. See CardTokenRequest fields.

requestOptions

MPRequestOptions

Optional per-request overrides for access token, headers, or timeouts. Pass null to use defaults.

Returns: CardToken — the created token. Use cardToken.getId() as the token field when creating a payment.

`get`

Retrieves a card token by its unique identifier. Useful for inspecting token metadata (e.g., masked card number, expiration) without re-sending card data.

CardToken get(String id) throws MPException, MPApiException
CardToken get(String id, MPRequestOptions requestOptions) throws MPException, MPApiException

String

required

Unique identifier of the card token to retrieve.

requestOptions

MPRequestOptions

Optional per-request overrides.

Returns: CardToken

CardTokenRequest fields

CardTokenRequest is a Lombok @Builder class with the following fields:

cardId

String

Unique identifier of a saved card associated with a customer. Required when re-tokenizing a stored card for a repeat charge.

customerId

String

Unique identifier of the customer who owns the saved card. Required alongside cardId for stored-card tokenization.

securityCode

String

CVV/CVC printed on the card. Required when creating a token from a saved card to meet issuer security requirements.

When tokenizing a new card on the frontend (first-time checkout), use the MercadoPago.js SDK or Checkout Bricks — these tools send card data directly to Mercado Pago’s servers and return a token without the raw card data ever touching your backend. The CardTokenClient.create method is used in backend flows for re-charging previously saved cards.

Code Example

import com.mercadopago.MercadoPagoConfig;
import com.mercadopago.client.cardtoken.CardTokenClient;
import com.mercadopago.client.cardtoken.CardTokenRequest;
import com.mercadopago.resources.CardToken;

MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

CardTokenClient client = new CardTokenClient();

// Re-tokenize a saved card for a repeat charge (server-side)
// cardId and customerId come from a previously saved CustomerCard
CardTokenRequest request = CardTokenRequest.builder()
    .cardId("123456789")
    .customerId("649457098-FybpOkG6zH8QRm")
    .securityCode("123")
    .build();

CardToken token = client.create(request);
System.out.println("Token ID: " + token.getId());
// Use token.getId() as the `token` field when creating a payment:
// PaymentCreateRequest.builder().token(token.getId()) ...

// Retrieve token metadata
CardToken retrieved = client.get(token.getId());
System.out.println("Last four digits: " + retrieved.getLastFourDigits());
System.out.println("Expiration month: " + retrieved.getExpirationMonth());
System.out.println("Expiration year: " + retrieved.getExpirationYear());

Card tokens are single-use and expire after a short period (typically 7 days). Do not store the raw token for later reuse — generate a new one for each payment attempt. To save a card for repeated charges, use CustomerCardClient.create after a successful first payment, then use CardTokenClient.create with the saved cardId and customerId for subsequent charges.

Core

Clients

Exceptions & HTTP

CardTokenClient: Secure Card Tokenization Reference