Improve authorization rates and reduce payment failures with network tokens from Visa and Mastercard

Network Tokenization

Network tokenization replaces sensitive card details (Primary Account Number or PAN) with a token provisioned directly by the card network. These tokens remain valid even when the underlying card is replaced, expired, or reported lost, significantly improving authorization rates for stored card transactions.

How Network Tokenization Works

When you enable network tokenization for a stored card, Plexy requests a token from the card network (Visa Token Service or Mastercard Digital Enablement Service). This token:

Replaces the PAN for all future transactions
Updates automatically when the physical card is replaced
Includes cryptograms unique to each transaction for enhanced security
Is merchant-specific and cannot be used elsewhere if compromised

Benefits of Network Tokenization

Benefit	Description	Impact
Higher authorization rates	Issuers trust network tokens more than raw PANs	2-5% improvement
Automatic updates	Card replacements don't require customer action	Reduced churn
Enhanced security	Transaction-specific cryptograms prevent replay attacks	Lower fraud
Issuer preference	Many issuers prioritize network token transactions	Fewer soft declines
Lifecycle management	Network maintains token validity	Less maintenance

Supported Card Networks

Network	Token Service	Status
Visa	Visa Token Service (VTS)	Supported
Mastercard	Mastercard Digital Enablement Service (MDES)	Supported
American Express	American Express Token Service	Coming soon
Discover	Discover Token Service	Coming soon
UnionPay	UnionPay Token Service	Coming soon

For cards that don't support network tokenization, Plexy automatically falls back to using the original PAN. Your integration doesn't need to handle this case differently.

Enabling Network Tokenization

Enable When Creating a Payment Method

Request a network token when storing a card for the first time:

curl -X POST https://api.plexypay.com/v2/payment_methods \
  -H "x-api-key: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "card": {
      "number": "4111111111111111",
      "exp_month": 12,
      "exp_year": 2028,
      "cvc": "123"
    },
    "customer": "cus_abc123",
    "enable_network_token": true,
    "metadata": {
      "source": "checkout"
    }
  }'

import { Plexy } from '@plexy/plexy-web';

const plexy = new Plexy({
  apiKey: process.env.PLEXY_SECRET_KEY,
});

const paymentMethod = await plexy.paymentMethods.create({
  type: 'card',
  card: {
    number: '4111111111111111',
    exp_month: 12,
    exp_year: 2028,
    cvc: '123',
  },
  customer: 'cus_abc123',
  enable_network_token: true,
  metadata: {
    source: 'checkout',
  },
});

console.log('Network token status:', paymentMethod.card.network_token?.status);

import os
from plexy import Plexy

plexy = Plexy(api_key=os.environ['PLEXY_SECRET_KEY'])

payment_method = plexy.payment_methods.create(
    type='card',
    card={
        'number': '4111111111111111',
        'exp_month': 12,
        'exp_year': 2028,
        'cvc': '123',
    },
    customer='cus_abc123',
    enable_network_token=True,
    metadata={
        'source': 'checkout',
    },
)

print(f"Network token status: {payment_method.card.network_token.get('status')}")

Response with Network Token

{
  "id": "pm_card_visa_abc123",
  "object": "payment_method",
  "type": "card",
  "customer": "cus_abc123",
  "card": {
    "brand": "visa",
    "last4": "1111",
    "exp_month": 12,
    "exp_year": 2028,
    "funding": "credit",
    "country": "US",
    "network_token": {
      "status": "active",
      "type": "visa_token_service",
      "token_last4": "4895",
      "token_exp_month": 12,
      "token_exp_year": 2030,
      "provisioned_at": "2026-03-25T10:30:00Z"
    }
  },
  "created_at": "2026-03-25T10:30:00Z"
}

Network Token Status Values

Status	Description
`active`	Token is provisioned and ready for use
`pending`	Token provisioning is in progress
`inactive`	Token has been deactivated by the network
`suspended`	Token is temporarily suspended
`not_supported`	Card doesn't support network tokenization

Enable for Existing Payment Methods

You can request network tokens for payment methods that were stored without them:

curl -X POST https://api.plexypay.com/v2/payment_methods/pm_card_visa_abc123/network_token \
  -H "x-api-key: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

const result = await plexy.paymentMethods.createNetworkToken('pm_card_visa_abc123');

console.log('Token status:', result.network_token.status);

result = plexy.payment_methods.create_network_token('pm_card_visa_abc123')

print(f"Token status: {result.network_token['status']}")

Response

{
  "payment_method": "pm_card_visa_abc123",
  "network_token": {
    "status": "active",
    "type": "visa_token_service",
    "token_last4": "4895",
    "provisioned_at": "2026-03-25T10:35:00Z"
  }
}

Using Network Tokens for Payments

When you make a payment with a stored card that has an active network token, Plexy automatically uses the token. No changes to your payment request are required.

curl -X POST https://api.plexypay.com/v2/payments \
  -H "x-api-key: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 9900,
    "currency": "USD",
    "customer": "cus_abc123",
    "payment_method": "pm_card_visa_abc123",
    "off_session": true,
    "description": "Monthly subscription"
  }'

