Generate a Network Token

Network tokenization replaces a card's real PAN with a DPAN (a device/domain‑specific number). To authorize a payment with a DPAN you also need a cryptogram, a one‑time proof of authentication generated right before the transaction. This guide covers both steps and how to hand the result to any processor.

Step 1: Create a token and provision the network token

Tokenize the card and set storeCard to 1 so SoftPoint requests a DPAN from the network at the same time. Network tokenization must be enabled on the location, contact to support to enable it.

URL: {{gtw_url}}/locations/{{location_id}}/tokens
Method: POST

curl --request POST \
  --url '{{gtw_url}}/locations/{{location_id}}/tokens' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "storeCard": 1,
    "currency_iso": "USD",
    "card_data": {
      "pan": "5120342233150747",
      "sad": "972",
      "exp_month": "12",
      "exp_year": "26",
      "card_holder": "John MA"
    }
  }'

The response contains both identifiers. Keep both — you will need them in Step 2:

{
  "card_data": {
    "token": "NBt8SACAhNuC0747"
  },
  "network_token_data": {
    "token": "5120XXXXXX150747",
    "exp_month": "12",
    "exp_year": "29",
    "card_network": "Mastercard",
    "state": "ACTIVE"
  }
}

Value	Field	Purpose
SP token	`card_data.token`	Identifies the stored card in SoftPoint. Used to request cryptograms later.
DPAN	`network_token_data.token`	The network token itself. Sent to the processor in place of the real PAN.

Full request/response reference: create-token.md. To look up a token and its network token status later, see get-token.md.

Step 2: Generate a cryptogram before each transaction

A cryptogram is single-use — request a fresh one immediately before every authorization, don't cache or reuse one from a previous sale.

URL: {{gtw_url}}/locations/{{location_id}}/network-token/cryptogram
Method: POST

curl --request POST \
  --url '{{gtw_url}}/locations/{{location_id}}/network-token/cryptogram' \
  --header 'Authorization: Bearer {{access_token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "token": "NBt8SACAhNuC0747",
    "network_token": "5120XXXXXX150747"
  }'

Response:

{
  "cryptogram": "AgAAAAAAAAAAAAAQAAAAAAA=",
  "eci": "05"
}

If the token isn't ACTIVE (e.g. the network suspended or deleted it), this call fails — check its state with ADD_GET_TOKEN_LINK_HERE before retrying. Full field and error reference: ADD_CRYTOGRAM_DOC_LINK_HERE.

Step 3: Submit the network token to any processor

Build the authorization request for your processor using the DPAN and cryptogram instead of the real card number, and the network token's own expiry date — not the original card's expiry.

Real card field	Replace with
Card number / PAN	DPAN (`network_token_data.token`)
Expiration month/year	Network token expiry (`network_token_data.exp_month` / `exp_year`)
CVV	Omit — not required for network-tokenized transactions
Cryptogram / UCAF / cardholder authentication value	`cryptogram` from Step 2
Electronic Commerce Indicator (ECI)	`eci` from Step 2

Most processor APIs expose these under names like tokenizedCard, networkToken, paymentCredentials, or onlineCardholderAuthValue — map the table above onto whatever field names your target processor uses.

Best practices

Generate one cryptogram per transaction. Reusing a cryptogram across multiple authorizations will be declined by the network.
Re-check token state via get-token.md if a cryptogram request fails with network_token_inactive — the card network can suspend or delete a DPAN independently of SoftPoint (e.g. on card reissue or cancellation).
Store the SP token as your long-lived reference; only the DPAN + cryptogram + ECI are sent to the processor.