Network Tokens

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.

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": 15000,
  "currency": "CLP"
}

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

Campo	Descripción
`isNetworkToken`	Indica que `card.number` es un network token y no un PAN tradicional.
`card.cryptogram`	Criptograma dinámico del network token, de 20 a 28 caracteres alfanuméricos. Es un campo distinto del CVV.
`deviceType`	Tipo de dispositivo que origina la transacción tokenizada.
`requestorId`	ID único que la red de tarjetas asigna al solicitante del token.
`source`	Origen del token.
`walletId`	Identificador de la wallet digital: `01` para Apple Pay, `04` para otras wallets.
`authenticationLevel`	Nivel de autenticación realizado durante el aprovisionamiento del token.
`mvv`	Merchant Verification Value de 10 dígitos (solo transacciones Visa).

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.

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.

Criptograma y CVV

El criptograma se envía en card.cryptogram y no reemplaza al CVV. Se recomienda enviar también card.cvv: si solo envías el criptograma, la tasa de aceptación puede variar. Confirma con tu wallet o proveedor de tokens si incluyen un criptograma.

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.

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: Cargo sin token y Preautorización sin token.

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

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"
  }
}

Requiere un acuerdo comercial

La creación de network tokens se habilita bajo demanda mediante un acuerdo comercial. No todas las transacciones se tokenizan de esta forma aun con el acuerdo activo: revisa el objeto network en cada respuesta para saber si esa transacción en particular lo fue.

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.

¿Usas Apple Pay?

Configura Apple Pay en tu integración para obtener network tokens desde la wallet del cliente.

1. Trae tu propio network token (Transporte)#

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

Cómo se relacionan los dos caminos#

Referencia API#

1. Trae tu propio network token (Transporte)

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

Cómo se relacionan los dos caminos

Referencia API