### Would you like to contact support?

No momento, esta página não está disponível em português

# Manage network tokens

Learn how to manage network tokens for cards added to digital wallets.

When your cardholder adds their Adyen-issued card to the digital wallet, the card scheme (Visa or Mastercard) creates a network token for it. A network token is a 16-digit Primary Account Number (PAN) alternative that is unique for each card-device-wallet pairing.

The benefits of using network tokens are:

• Reduced user friction and declined payments because network tokens are maintained by card schemes.
• Higher authorisation rates compared to payments made without network tokens.
• Better payment security because each transaction is protected with a one-time use cryptogram.

With Adyen Issuing, you can manage network tokens separately from the cards. For example, you might want to temporarily suspend a network token or deactivate a network token, if the card has been lost or stolen.

## Get all network tokens

To get all network tokens that are linked to the Adyen-issued card:

1. Make a GET /paymentInstruments/{id}/networkTokens request and specify the following parameter in the path:

Path parameter Description
id The identifier of the payment instrument created when issuing a card.
Get all network tokens of a card
curl https://balanceplatform-api-test.adyen.com/bcl/v2/paymentInstruments/PI3227C223222B5BPCMFXD2XG/networkTokens \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-X GET \
-d ''

The response returns all network tokens associated with the payment instrument PI3227C223222B5BPCMFXD2XG regardless of the network token status.

Parameter Description Possible values
type The type of wallet the network token is associated with. applePay, googlePay
id The unique identifier of the network token. NWTK00000000000000000000000001
paymentInstrumentId The unique identifier of the payment instrument. PI3227C223222B5BPCMFXD2XG
creationDate Date and time when the network token was created. 2021-01-01T01:00:00+01:00
status The status of the network token. active, inactive, suspended, closed.
brandVariant The card brand variant of the payment instrument associated with the network token. mcmaestro, mc_prepaid_mrw, etc.
tokenLastFour The last four digits of the network token id. 0001
device.osName The operating system of the device the network token is stored on. android, ios, other.
device.formFactor The form factor of the device the network token is stored on. phone, watch, tablet, other.
Response
{
"data": [
{
"type": "applePay",
"id": "NWTK00000000000000000000000001",
"paymentInstrumentId": "PI3227C223222B5BPCMFXD2XG",
"creationDate": "2020-01-01T01:00:00+01:00",
"status": "active",
"brandVariant": "mcmaestro",
"tokenLastFour": "0001",
"device": {
"osName": "ios",
"formFactor": "phone"
}
},
{
"id": "NWTK00000000000000000000000002",
"paymentInstrumentId": "PI3227C223222B5BPCMFXD2XG",
"creationDate": "2021-01-01T01:00:00+01:00",
"status": "suspended",
"brandVariant": "mc_prepaid_mrw",
"tokenLastFour": "0002",
"device": {
"osName": "android",
"formFactor": "watch"
}
}
]
}

## Get a single network token

To get the details of a single network token that is linked to the Adyen-issued card:

1. Make a GET /networkTokens/{networkTokenId} request and specify the following parameter in the path:

Path parameter Description
networkTokenId The identifier of the network token associated with the card.
Get a single network token of a card
curl https://balanceplatform-api-test.adyen.com/bcl/v2/paymentInstruments/PI3227C223222B5BPCMFXD2XG/networkTokens/NWTK00000000000000000000000001 \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-X GET \
-d ''

The response contains the details for the network token NWTK00000000000000000000000001 associated with the payment instrument.

Parameter Description Possible values
type The type of wallet the network token is associated with. applePay, googlePay
id The unique identifier of the network token. NWTK00000000000000000000000001
paymentInstrumentId The unique identifier of the payment instrument. PI3227C223222B5BPCMFXD2XG
creationDate Date and time when the network token was created. 2020-01-01T01:00:00+01:00
status The status of the network token. active, inactive, suspended, closed
brandVariant The card brand variant of the payment instrument associated with the network token. mcmaestro, mc_prepaid_mrw, etc.
tokenLastFour The last four digits of the network token id. 0001
device.osName The operating system of the device the network token is stored on. android, ios, other
device.formFactor The form factor of the device the network token is stored on. phone, watch, tablet, other
Response
{
"type": "applePay",
"id": "NWTK00000000000000000000000001",
"paymentInstrumentId": "PI3227C223222B5BPCMFXD2XG",
"creationDate": "2020-01-01T01:00:00+01:00",
"status": "active",
"brandVariant": "mcmaestro",
"tokenLastFour": "0001",
"device": {
"osName": "ios",
"formFactor": "phone"
}
}

## Update the status of a network token

To update the status of a network token:

1. Make a PATCH /networkTokens/{networkTokenId} request and specify the following parameter in the path:

Path parameter Description
networkTokenId The identifier of the network token associated with the card.

Provide the following parameters in the request body:

Parameter Required Description
status The status of the network token. Possible values: active, suspended, closed. The closed status is final and cannot be changed.

Here's an example of how to change the status of the network token to suspended.

Update the status of a network token
curl https://balanceplatform-api-test.adyen.com/bcl/v2/paymentInstruments/PI3227C223222B5BPCMFXD2XG/networkTokens/NWTK00000000000000000000000001 \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-X PATCH \
-d '{
"status": "suspended"
}'

The HTTP 202 Accepted response means that the request has been accepted, but will be processed asynchronously. You will get the final result of this request in a notification webhook.

## Limit the usage of a network token

In some cases, you might need to limit the number of network tokens per card or set limits for transactions that use network tokens. You can do so by using the /transactionRules endpoint.

### Limit the number of active network tokens

To limit the number of active network tokens allowed for a single card:

1. Send a POST /transactionRules request and specify the following parameters:

Parameter Required Description
description Your description for the rule. Maximum length: 300 characters. This description is shown in the Balance Platform Customer Area.
entityKey Contains the ID and type of resource to which the rule is applied.
interval The time period or duration when the rule applies.
reference Your reference for the rule. Maximum length: 150 characters.
type Set to blockList, maxUsage, or velocity.
ruleRestrictions Object that contains key-value objects with the key as the condition and the value containing values and operations.
status Set to active if you want to start evaluating the rule. When you set the status to active, we automatically set the startDate to the current time.

The following example shows how to limit the number of active network tokens to only one per card.

Limit the number of active network tokens for a card
curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-X POST \
-d '{
"interval": {
"type": "perTransaction"
},
"type": "blockList",
"description": "Set the maximum number of active network tokens to one for this card",
"reference": "myRule123",
"entityKey": {
"entityType": "paymentInstrument",
"entityReference": "PI3227C223222B5FN65FN5NS9"
},
"ruleRestrictions": {
"activeNetworkTokens": {
"operation": "greaterThanOrEqualTo",
"value": 1
}
},
"status": "active",
"requestType": "authorization",
"outcomeType": "hardBlock"
}'

The response returns the id of the transaction rule that can be used to further update or delete this rule.

Response
{
"description": "Set the maximum number of active network tokens to one for this card",
"entityKey": {
"entityReference": "PI3227C223222B5FN65FN5NS9",
"entityType": "paymentInstrument"
},
"interval": {
"timeZone": "UTC",
"type": "perTransaction"
},
"outcomeType": "hardBlock",
"reference": "myRule123",
"requestType": "authorization",
"ruleRestrictions": {
"activeNetworkTokens": {
"operation": "greaterThanOrEqualTo",
"value": 1
}
},
"startDate": "2022-10-05T10:44:15.608698+02:00",
"status": "active",
"type": "blockList",
"id": "TR32272223222C5GP4S4K5NZG"
}

### Limit transactions using network tokens

To limit the transactions using network tokens for a card:

1. Make a POST /transactionRules request and specify the following parameters:

Parameter Required Description
description Your description for the rule. Maximum length: 300 characters. This description is shown in the Balance Platform Customer Area.
entityKey Contains the ID and type of resource to which the rule is applied.
interval The time period or duration when the rule applies.
reference Your reference for the rule. Maximum length: 150 characters.
type Set to blockList, maxUsage, or velocity.
ruleRestrictions Object that contains key-value objects with the key as the condition and the value containing values and operations.
status Set to active if you want to start evaluating the rule. When you set the status to active, we automatically set the startDate to the current time.

The following example shows how to block transactions that are greater than 50 EUR and use network tokens.

Block the transactions using network tokens
curl https://balanceplatform-api-test.adyen.com/bcl/v2/transactionRules \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-X POST \
-d '{
"description": "Block network token transactions above 50 EUR",
"reference": "myRule123",
"entityKey": {
"entityType": "paymentInstrument",
"entityReference": "PI3227C223222B5FN65FN5NS9"
},
"interval": {
"type": "perTransaction"
},
"ruleRestrictions": {
"processingTypes": {
"operation": "anyMatch",
"value": [
"token"
]
},
"totalAmount": {
"operation": "greaterThan",
"value": {
"currency": "EUR",
"value": 5000
}
}
},
"status": "active",
"outcomeType": "hardBlock",
"type": "velocity"
}'

The response returns the id of the transaction rule that can be used to further update or delete this rule.

Response
{
"description": "Block network token transactions above 50 EUR",
"entityKey": {
"entityReference": "PI3227C223222B5FN65FN5NS9",
"entityType": "paymentInstrument"
},
"interval": {
"timeZone": "UTC",
"type": "perTransaction"
},
"outcomeType": "hardBlock",
"reference": "myRule123",
"requestType": "authorization",
"ruleRestrictions": {
"processingTypes": {
"operation": "anyMatch",
"value": [
"token"
]
},
"totalAmount": {
"operation": "greaterThan",
"value": {
"currency": "EUR",
"value": 5000
}
}
},
"startDate": "2022-10-05T10:34:31.911273+02:00",
"status": "active",
"type": "velocity",
"id": "TR32272223222C5GP4S4K5NZG"
}