Network Tokens

October 08, 2026

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.

Step 1. 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": "PEN"
}

Replace currency with your country’s currency: COP, CLP, PEN, or MXN.

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

See the full reference in Create a card token.

Step 2. 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.

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.

Step 1. 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.

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

Step 2. 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"
  }
}

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.