Network Tokens

How network tokens work in Kushki's Card Payments API: bring your own token, or let Kushki create one during the charge.

A network token is a card number issued directly by the card network (Visa or Mastercard) that replaces the real card number (PAN) in a transaction. It is tied to the original card and updates automatically if the card expires or is reissued, so the merchant does not need to ask the cardholder for a new number when that happens.

Kushki supports network tokens in Colombia, Chile, Peru, and Mexico in two independent ways, and a single integration can use one, both, or neither on a given transaction. Both paths apply to Kushki's acquiring model.

1. Bring your own network token (Transport)

BETA

If your integration already obtains network tokens on its own, for example from a digital wallet such as Apple Pay, you can hand that token to Kushki so the transaction is processed with it instead of a traditional PAN. This feature is in BETA: contact your Kushki account manager before enabling it.

Send the network token when requesting a Kushki token

It is sent in the Create a card token request (POST /card/v1/tokens), with card.number set to the network token number, card.cryptogram set to the cryptogram, isNetworkToken: true, and a networkToken object with the wallet and device metadata:

{
  "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": "MXN"
}

Field	Description
`isNetworkToken`	Indicates that `card.number` is a network token and not a traditional PAN.
`card.cryptogram`	Dynamic cryptogram of the network token, 20 to 28 alphanumeric characters. It is a separate field from the CVV.
`deviceType`	Type of device originating the tokenized transaction.
`requestorId`	Unique ID that the card network assigns to the token requestor.
`source`	Source of the token.
`walletId`	Digital wallet identifier: `01` for Apple Pay, `04` for other wallets.
`authenticationLevel`	Authentication level performed during token provisioning.
`mvv`	10-digit Merchant Verification Value (Visa transactions only).

You can also send these fields directly in a tokenless charge (POST /card/v2/charges).

Continue the normal flow

Use the returned token to call Charge (POST /card/v1/charges) or Pre-authorization (POST /card/v1/preAuthorization). The rest of the flow does not change.

Cryptogram and CVV

The cryptogram is sent in card.cryptogram and does not replace the CVV. We recommend also sending card.cvv: if you send only the cryptogram, the acceptance rate may vary. Check with your wallet or token provider whether they include a cryptogram.

2. Let Kushki create one (Creation)

If instead you are tokenizing a regular card with Kushki, without bringing an already tokenized number, you can ask Kushki to also tokenize that card with a network token during the charge, using Kushki's own tokenizer.

Request it in the charge

Include "networkToken" in the capabilities array of the Charge (POST /card/v1/charges) or Pre-authorization (POST /card/v1/preAuthorization) request. It also works in their tokenless variants: Tokenless charge and Tokenless pre-authorization.

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

Read the network object in the response

If the transaction was tokenized this way, the response includes a network object with the token details:

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

Requires a commercial agreement

Network token creation is enabled on demand through a commercial agreement. Not every transaction is tokenized this way even with the agreement active: check the network object in each response to see whether that particular transaction was.

How the two paths relate

Transport and Creation answer different questions:

Transport controls what you send: whether the card number in the request is a traditional PAN or a network token you already obtained on your own.

Creation controls what you get back: whether Kushki reports network token information for that transaction in the response, using its own tokenizer.

They are independent: using one neither requires nor excludes the other. The network object in the charge or pre-authorization response reflects what you requested in capabilities and what actually happened to that transaction, regardless of which path the underlying token came from.

API reference

Create a card token: isNetworkToken, networkToken, and card.cryptogram fields.

Charge and Tokenless charge: capabilities and the network object.

Pre-authorization and Tokenless pre-authorization: capabilities and the network object.

1. Bring your own network token (Transport)#

2. Let Kushki create one (Creation)#

How the two paths relate#

API reference#

1. Bring your own network token (Transport)

2. Let Kushki create one (Creation)

How the two paths relate

API reference