Understand the distinction: card-on-file (CoF) stores the raw PAN or a PSP vault token tied to the PAN; network tokens (issued by Visa, Mastercard via their token services) are scheme-level tokens that are merchant-specific and automatically updated when the underlying card is reissued.
For agent use cases with repeat purchases at known merchants, prefer network tokens where your PSP supports them: they reduce decline rates on card reissuance (the token stays valid even when a new physical card is issued), and they reduce PAN exposure.
To use network tokens: store the customer's payment method in your PSP vault at the time of the first customer-present transaction; the PSP handles token provisioning with the card network behind the scenes; for subsequent agent-initiated charges, reference the PSP payment method ID (which maps to the network token).
For CoF fallback (where network tokens are not available): store only the PSP's payment method ID, never the raw PAN; update the stored method when the customer reports a new card or when a charge fails with a 'card expired' or 'card number changed' decline code.
For agent-initiated off-session charges, set the appropriate MIT (merchant-initiated transaction) flag on the charge to signal the card network that the cardholder is not present; this affects interchange rates and 3DS liability.
Audit which payment method type is in use for each charge and track decline rates by method type; this informs whether to prioritize network token rollout.
Known gotchas
Network token provisioning is handled by the PSP and card network — there is no additional API call you make to 'get' a network token; if your PSP supports it, it happens automatically when you save a payment method; if not, you are using CoF regardless of what you call it.
Merchant-initiated transaction flags and mandate requirements differ by card network and jurisdiction; using MIT flags without a valid mandate on file is a compliance violation that can lead to increased chargebacks and interchange penalties.
CoF charges have higher fraud rates than cardholder-present transactions; card networks price this risk into interchange and may require additional velocity controls from your acquiring bank — factor this into your payment architecture cost model.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp