Prerequisites

• Access to the Recurly Payment Gateway Configuration page.
• An active Stripe account (existing or newly created).
• When using Gateway Failover, currencies and card types must match across both Stripe and Recurly.

Limitations

• Billing info changes don't sync to Stripe — Updates to billing information in Recurly do not automatically reflect on Stripe customers. Manual updates are required for direct Stripe payments.
• Manual customer lookup required in Stripe — When processing payments directly in Stripe, you'll need to manually search for the most recent Stripe customer record.

Definition

Key details

Integrate Stripe with Recurly

Step 1: Confirm your Stripe account eligibility

Verify your business is eligible to process on Stripe. Review Stripe's restricted businesses list — if your business appears there, you won't be able to use the Stripe gateway.

Step 2: Open Payment Gateway Configuration

In Recurly, navigate to Configuration → Payment Gateways → Add Payment Gateway.

Step 3: Select Stripe

Choose Stripe from the list of available gateways. Stripe uses OAuth authentication — you won't need to copy or paste API keys.

Step 4: Log in or create your Stripe account

You'll be prompted to log in with your Stripe credentials or create a new account. Follow the prompts to authenticate.

Step 5: Configure gateway settings

After authenticating, you'll be redirected to Recurly to finish configuration:

• Exclude this instance from Gateway Failover (if applicable)
• Enable Alternative Payment Methods (Apple Pay, Google Pay)
• Set currency preferences

Step 6: Review Gateway Failover settings

If you plan to use Gateway Failover, confirm that supported currencies and card types match in both Stripe and Recurly.

Step 7: Enable payment methods

Enable payment methods in your Stripe Dashboard. If you're using Stripe Elements, only enable methods that Recurly supports (see Key details above). Enabling an unsupported payment method will cause payment failures.

Step 8: Test and go live

Test the integration in Recurly's development environment to confirm everything works as expected, then switch to production to begin processing live transactions.

Authorization and capture

Stripe supports Recurly's Auth and Capture feature, which pre-authorizes funds before capturing them — confirming availability without completing the charge immediately. See the Auth and Capture documentation for details.

Stripe webhook behavior

Recurly supports several Stripe webhook event types automatically. No additional configuration is needed in your Stripe dashboard — contact your Recurly representative to enable the relevant feature flag.

Payment method and customer token lifecycle

• Payment Method Detach — If a payment method token is deleted in the Stripe Dashboard, Recurly disables the associated billing info. Active subscriptions will enter dunning if no other payment method is on file.
• Customer Deletion — Deleting a Stripe Customer in the Stripe Dashboard removes all associated payment methods at Stripe, with the same dunning effect as a Detach event.
• Payment Method Update — If a token attribute such as an expiration date is updated in the Stripe Dashboard, Recurly automatically updates the billing info on file.
• Account Updater — If you use Account Updater at Stripe, Recurly consumes those events to keep gateway tokens in sync automatically.

Transaction lifecycle

• Expired Authorization — Uncaptured authorizations expire after 7 days. Recurly updates the authorization to Void status and it can no longer be captured.

• Hard Decline — In certain cases, Stripe may update a charge with new retry advice. When Stripe deems it necessary, Recurly will stop retries on a previously soft-declined transaction.

• Chargeback Dispute — If you receive a card chargeback and have the early access Chargeback Management feature enabled, Refund Invoices with an origin of Chargeback will appear in your Recurly dashboard. Affected subscriptions can be automatically expired depending on your settings.

• Radar Review — If you configure "review" rules in Stripe Radar, Recurly returns approved_fraud_review responses via API when those rules trigger. When Stripe Webhooks are enabled for Recurly (contact Recurly Support), closing a review triggers the following actions:

  • Closed with reason canceled → Recurly automatically voids pending auths or voids/refunds purchases.
  • Closed with reasons approved, redacted, or acknowledged → Recurly takes no action.

  See Stripe's review documentation for more details.

India mandates with credit cards

Recurly supports creating e-mandates for recurring transactions for customers located in India, in compliance with RBI regulations. See the India e-mandates integration guide for full implementation details.

Integration style

All CIT/subscription signups for Indian customers require 3DS. Combine subscription creation and customer interaction into a single step — do not add billing info via verification and set up the subscription in two separate steps.

Public Preview status

India e-mandates are in Public Preview at Stripe. Unintended issues may arise before the implementation is fully stable. Contact Recurly Support to escalate any issues.

Single subscription per account

E-mandates are stored at the Customer Account level in Recurly. Only one active subscription is permitted per account for Indian customers — adding multiple subscriptions risks invalidating older ones.

Single plan per transaction

To avoid renewal declines and mandate cancellations, use a single plan per invoice. Multiple subscriptions on a single transaction can result in renewal failures.

Asynchronous transactions

Due to the pre-renewal notification requirement in India, e-mandate transactions enter a Scheduled state with a Pending invoice for up to 26 hours after submission to Stripe. During this window, customers receive a notification via their banking app to approve or decline the mandate or payment. Use payment and invoice webhooks to listen for status updates.

Automatic subscription cancellations

If a customer cancels their mandate through their banking app, Recurly may receive a cancellation indicator on the next renewal attempt and will cancel the subscription immediately. Work with the customer to update their payment method, or revoke service access in your environment as needed.

Billing country requirements

Send the customer's full billing address including country code (IN) to trigger an e-mandate correctly. Without the India country indicator, Recurly may not request a mandate from Stripe and renewals will likely fail.

Webhook requirements

Async payments require Stripe webhook support on your Recurly site. Contact Recurly Support to enable async status updates for Stripe. See Stripe webhook behavior above.

Mandate amounts

Mandate amounts are calculated from your plan amount plus taxes, plus an 18% buffer to allow for plan amount changes over the subscription lifetime. Discounts are not factored in to avoid undervaluing the mandate.

Customer interaction indicator

When a transaction is in a Scheduled state, the Recurly UI shows a customer interaction indicator — this tells you whether the customer needs to act in their banking app and by when. Subscriptions can be marked as failed if customers don't respond in time.

3DS requirement

RBI requires 3DS for all customer-in-session payments including subscription signups and one-time transactions. If a renewal triggers a 3DS verification response, ensure the 3DS Dunning Email is enabled and a valid customer email address is on file. 3DS on Stripe requires a Recurly.js integration — see the 3DS implementation guide if you haven't integrated yet.

Ongoing maintenance

Keep billing information current in Stripe

Billing info changes in Recurly do not automatically sync to Stripe. Regularly update customer records in Stripe to ensure direct payments process correctly.

Monitor parity between Stripe and Recurly

Maintain matching currency and card support settings in both platforms to avoid payment disruptions. This is especially important when using Gateway Failover.

Monitor your Stripe Dashboard

Review your Stripe transactions regularly. Stripe may send transaction notices that Recurly doesn't receive. Recurly also sends metadata to Stripe that is visible in the Dashboard.