{"__v":5,"_id":"5666328b2342100d007dcbf7","category":{"__v":29,"_id":"5665dfa0e93ae70d00b96a2a","pages":["5665dfca1b6559190020ae7d","5665e000e93ae70d00b96a2c","5665e0a9e93ae70d00b96a32","5665e0c7d8a06b170063f311","5665e12bd7490819006a503f","5665e1431b6559190020ae86","5665e16f63109d0d0036ba19","5665e192b6c0f60d00eae53d","5665e29ed8a06b170063f315","5665e2b9d7490819006a5044","566630b03360850d00336cb6","566631547cc81e0d00253f1a","566631b38744940d004c3eff","5666328b2342100d007dcbf7","566729ab5d00370d00ede6c2","56672a86f672550d0008523a","56672fd9ee53940d00516267","5667335f5d00370d00ede6db","566735cf6819320d000c2f05","5667362b32dd550d00f3924b","5667373d6819320d000c2f0a","566737c232dd550d00f3924e","5667380ad784a70d00397ce1","56673ee86819320d000c2f1b","56673f95ee53940d0051629d","56673feed784a70d00397cec","5667431e66debc1700503f6a","5667436d66debc1700503f6d","566745066819320d000c2f3d"],"project":"56450a342229d7170010928a","version":"56450a342229d7170010928d","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-07T19:36:00.783Z","from_sync":false,"order":2,"slug":"configuration","title":"Configuration"},"parentDoc":null,"project":"56450a342229d7170010928a","user":"55648cf93b87582b003ab8b1","version":{"__v":9,"_id":"56450a342229d7170010928d","project":"56450a342229d7170010928a","createdAt":"2015-11-12T21:52:52.685Z","releaseDate":"2015-11-12T21:52:52.684Z","categories":["56450a352229d7170010928e","56450a472c74cf1900da48ca","565def2677f0090d005819bb","5665dfa0e93ae70d00b96a2a","5665e3db1b6559190020ae8c","5665e47763109d0d0036ba5a","5690123f18c3920d00be8b1c","56944016d8c04d1700e5ae20","569447891005590d0062cace"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"createdAt":"2015-12-08T01:29:47.482Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":25,"body":"## Retry Schedule\n\nWhile an invoice is past due and in the dunning process, Recurly automatically attempts to collect the invoice using the optimal retry strategy for the payment type and error. **This process is not customizable.** However, you can control the communications that your customers receive. For more information on that, please see the [Customer Communication section][1].\n\n[1]: #section-customer-communication\n\n### Customer Payment Issues\n\n- ####Insufficient Funds\nEvery 7 days\n- ####Exceeds Daily Limit\nEvery 3 days\n- ####Call Issuer\nEvery 3 days\n- ####Temporary Hold\nEvery 6 days\n- ####Generic Declines\n Retry every 3-5 days, based on dunning length\n- ####PayPal Decline\nEvery 6 days\n- ####Hard Decline (Will Never Succeed)\nNever. Hard declines, such as customer closing their account, cannot be resolved immediately; and subsequent attempts with the same payment method will not succeed\n\n### Gateway Payment Issues\n\n- ####Try Again/Gateway Error\nEvery 2 days\n- ####Issuer or Gateway Unavailable\nEvery 3 days\n- ####Communication/Configuration Error\nFirst retry up to 2 times, 4 hours apart\nNext retry up to 6 times, 1 day apart\nFinally retry through end of dunning cycle, 3 days apart\n\n\n## Maximum Retries\nThe transaction retry attempts on an invoice will stop after 12 transaction declines from the payment gateway, 20 total transaction attempts (including gateway unavailability), or 60 total days since the invoice creation date.\n\n\n## Configuration\n\nDunning preferences can be accessed in your account's Configuration panel. On this page, admins can change the failed payment notification intervals, number of notification attempts and the desired end-result when payment is unsuccessfully collected.\n\n\n## Customer Communication\n\nIn the process of dunning an account, Recurly can send several emails to your customer notifying them of failed payment and any subsequent subscription changes due to non payment:\n\n1. First, Recurly will send a \"Payment Declined\" email letting the customer know their payment failed, and prompting them to update their billing information.\n\n2. Recurly will then retry the payments and send the appropriate notification emails (depending on the outcome) based on your dunning management settings.\n\n3. If the customer does not respond to these emails by updating their billing information, Recurly sends a \"Subscription Canceled Nonpayment\" email letting them the customer know their subscription has been terminated for non-payment. This ends their subscription immediately.\n\n### Customizing Customer Communication\n\nYou must have Configuration permissions to perform this task.\n\n1. Navigate to your [Dunning Management][2] page.\n\n2. Adjust the number of emails you'd like your customers to receive by pressing the + and - buttons.\n\n3. Adjust the number of days in between emails. The total number of days should be fewer than your shortest billing cycle length.\n\n4. Choose an outcome if the payment fails at the end of the dunning cycle. You may either expire the subscription, or leave it active.\n\n[2]: https://app.recurly.com/go/configuration/dunning\n\n## Webhooks\n\nWebhooks can be used to keep your service synchronized with payment issues inside of Recurly.\n\n- ####Failed Payment\nSent after each failed payment. Recurly merchants use this push notification to flag a user as past-due inside their application and encourage them to update payment information.\n- ####Successful Payment\nSent after a successful payment. Recurly merchants use this push notification to recognize when a previously past-due user is now back in good standing.\n- ####Subscription Expired\nSent if Recurly terminates a subscription due to non-payment or if the subscription is canceled and no longer valid. When this notification is received, the subscription should be immediately terminated in your system. This is the primary notification you should catch if you are receiving push notifications.\n\n## Updating Billing Info\n\n[3]: https://dev.recurly.com/docs/list-accounts\n\nWhen your customers receive a failed payment email, they need to know how to update their billing information. The default payment declined email template offers your customers a direct link to their hosted account management page, where the customer can provide updated billing information.\n\nYou can include a direct link to a customer's account management page from your website using the `hosted_login_token` parameter available on the [Accounts API][3]. API users can also update the email template to point to a billing update form on their own website.\n\n## Manual Retry/Force Collection\n\nA forced collection attempt can occur at any time by clicking the **Collect Now** button on an open invoice\n\n## Stop Dunning\n\nThe dunning process can be halted on an account by opening the past due invoice, clicking on the **Stop Collection** tab, and selecting either the **Stop Collecting** option, which will mark the invoice as failed, or the **Mark Paid** option, which will indicate that the invoice was successfully paid for (this option is typically used when funds are received outside of Recurly).\n\nEither option will move the invoice to a **Closed** state and will stop all future collection attempts on the invoice.\n\nPlease Note: Stopping collection on an invoice *will not* automatically cancel the related subscription. The subscription needs to be canceled separately in order to stop the subscription from renewing again.\n\nA subscription will only be canceled automatically if an invoice fails dunning (assuming your dunning settings are configured to expire a subscription at the end of the dunning process).\n\n## Reopening Invoices and Dunning\nUsers with permissions to edit the Customer section have the option to reopen failed manual invoices. If a failed manual invoice is reopened, dunning will not restart (no dunning emails will be sent) and the associated subscription will not be effected. When a manual invoice is reopened, it will remain in an Open state indefinitely until it's closed and marked paid/failed.\n\n##Test Dunning Behavior\nMerchants wanting to speed up the dunning behavior to test webhooks, delivery of email, and other variables may follow the below instructions to put an account through dunning in **sandbox** mode.\n1. Subscribe an account using the \"Success\" test card number: 4111-1111-1111-1111\n2. Update the account's billing information to use the \"Fail, but save\" test card number: 4000-0000-0000-0341 (note: it will appears this action returns an error, but this is expected. The card number will still save on the account).\n3. Speed up the renewal process by clicking \"More info\" on the subscription, then \"Change Renewal Date\" on the subscription details page\n4. Set the subscription's next renewal date 1 hour in the future\n5. The subscription will renew within the hour, kicking off your dunning process.","excerpt":"When a customer's payment fails, Recurly kicks off a process called dunning management (Delinquent User Notification). This process involves user communication, payment reconciliation, and payment retries.","slug":"dunning-management","type":"basic","title":"Dunning Management"}

Dunning Management

When a customer's payment fails, Recurly kicks off a process called dunning management (Delinquent User Notification). This process involves user communication, payment reconciliation, and payment retries.

## Retry Schedule While an invoice is past due and in the dunning process, Recurly automatically attempts to collect the invoice using the optimal retry strategy for the payment type and error. **This process is not customizable.** However, you can control the communications that your customers receive. For more information on that, please see the [Customer Communication section][1]. [1]: #section-customer-communication ### Customer Payment Issues - ####Insufficient Funds Every 7 days - ####Exceeds Daily Limit Every 3 days - ####Call Issuer Every 3 days - ####Temporary Hold Every 6 days - ####Generic Declines Retry every 3-5 days, based on dunning length - ####PayPal Decline Every 6 days - ####Hard Decline (Will Never Succeed) Never. Hard declines, such as customer closing their account, cannot be resolved immediately; and subsequent attempts with the same payment method will not succeed ### Gateway Payment Issues - ####Try Again/Gateway Error Every 2 days - ####Issuer or Gateway Unavailable Every 3 days - ####Communication/Configuration Error First retry up to 2 times, 4 hours apart Next retry up to 6 times, 1 day apart Finally retry through end of dunning cycle, 3 days apart ## Maximum Retries The transaction retry attempts on an invoice will stop after 12 transaction declines from the payment gateway, 20 total transaction attempts (including gateway unavailability), or 60 total days since the invoice creation date. ## Configuration Dunning preferences can be accessed in your account's Configuration panel. On this page, admins can change the failed payment notification intervals, number of notification attempts and the desired end-result when payment is unsuccessfully collected. ## Customer Communication In the process of dunning an account, Recurly can send several emails to your customer notifying them of failed payment and any subsequent subscription changes due to non payment: 1. First, Recurly will send a "Payment Declined" email letting the customer know their payment failed, and prompting them to update their billing information. 2. Recurly will then retry the payments and send the appropriate notification emails (depending on the outcome) based on your dunning management settings. 3. If the customer does not respond to these emails by updating their billing information, Recurly sends a "Subscription Canceled Nonpayment" email letting them the customer know their subscription has been terminated for non-payment. This ends their subscription immediately. ### Customizing Customer Communication You must have Configuration permissions to perform this task. 1. Navigate to your [Dunning Management][2] page. 2. Adjust the number of emails you'd like your customers to receive by pressing the + and - buttons. 3. Adjust the number of days in between emails. The total number of days should be fewer than your shortest billing cycle length. 4. Choose an outcome if the payment fails at the end of the dunning cycle. You may either expire the subscription, or leave it active. [2]: https://app.recurly.com/go/configuration/dunning ## Webhooks Webhooks can be used to keep your service synchronized with payment issues inside of Recurly. - ####Failed Payment Sent after each failed payment. Recurly merchants use this push notification to flag a user as past-due inside their application and encourage them to update payment information. - ####Successful Payment Sent after a successful payment. Recurly merchants use this push notification to recognize when a previously past-due user is now back in good standing. - ####Subscription Expired Sent if Recurly terminates a subscription due to non-payment or if the subscription is canceled and no longer valid. When this notification is received, the subscription should be immediately terminated in your system. This is the primary notification you should catch if you are receiving push notifications. ## Updating Billing Info [3]: https://dev.recurly.com/docs/list-accounts When your customers receive a failed payment email, they need to know how to update their billing information. The default payment declined email template offers your customers a direct link to their hosted account management page, where the customer can provide updated billing information. You can include a direct link to a customer's account management page from your website using the `hosted_login_token` parameter available on the [Accounts API][3]. API users can also update the email template to point to a billing update form on their own website. ## Manual Retry/Force Collection A forced collection attempt can occur at any time by clicking the **Collect Now** button on an open invoice ## Stop Dunning The dunning process can be halted on an account by opening the past due invoice, clicking on the **Stop Collection** tab, and selecting either the **Stop Collecting** option, which will mark the invoice as failed, or the **Mark Paid** option, which will indicate that the invoice was successfully paid for (this option is typically used when funds are received outside of Recurly). Either option will move the invoice to a **Closed** state and will stop all future collection attempts on the invoice. Please Note: Stopping collection on an invoice *will not* automatically cancel the related subscription. The subscription needs to be canceled separately in order to stop the subscription from renewing again. A subscription will only be canceled automatically if an invoice fails dunning (assuming your dunning settings are configured to expire a subscription at the end of the dunning process). ## Reopening Invoices and Dunning Users with permissions to edit the Customer section have the option to reopen failed manual invoices. If a failed manual invoice is reopened, dunning will not restart (no dunning emails will be sent) and the associated subscription will not be effected. When a manual invoice is reopened, it will remain in an Open state indefinitely until it's closed and marked paid/failed. ##Test Dunning Behavior Merchants wanting to speed up the dunning behavior to test webhooks, delivery of email, and other variables may follow the below instructions to put an account through dunning in **sandbox** mode. 1. Subscribe an account using the "Success" test card number: 4111-1111-1111-1111 2. Update the account's billing information to use the "Fail, but save" test card number: 4000-0000-0000-0341 (note: it will appears this action returns an error, but this is expected. The card number will still save on the account). 3. Speed up the renewal process by clicking "More info" on the subscription, then "Change Renewal Date" on the subscription details page 4. Set the subscription's next renewal date 1 hour in the future 5. The subscription will renew within the hour, kicking off your dunning process.