const payment = await plexy.payments.create({
  amount: 9900,
  currency: 'USD',
  customer: 'cus_abc123',
  payment_method: 'pm_card_visa_abc123',
  off_session: true,
  description: 'Monthly subscription',
});

// Check if network token was used
console.log('Used network token:', payment.payment_method_details?.network_token_used);

payment = plexy.payments.create(
    amount=9900,
    currency='USD',
    customer='cus_abc123',
    payment_method='pm_card_visa_abc123',
    off_session=True,
    description='Monthly subscription',
)

# Check if network token was used
print(f"Used network token: {payment.payment_method_details.get('network_token_used')}")

Payment Response with Network Token

{
  "id": "pay_xyz789",
  "object": "payment",
  "amount": 9900,
  "currency": "USD",
  "status": "succeeded",
  "payment_method": "pm_card_visa_abc123",
  "payment_method_details": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "1111",
      "network_token_used": true,
      "network_transaction_id": "123456789012345"
    }
  },
  "created_at": "2026-03-25T10:40:00Z"
}

Webhook Events

Plexy sends webhooks when network token status changes:

network_token.created

Sent when a network token is successfully provisioned.

{
  "id": "evt_abc123",
  "type": "network_token.created",
  "created_at": "2026-03-25T10:30:00Z",
  "data": {
    "payment_method": "pm_card_visa_abc123",
    "customer": "cus_abc123",
    "network_token": {
      "status": "active",
      "type": "visa_token_service",
      "token_last4": "4895"
    }
  }
}

network_token.updated

Sent when the underlying card details change and the token is updated.

{
  "id": "evt_def456",
  "type": "network_token.updated",
  "created_at": "2026-03-25T10:45:00Z",
  "data": {
    "payment_method": "pm_card_visa_abc123",
    "customer": "cus_abc123",
    "network_token": {
      "status": "active",
      "type": "visa_token_service",
      "token_last4": "4895"
    },
    "update_reason": "card_replaced",
    "previous_card": {
      "exp_month": 12,
      "exp_year": 2026
    },
    "updated_card": {
      "exp_month": 12,
      "exp_year": 2029
    }
  }
}

network_token.deactivated

Sent when a network token is deactivated (e.g., account closed).

{
  "id": "evt_ghi789",
  "type": "network_token.deactivated",
  "created_at": "2026-03-25T11:00:00Z",
  "data": {
    "payment_method": "pm_card_visa_abc123",
    "customer": "cus_abc123",
    "network_token": {
      "status": "inactive",
      "type": "visa_token_service"
    },
    "deactivation_reason": "account_closed"
  }
}

When you receive a network_token.deactivated event with reason account_closed, the cardholder has closed their account. You should contact the customer to update their payment method.

Bulk Provisioning

To enable network tokens for all existing stored cards, use the bulk provisioning endpoint:

curl -X POST https://api.plexypay.com/v2/network_tokens/bulk_provision \
  -H "x-api-key: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "network_token_status": "not_provisioned",
      "card_brands": ["visa", "mastercard"]
    },
    "limit": 1000
  }'

Response

{
  "id": "bulk_prov_abc123",
  "status": "processing",
  "total_cards": 847,
  "estimated_completion": "2026-03-25T12:00:00Z",
  "created_at": "2026-03-25T10:50:00Z"
}

You'll receive network_token.created webhooks as each token is provisioned.

Configuration in Plexy Dashboard

Configure default network tokenization settings in the Plexy Dashboard:

Go to Settings > Account Management > Network Tokenization.

Toggle Auto-provision network tokens to automatically request tokens for all new stored cards.

Select which card networks to enable: Visa, Mastercard, or both.

Enable webhook events for token lifecycle changes.

Monitoring and Analytics

Track network tokenization performance in Plexy Dashboard under Reports > Account Management:

Metric	Description
Token adoption rate	Percentage of stored cards with active network tokens
Authorization lift	Difference in auth rates between token and PAN transactions
Token update rate	Cards updated automatically via network token lifecycle
Provisioning success rate	Percentage of successful token provisioning requests

Issue	Cause	Solution
Token status `not_supported`	Card issuer doesn't support network tokens	Continue using PAN; monitor for future support
Token status `pending` for extended time	Network provisioning delayed	Wait up to 24 hours; contact support if longer
Authorization failed with token	Token may be out of sync	Plexy auto-retries with PAN as fallback
Token deactivated unexpectedly	Account closed or card cancelled	Contact customer for new payment method

Next Steps

Account Updater - Keep card credentials current
Auto Rescue - Recover failed payments automatically
Manage Tokens - List and manage stored payment methods

Network Tokenization

Network Tokenization

How Network Tokenization Works

Benefits of Network Tokenization

Supported Card Networks

Enabling Network Tokenization

Enable When Creating a Payment Method

Response with Network Token

Network Token Status Values

Enable for Existing Payment Methods

Response

Using Network Tokens for Payments

Payment Response with Network Token

Webhook Events

network_token.created

network_token.updated

network_token.deactivated

Bulk Provisioning

Response

Configuration in Plexy Dashboard

Monitoring and Analytics

Best Practices

Enable for All New Cards

Monitor Token Health

Handle Deactivations

Use with Account Updater

Troubleshooting

Next Steps

Осы бетте