Network Tokens

08 octubre 2026

Cómo funcionan los network tokens en la API de Card Payments de Kushki: trae tu propio token, o deja que Kushki cree uno durante el cargo.

Un network token es un número de tarjeta emitido directamente por la red de tarjetas (Visa o Mastercard) que reemplaza el número real de la tarjeta (PAN) en una transacción. Está ligado a la tarjeta original y se actualiza automáticamente si la tarjeta expira o se reemite, así que el comercio no necesita pedirle al tarjetahabiente un nuevo número cuando eso pasa.

Kushki admite network tokens en Colombia, Chile, Perú y México de dos formas independientes, y una misma integración puede usar una, ambas o ninguna en una transacción dada. Ambos caminos aplican al modelo de adquirencia de Kushki.

1. Trae tu propio network token (Transporte)

🚧 BETA

Si tu integración ya obtiene network tokens por su cuenta, por ejemplo desde una wallet digital como Apple Pay, puedes entregarle ese token a Kushki para que la transacción se procese con él en lugar de un PAN tradicional. Esta función está en BETA: contacta a tu ejecutivo de cuenta de Kushki antes de habilitarla.

Paso 1. Envía el network token al solicitar un token de Kushki

Se envía en el request de Solicitar un token de tarjeta (POST /card/v1/tokens), con card.number en el número del network token, card.cryptogram con el criptograma, isNetworkToken: true y un objeto networkToken con los metadatos de wallet y dispositivo:

{
  "card": {
    "name": "Luis García",
    "number": "4761923458201947",
    "expiryMonth": "08",
    "expiryYear": "28",
    "cvv": "121",
    "cryptogram": "AgAAAAAABk4DWZ4C28yUQAAAAAAA"
  },
  "isNetworkToken": true,
  "networkToken": {
    "deviceType": "MOBILE",
    "requestorId": "98987676501",
    "source": "01",
    "walletId": "01",
    "authenticationLevel": "02"
  },
  "totalAmount": 150.00,
  "currency": "PEN"
}

Reemplaza currency por la moneda de tu país: COP, CLP, PEN o MXN.

También puedes enviar estos campos directamente en un cargo sin token (POST /card/v2/charges).

Consulta la referencia completa en Solicitar un token de tarjeta.

Paso 2. Continúa el flujo normal

Usa el token que te devolvieron para llamar a Cargo (POST /card/v1/charges) o a Preautorización (POST /card/v1/preAuthorization). El resto del flujo no cambia.

2. Deja que Kushki cree uno (Creación)

Si en cambio estás tokenizando una tarjeta normal con Kushki, sin traer un número ya tokenizado, puedes pedirle a Kushki que también tokenice esa tarjeta con network token durante el cargo, usando el tokenizador propio de Kushki.

Paso 1. Pídelo en el cargo

Incluye "networkToken" en el array capabilities del request de Cargo (POST /card/v1/charges) o de Preautorización (POST /card/v1/preAuthorization). También funciona en sus variantes sin token.

{
  "token": "f5c64f7ac8ea42d5a58dcdc74de973dc",
  "capabilities": ["networkToken"],
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 150.00,
    "iva": 0,
    "currency": "PEN"
  }
}

Paso 2. Lee el objeto network en la respuesta

Si la transacción se tokenizó de esta forma, la respuesta incluye un objeto network con los detalles del token:

{
  "ticketNumber": "922513792073660814",
  "transactionReference": "6f16659e-b711-4995-a9ae-161aecbd6521",
  "network": {
    "wallet": "cybersource",
    "walletId": "04",
    "isNetworkToken": true,
    "tmsMaskedCardNumber": "549138XXXXXX4509",
    "tmsLastFourDigits": "4509",
    "tmsBin": "549138",
    "tmsIntegration": "kushki"
  }
}

Cómo se relacionan los dos caminos

Transporte y Creación responden preguntas distintas:

• Transporte controla qué envías: si el número de tarjeta en el request es un PAN tradicional o un network token que ya obtuviste por tu cuenta.
• Creación controla qué recibes de vuelta: si Kushki reporta información de network token para esa transacción en la respuesta, usando su propio tokenizador.

Son independientes: usar uno no requiere ni excluye al otro. El objeto network en la respuesta del cargo o la preautorización refleja lo que pediste en capabilities y lo que realmente pasó con esa transacción, sin importar por cuál camino se obtuvo el token subyacente.

Referencia API

• Solicitar un token de tarjeta: campos isNetworkToken, networkToken y card.cryptogram.
• Cargo y Cargo sin token: capabilities y objeto network.
• Preautorización y Preautorización sin token: capabilities y objeto network.