Overview

Recurly Recover turns on Recurly Wallet for every site by default, so you can store one or many payment methods on a recovery invoice. A customer with a single card on file is exposed to any decline — an expired or reissued card, or even a temporary hold, can stall an invoice's recovery. Adding a backup method closes that gap.

Best practices

• Encourage customers to add a second payment method proactively — at signup or in account settings, not just after a failed charge. When you send recovery invoices to Recurly, include every method so we can retry against any the customer has provided.
• Favor variety over duplicates — an Apple Pay token built on the same card number (PAN) adds little protection. A different card network, or PayPal backed by a bank account or PayPal balance, is far more resilient.
• Keep backup methods current — expired or removed backups give no real coverage. When a customer adds a new method to your wallet system, pass that detail to Recurly, and periodically nudge customers to remove expired or unused cards.
• Be transparent that a backup may be charged if the primary fails — so a successful backup charge is never a surprise
• Let customers pick their preferred primary — some want control over which method absorbs a failed charge. Use Recurly Wallet's primary and backup designations to mirror those preferences.

Set up for success

To get the most out of multiple payment methods, make sure the following are in place before you send recovery invoices.

Validate your gateway tokens

Make sure you have a gateway token for each payment method, with the correct gateway_code matched to that token's gateway. Gateway tokens are usually tied to a specific gateway account (with few exceptions), so a mismatched code can cause an error. To retry the same payment method across more than one gateway, include a token for that method for every gateway you want us to attempt — and add each of those gateways to your site. Depending on the gateway, you may also need to provide the expiration date and the Network Transaction ID (NTID) you keep on file for the customer's subscription.

Enable token backfilling

If you don't have the metadata (first six, last four, and card brand) for your tokens, Recurly can query your gateway for up-to-date card brand, BIN, and expiration data when the gateway requires it for processing. In some cases you'll need to enable specific permissions at the gateway level for this to work.

Follow the guide for your use case

Your exact setup depends on whether your payment methods live on one gateway or several. Follow the guide that matches your use case: