How to Migrate to a New Payment Gateway in Recurly – Recurly

If your business is migrating from one payment gateway to another in Recurly, the process can be smooth and flexible with the right planning. Recurly supports multiple payment gateways within the same site, allowing merchants to route transactions, test new integrations, and gradually transition existing subscribers without service disruption.

Common migration scenarios include:

Switching from Stripe to Adyen or Braintree.
Moving from a legacy gateway to a new regional processor.
Adding a backup or fallback gateway for redundancy.

Migration Options

1. Add a New Gateway

You can connect multiple gateways to your Recurly site under Configuration → Gateways. Each gateway is configured independently and can handle specific transaction types or currencies.

Tip: Keep your current gateway active until all recurring billing and token migrations are fully tested and validated.

2. Route New Transactions

Once the new gateway is added, you can set routing rules or select the new gateway for:

Specific currencies (e.g., use Adyen for EUR, Stripe for USD)
New sign-ups or checkout flows
Backup routing when a primary gateway fails.

Note for Apple Pay and PayPal merchants: If you are migrating from one Apple Pay or PayPal gateway instance to another, you will not be able to set a default gateway for these payment methods in the Recurly UI. You must use gateway routing rules to ensure recurring transactions are correctly directed to the appropriate gateway instance during and after migration. Failure to configure routing for these payment methods may result in transactions being sent to the wrong gateway.

3. Migrating Existing Payment Methods

For recurring subscribers, existing payment tokens must be migrated from your old gateway to the new one to ensure continuity.

Recurly offers a secure token migration process for supported gateways (e.g., Stripe → Adyen, Braintree → Recurly).
Token migrations typically require coordination between your old and new processors.
Contact Recurly Support to initiate a token migration request.

Important: Token migration requires cooperation from both gateways. Not all processors support cross-vault migrations. In unsupported cases, you may need to collect updated payment details from customers.

Apple Pay and PayPal — Special Routing Requirement

Unlike standard card-based payment methods, Apple Pay and PayPal do not support setting a default gateway through the Recurly UI. When migrating between gateway instances for either of these payment methods, merchants must configure gateway routing to direct recurring transactions to the correct gateway instance. This routing must be set up before migration begins to avoid billing disruptions for existing subscribers using these payment methods.

Best Practices

Use Recurly sandbox to test the new gateway connection before production rollout.
Perform the migration in phases — start with a subset of new customers before transitioning existing subscriptions.
Keep your old gateway active for at least one billing cycle overlap to ensure all renewals succeed.
Monitor transaction.error and payment_gateway fields in the Recurly Admin or via API for any anomalies.
Notify customers in advance if you expect any re-authentication or billing updates.
If your site uses Apple Pay or PayPal, configure gateway routing rules before initiating migration to ensure recurring transactions reach the correct gateway instance.

Testing in Sandbox

Use Recurly’s Sandbox environment to test a full checkout, subscription renewal, and refund process on the new gateway before going live.


# Example: Create a test transaction on the new gateway
curl -X POST "https://v3.recurly.com/purchases" \
  -H "Authorization: Bearer YOUR_SANDBOX_API_KEY" \
  -H "Accept: application/json" \
  -d '{
    "currency": "USD",
    "account": { "code": "acct-123" },
    "subscriptions": [ { "plan_code": "gold" } ],
    "gateway_code": "adyen_gateway_code"
  }'

Frequently Asked Questions

Can I use multiple gateways at once?

Yes. Recurly supports multiple active gateways per site. You can configure routing by currency, region, or manually per transaction.

Will my old transactions remain accessible?

Yes. Transaction and subscription history remains intact in Recurly regardless of gateway changes.

Can I migrate tokens myself?

No. Token migration must be coordinated through Recurly and both gateways to ensure PCI compliance.

What happens if a gateway is disabled before migration completes?

Recurring payments tied to that gateway will fail. Always complete migration and validation before removing the old gateway.

I'm migrating between Apple Pay or PayPal gateway instances — do I need to do anything special?

Yes. Because Recurly does not allow merchants to set a default gateway for Apple Pay or PayPal in the UI, you must use gateway routing to direct recurring transactions to the correct gateway instance. Set up your routing rules before beginning the migration to prevent billing disruptions for existing subscribers.

Resources

Using Multiple Payment Gateways in Recurly