Prerequisites

• To use gateway tokens from a supported provider, or to import existing tokens, confirm that Recurly supports the logic required to handle that token type. For cards and certain direct debit methods, Recurly stores payment details securely (encrypted) rather than tokenising the method itself. See configuring multiple gateways for a scalable payments setup.

Limitations

• If only a gateway token is present, gateway failover to other providers is not possible.
• Imported tokens on a handful of gateways typically don't display full payment method details and are treated as generic tokens. This includes tokens brought in through Professional Services or sent via API without using Recurly.js or standard Recurly API flows. Generic and imported tokens may not support some behaviours available to standard payment methods. Exceptions are: Stripe, Adyen, Braintree -- speak to Support about enabling our Token Backfill behavior.
• If only a gateway token is present for cards (common with imports), Recurly Account Updater cannot be used. Check with your gateway provider about Account Updater availability.

Key details

Token types

Gateway token — A value referencing a payment instrument stored with a specific gateway partner. Gateway tokens are not transferable between gateways. For example, an Adyen token cannot be used to process a transaction on Stripe.

Network token — A card token issued by a card network (e.g., Visa) that can be used across multiple gateways and is not bound to a single provider.

One-time token — A short-lived token used once, typically to move sensitive data from your website to Recurly during a checkout flow. One-time tokens cannot be stored for renewals.

Examples of one-time tokens: Recurly.js tokens, Stripe confirmation tokens (Payment Elements), Braintree nonces, Adyen State Data (Web Components).

Key benefits by token type

Network tokens

• Enable failover across gateways when using multiple providers.
• Support migrating existing subscriptions to a different gateway that supports network tokens.

Gateway tokens

• Keep the payment instrument under your gateway's control and let the gateway's Account Updater keep details current (where available).
• Support payment methods that must be tokenised for acceptance.
• Enable certain gateway-specific behaviours that depend on tokenised flows.
• Trade-off: Portability is limited, and some Recurly features requiring full instrument details may be unavailable (see Limitations above).

One-time tokens

• Reduce PCI scope by ensuring sensitive data doesn't touch your servers.
• Caveat: One-time tokens expire quickly and cannot be reused — pass them to Recurly promptly.

Gateway token interoperability

Gateway tokens can be used only on the gateway they originate from.

• Stripe tokens work only on Stripe and won't work on Adyen — even related platforms such as Braintree and PayPal are not always compatible. Contact Recurly Support before attempting to use a token on a different gateway.
• Gateway tokens are typically limited to the specific gateway account that created them. An Adyen token created on one Adyen account generally cannot be used on a different Adyen account, even with the same provider. When using gateway tokens across different gateway_code values, confirm the token can be used on that gateway account.
• If you have multiple instances of the same gateway in Recurly that map to the same gateway account, tokens can typically be used across those instances. If the instances map to different accounts (e.g., two different Stripe accounts), their tokens are not transferable and payments may fail.
• If you send a gateway token without a gateway_code on an existing account or Billing Info ID, Recurly uses the gateway_code the token was first created or added with. To use a different gateway_code, include it explicitly in your API payload.

When does Recurly tokenise?

Recurly may tokenise payment methods in some flows and securely store payment instruments in others. Behaviour depends on the gateway and checkout flow.

Stripe

All payment methods are tokenised. Recurly also retains card data. With Stripe Payment Elements, Stripe retains the raw card data and Recurly does not have access to the primary account number (PAN).

Recurly supports Stripe confirmation tokens (ctoken_xxxxx) and exchanges them for reusable Payment Method IDs (Stripe gateway tokens). Recurly receives gateway tokens from Stripe only on approved payments.

If you import Stripe tokens, payment methods are generic and may have degraded performance unless you ask Support to enable a special backfill feature flag. For card renewals with imported Stripe tokens, pass the cardholder-initiated transaction (CIT) network transaction ID (NTID) when creating future-dated subscriptions. See Using gateway tokens and external NTIDs with Recurly APIs.

Braintree

Depending on your gateway configuration, Recurly can create Braintree tokens for future use, but doesn't do so by default unless the payment method requires it (e.g., PayPal or Venmo).

With Recurly.js or hosted pages (e.g., Checkout), Recurly creates a Braintree nonce (a one-time token) that can be exchanged for a reusable Braintree token for renewals when required. To vault tokens in Braintree automatically, see Configuration steps for Braintree.

Braintree does not support PayPal Billing Agreement IDs and won't process them. If you are importing tokens or migrating from a PayPal direct integration, you must first vault these billing agreements with Braintree — contact Recurly Professional Services for assistance.

If you import Braintree tokens, payment methods are generic and may have degraded performance. For card renewals with imported Braintree tokens, pass the CIT NTID when creating future-dated subscriptions. See Using gateway tokens and external NTIDs with Recurly APIs.

Adyen

With native Recurly checkout flows (API with raw data, Recurly.js, hosted pages), only non-card methods are tokenised by default. With Adyen Web Components through Recurly.js, all supported methods are tokenised.

If you need an Adyen feature that requires tokenisation (e.g., network tokens), use Third-party checkout for Adyen Web Components.

If you import Adyen tokens, payment methods are generic and may have degraded performance. For card renewals with imported Adyen tokens, pass the CIT NTID when creating future-dated subscriptions. See Using gateway tokens and external NTIDs with Recurly APIs.

Commerce Hub / Fiserv

Imported Fiserv TransArmor tokens can be used but may have degraded performance. For renewals with Commerce Hub tokens, pass the CIT NTID when creating future-dated subscriptions. See Using gateway tokens and external NTIDs with Recurly APIs.

FreedomPay

Imported FreedomPay tokens can be imported or sent via API. For renewals with FreedomPay tokens, pass the CIT NTID when creating future-dated subscriptions. See Using gateway tokens and external NTIDs with Recurly APIs.

Amazon Pay

Payment instruments are stored with Amazon Pay. Recurly stores a Billing Agreement or Charge Permission ID for renewals and one-time payments (Amazon Pay V1 and V2). These can be imported if you use Amazon Pay V1 or V2. Charge Permission IDs are supported on Amazon Pay V2 only.

PayPal

Payment instruments are stored with PayPal and are not accessible to Recurly. Recurly stores a token or billing agreement for renewals and one-time payments.

PayPal Complete is a special case: Recurly retains raw card details (PAN) and creates a PayPal token for renewals. Legacy PayPal and PayPal Complete gateways support Billing Agreement IDs. Only PayPal Complete supports the newer PayPal token.

Where is the payment data stored?

Use this matrix to understand which system stores the payment instrument based on gateway and checkout flow.