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

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.

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.

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.

Resources

Using Multiple Payment Gateways in Recurly