Recurring Payments and Dunning for Perfex CRM

Perfex creates the invoice. It does not take the money.

Perfex CRM’s own documentation says it plainly: a recurring invoice is used only to re-create
the invoice on a specific date. The document goes out on schedule, correctly numbered, with the
right items on it – and then nothing happens. No card is charged. No mandate is debited. Somebody
in your office still opens the list every month, works out who has not paid, and writes the
emails.

This module is the other half. Your customer authorises a card or a bank debit once, from your
own client portal. After that, when Perfex generates the recurring invoice, the money is
collected automatically – and when a charge fails, a dunning engine works the decline until the
money arrives or you decide to stop.

Dunning is the automated sequence of retries and emails that chases a payment which failed.
It is the part no option inside Perfex covers today – see the table below – and it is where the
money is.

Stripe, in its own engineering post on Smart Retries, writes: “Twenty-five percent of lapsed
subscriptions are purely due to payment failures.” Recurly’s published churn benchmarks put the
overall churn rate at 3.60%, of which 1.25 points are involuntary – revenue lost to a card that
failed rather than to a customer who decided to leave – and Paddle puts involuntary churn at
20-40% of overall churn. That share is what a dunning engine exists to win back.

It is worth winning back, and the timing is most of the job. Recurly reports that 90% of
recovered transactions occur within the first 10 days of a failed payment. Baremetrics,
measuring over a million dunning emails sent by its Recover customers, puts recovery at 13.25%
for the email sent the day the payment fails, against 4.22% for the one sent on day 15; across
almost 300,000 pre-dunning emails, the notice sent 30 days before a card expires recovers
14.37% – the best result in the set, because it arrives before anything breaks. And Recurly,
analysing one enterprise merchant’s failed transactions, found that merchant’s existing retry
logic recovering roughly 53% of eligible failures, and optimised retry timing reaching roughly
71% on the same transactions.

Every figure above is another vendor’s, measured on that vendor’s own network and published on
that vendor’s own site. This module ships the machinery those figures describe – a retry
schedule you set, decline classification, an escalating email sequence and a card-expiry
warning – inside Perfex. It does not promise you their recovery rates.

This is a module for Perfex CRM, not a standalone script

You need a licensed, working Perfex CRM 3.4.x installation, sold separately. This module
installs into it under Setup > Modules and adds one sidebar section. It modifies no core file,
and it uninstalls cleanly.

This is an independent third-party module. It is not published by, affiliated with or endorsed
by the authors of Perfex CRM, and it is not affiliated with Stripe, GoCardless or Paystack.

What Perfex already does, and what this adds

Every row below is a statement about published behaviour or shipped code, and every one can be
checked.

</thead>
<tbody>

</tbody>

If the description editor strips the table, use this instead:

Perfex core re-creates the recurring invoice and can send an overdue reminder; it never
charges anything. Perfex’s built-in subscriptions do charge, but only through Stripe, only for
plans you create in the Stripe Dashboard, with no trial support and no retry logic of their
own. The free Perfex payment-gateway modules on GitHub are on-session gateways: they run when
a customer clicks Pay and cannot charge anybody afterwards. This module charges a stored
authorisation off-session against your own Perfex invoices, on three rails, and then works the
decline.

A note on Stripe’s own retries. Stripe’s Smart Retries applies to Stripe’s own invoices and
subscriptions. A plain payment intent raised against a CRM invoice is never retried by Stripe.
That is precisely the case this module covers.

How this differs from the other paid modules you will find

Perfex CRM has over 25,000 installations, and there is already a paid module for almost every
individual piece of the recurring-money problem: reminder emails before a renewal, a single
direct-debit rail, a prepaid customer wallet. Three of them are worth naming, so you can tell
which one you actually need – and so you can see what none of them does.

Products and services for Perfex CRM ($39) lets you sell products and services as Stripe
subscriptions and sends renewal notification emails 7, 30 and 60 days ahead. If a heads-up email
before renewal is what you are missing, that item is cheaper and it does that. What it does not
carry is retry logic: when the payment fails, the sequence ends. This module starts there.

GoCardless Payment Gateway ($49) adds GoCardless to Perfex and can set up a GoCardless
subscription that debits on its own schedule. If every one of your customers pays by UK or EU
bank debit and you never touch a card, that covers the collection. What it is not is a
multi-rail engine: the recurring schedule lives at GoCardless rather than against your Perfex
invoices, there is no card rail beside it, and there is no decline classification, dunning
sequence, MRR reporting or client-portal method management around it. Here GoCardless is one of
three rails, the schedule is your Perfex invoice, and the recovery layer is the product.

Wallet Module ($49) gives each customer a prefunded balance inside Perfex and settles their
recurring invoices from it automatically. For customers who are happy to keep a deposit with
you, that is a simpler answer than anything here. But the money has to be in the wallet already –
somebody topped it up. There is no card vault behind it, no gateway retry and no decline
handling, because there is no gateway in the loop. This module takes money the customer has not
pre-paid, from their bank or their card, and handles it when that fails.

One more thing worth knowing. When a customer pays a Perfex invoice through the built-in
Stripe gateway, Perfex already asks Stripe to keep that card for future off-session use. The
authorisation is sitting there. Nothing in Perfex ever charges it again. This module is the part
that does.

Features

Collecting the money

• Two modes, both usable on the same install.
  Auto-charge a recurring invoice – Perfex keeps generating its recurring invoices exactly as
  it does today, with your numbering and your items, and the module collects each one the moment
  it appears. Subscription plan – the module owns the clock, builds the period’s invoice from a
  plan you defined, then charges it.
• One switch for everything. Turn on Auto-charge every recurring invoice and any customer
  with a saved default payment method is collected automatically, with no subscription to create
  by hand.
• Charges at a sensible hour. Collections are placed at a configurable local hour (2 a.m. by
  default) in the subscription’s own timezone, which is what card issuers expect from a
  subscription merchant.
• Respects part payments. A retry collects what is still owed, never the original amount
  again.
• Charge now, from the subscription screen, behind its own staff permission – with an honest
  message when the engine refuses rather than a claim that money moved.
• The invoice is never edited. The document exists and carries its final number before any
  money is requested, and a decline never modifies it. That immutability is what makes retries
  safe.

Three payment rails

• Stripe – cards worldwide. Capture through Stripe Checkout, off-session charging, 3-D
  Secure recovery links, and handling for cards the network updates automatically.
• GoCardless – bank debit through the Billing Request Flow (Bacs, SEPA and the other schemes
  GoCardless selects from the payer’s country). Settlement is recorded from the confirmation
  webhook, not at submission.
• Paystack – card authorisations for Nigeria, Ghana, South Africa and Kenya.
• Each rail has its own webhook endpoint, its own signature verification and its own event list.
  Credentials are entered once as encrypted Perfex gateway settings.
• Currency handling that is actually right: zero-decimal currencies sent as whole units,
  three-decimal at x1000, everything else at x100, always rounded rather than truncated.
• Run two rails side by side – Stripe for international customers, GoCardless for domestic ones.
  Each saved method carries its own gateway, and the module always charges the one that customer
  actually authorised.

When a payment fails

• A decline classifier that reads the gateway’s advice code first and the decline code
  second. A soft decline (insufficient funds, issuer unavailable, processing error) is
  retried on your schedule. A hard decline (lost or stolen card, revoked authorisation,
  incorrect number) is never retried – the card networks bill per attempt and issuers read
  repeated retries as fraud probing. An authentication failure gets a confirmation link
  instead of a blind retry. A dead mandate stops collection and asks for re-authorisation. And
  when the failure is your own misconfiguration – wrong API key, currency not enabled – your
  staff are told and the customer is never dunned for it.
• Dunning policies you edit: retry days, email days, maximum attempts, a give-up day, the
  charge hour, staff notification, and a terminal action (mark past due, pause, cancel, or stop
  billing and ask a human about portal access).
• A live preview that re-draws the whole timeline from the values in the form before you
  save, and warns you about the mistakes that are invisible when the three limits are read
  separately – retries planned beyond the attempt cap, steps falling after the give-up day, no
  retry days at all, no email days at all.
• Every offset is measured from the first failure, never from whenever the last cron run
  happened. A missed day does not stretch a 14-day sequence into a month.
• Each step is claimed before it is sent. A customer can never receive the same dunning step
  twice, however often the cron runs, and after an outage only the latest due step is sent
  rather than three landing in the same minute.
• A velocity ceiling no policy can raise: 8 attempts per stored instrument per 14 days,
  across all invoices. Past that the module stops and asks you to speak to the customer.
• Card-expiry warnings on your own notice days (30 and 7 by default) – the cheapest recovery
  is the one that costs no failed charge at all.
• Any payment recorded against the invoice by any route – the module, the customer’s own Pay
  button, or your staff typing it in – closes the open dunning, stands down the queued retries,
  and puts a past-due subscription back to active.

Emails your customers actually get

Eight Perfex email templates, seeded into Setup > Email Templates and editable exactly like any
other: three failed-payment notices, card expiring, payment authentication required, receipt,
payment authorisation cancelled, and an upcoming-payment notice. Merge fields cover card brand,
last four digits, amount due, retry date, decline reason, the update-card link and the
confirm-payment link. Customers see plain-language decline reasons, never the gateway’s raw
error text, and a placeholder that cannot be resolved is stripped rather than shown.

What your customers can do themselves

• A Billing & Cards page in the client portal: their subscriptions, their saved payment
  methods with brand, last four and status, a past-due banner, and add / replace / remove.
  Replacing a card moves every live subscription onto the new one – “update card” actually
  changes what gets charged.
• A self-service subscription page reachable without a login, authorised by the
  subscription’s own hash: pause for up to three months, resume, or cancel. Cancelling always
  passes a retention step first, and a customer-initiated cancellation always takes effect at
  the end of the paid period – they keep what they paid for and nothing further is charged.
• A 3-D Secure confirmation page, also without a login, on a single-use expiring token that
  is stored hashed. Unknown, expired and already-used links all return the same neutral page, so
  the endpoint cannot be used to probe for valid tokens.
• A read-only payment history, shown only to contacts who hold the Perfex invoices
  permission.

Knowing where you stand

• A dashboard that answers three questions: how recurring revenue is doing, what needs a human,
  and whether the machinery is running.
• MRR (monthly recurring revenue – what your live subscriptions are worth in a month; a
  yearly plan of 1,200 counts as 100) and ARR, taken as a daily snapshot, one row per
  currency, never converted and never added together. No FX is performed, and a single blended
  total would be a fiction.
• Churn (subscriptions that ended in the period and the monthly revenue that left with them)
  and involuntary churn – the customers you lost to a payment failure rather than to a
  decision, which is exactly what dunning exists to prevent.
• Recovered this month: payments that only succeeded because an earlier attempt had failed.
• MRR movement over 12 months – new, expansion, contraction, churned – reconciling exactly.
• Success rate per gateway, with in-transit and awaiting-customer attempts counted but kept
  out of the ratio, so a bank-debit rail does not read as broken.
• Top decline reasons and cohort retention by signup month.

Running it

• Eight admin screens: Dashboard, Subscriptions, Plans, Payment Methods, Charge Attempts,
  Dunning, Reports and Settings.
• Seven staff capabilities, including separate ones for viewing stored payment methods and for
  manual collection.
• A Diagnostics screen built to answer “why did nothing get charged?” – per-gateway
  configuration and webhook state, the webhook URL to register, the age of the last cron run,
  all eight cron jobs with their last error, unprocessed events, stuck attempts, and
  subscriptions waiting for a payment method. API keys are never decrypted or printed, so the
  screen is safe to screenshot.
• Cron health on the dashboard, with a red banner and a staff notification when the cron has
  been silent longer than your threshold.

Built so it cannot charge twice

Five independent guards, all enforced by the database rather than by hopeful code: a single-flight
lock around the cron; deterministic idempotency keys (never random ones), so a repeated charge
makes the gateway replay its original answer instead of taking money again; one attempt row per
invoice and attempt number; the gateway transaction claimed before any payment is written into
Perfex; and webhook de-duplication on the gateway’s own event id. On top of that the module asks
Perfex’s own ledger whether that transaction already exists on the invoice.

Card data never reaches your server

Card numbers are entered on the payment provider’s own page and go straight to the provider.
Your server holds the token, the brand, the last four digits and the expiry – nothing PCI DSS
treats as in scope. There is no card field anywhere in this module, deliberately not in the
admin area either: your staff should never be in a position to type a customer’s card number
into your CRM. The consent your customer gives is recorded with its timestamp, IP address,
browser and a snapshot of the exact wording, so you can evidence it later.

And the housekeeping

• Multi-tenant safe: every table name goes through Perfex’s prefix helper, the installer is
  idempotent, settings live in the options table rather than on disk, and email templates are
  seeded per tenant database.
• No licence call at all. An offline format check on your purchase code, and nothing
  outbound – a network problem can never stop your invoicing.
• Deactivating is safe: charging stops, data is untouched, and webhook endpoints answer 503
  so gateways re-deliver rather than dropping events. Reactivating creates no duplicates.
• Uninstalling keeps your data by default. Dropping the tables is an explicit opt-in you set
  before you remove the module. Perfex invoices and payments are never touched.
• Deleting a client cancels their subscriptions, detaches each stored token at the gateway, and
  removes the local rows.

What version 1.0 does not do

Stated here rather than discovered after you buy.

• Three gateways only – Stripe, GoCardless and Paystack. There is no PayPal and no Razorpay
  integration. Your existing Perfex gateways keep working for manual, on-session payments; they
  simply cannot be charged off-session by this module.
• No automatic late fees. A fee would have to modify an invoice that already carries its
  final number, which is unacceptable in most tax jurisdictions. The policy screen carries the
  fields for a later release; version 1.0 never applies one.
• GoCardless advance notices are sent by GoCardless, not by this module, and its
  notifications must be left switched on. Bank debit schemes require the payer to be told before
  money is taken, and the “module sends it” option is visible but deliberately disabled so
  nobody can switch off the only notice being sent.
• GoCardless payments are never retried by the module. Re-submitting a mandate from our side
  would be a second collection, not a retry. GoCardless Success+ owns that; for GoCardless the
  email schedule is the whole recovery path.
• Flat pricing only on the plan screen. The engine already computes per-unit, tiered and
  metered pricing, and version 1.0 ships no screen for them. The same is true of coupons and of
  the plan flag “visible in client portal”.
• Customers cannot sign themselves up to a plan. Subscriptions are created by staff; the
  portal manages what already exists.
• Adding or replacing a stored card needs a client-portal login. Confirming a bank security
  check and managing a subscription do not.
• Reconciliation is a state sweep, not an API poll. Once a day the module finds charge
  attempts that never reached a final state and tells you; it does not query the three gateway
  APIs to compare balances. You resolve those from the gateway dashboard.
• No migration wizard from Perfex’s built-in Stripe subscriptions. Moving a customer across
  is a manual, documented procedure – and you must never run the same customer on both at once.
• English only. One language file ships, using Perfex’s own translation mechanism, so a
  translation drops in as an extra file.

Requirements

• Perfex CRM 3.4.x, licensed and working. Sold separately; this is a module, not a
  standalone script.
• PHP 8.1, 8.2, 8.3 or 8.4.
• The MySQL or MariaDB server your Perfex already runs on. Tables are created with your
  install’s own character set and collation.
• HTTPS, reachable from the public internet. Gateways will not deliver webhooks to plain
  HTTP, and card authorisation pages must not be reached over it.
• A working Perfex cron job. This is not optional and it is not a second cron – the module
  registers into the one you already run. Without it nothing is charged, no retry fires and no
  dunning email is sent. Cron health is on the dashboard, and you are notified when it goes
  quiet.
• Outbound HTTPS from your server to your gateway’s API. Locked-down hosting that blocks
  outbound connections cannot charge anything.
• Working email through Perfex’s own SMTP settings.
• A merchant account with at least one of Stripe, GoCardless or Paystack, with API keys.
  Each provider approves accounts on its own terms; approval, fees and any compliance
  requirement are between you and them.
• No PHP extensions beyond what Perfex itself requires. No core file is modified.

Demo

Demo: https://recurring.104.171.139.106.sslip.io/admin
Username: [email protected]
Password: RecurringDemo2026

Read-only account. Demo data resets nightly.

Documentation

Full documentation ships in the download as HTML and is published online: installation, cron
setup, per-gateway setup for all three rails, the two modes, dunning policy, the client portal,
PCI and data handling, a FAQ and the changelog.

Documentation: https://recurring.104.171.139.106.sslip.io/modules/autobill/docs/index.html

Support and updates

Item support is included for 6 months from the purchase date. That is Envato’s standard term,
and it is bundled in the price. At checkout you can add extended item support, increasing the
support period up to a maximum of 12 months from the date of purchase. Afterwards Envato sells
6-month extensions while your period is still running, and 6-month renewals once it has expired,
from your Envato Downloads page or this item page. Envato sets the eligibility rules and the
price – support is costed as a percentage of the item price, not by us.

What your support period covers. During it, we are available to:

• answer general questions about the module and how to use it;
• answer specific questions about its features and functionality, and explain the way it is
  designed – the two modes, dunning policy and retry schedules, the MRR rows, the cron job, and
  how the module talks to each of the three payment rails;
• take reported bugs and defects: report one, discuss it with us, and where a fix is appropriate
  we will issue it. A defect fixed in a general version update reaches every buyer, not just you;
• keep the module working with new Perfex releases and with gateway API and security changes,
  delivered as version updates available to all buyers.

Raise something while your support is valid and we see it through – even if the fix lands after
your support period has ended.

Before you write in, read the documentation in the download and check this item’s FAQ and
comments. Cron setup, API keys, webhook URLs and the per-gateway walkthroughs are all covered
there step by step, and you will have the answer faster than we can type it.

Response time. We aim to reply within one business day. It is an aim, not a guarantee:
response times vary with the volume of requests and with what is being asked, and a defect that
needs a fix, a test and a release can take days. Any extended break is announced on this item’s
Support and Comments tabs before it starts. Support runs through the item comments and the
contact form on our profile page.

What item support does not include. Envato’s Item Support Policy draws the line and we
follow it rather than invent our own:

• Customisation. Modifying or extending the module beyond the features, style and
  functionality described on this page.
• Installation. Item support does not include help to install the item on your server or on a
  CMS. Installing Perfex, uploading the module archive and adding the server cron entry are yours
  to do. We will answer your questions about how it is done – the documentation walks through all
  of it – but we do not do it for you.
• Your hosting, server environment or software. PHP settings, outbound HTTPS, SSL
  certificates, mail delivery, and whether your host will run cron every five minutes. Those sit
  with your host, not with the module.
• Anything not included in this download, including conflicts with other third-party Perfex
  modules. Test on a staging tenant first.
• Your gateway account. Its approval, fees, payout timing, and any compliance decision your
  gateway makes about your business.
• A modified module. Anything arising from editing the code – including self-hosting a
  gateway’s JavaScript, which changes your own PCI scope.

Installation and customisation are the two things buyers ask for most often that support cannot
cover. Ask us and we will quote them as private paid work, separately from the item. They are not
part of what you bought here.

Updates are free for the life of the item. Every buyer, supported or not, receives updates
that keep the module working as described and protected against major security issues, plus the
further improvements we release. New versions appear automatically on your Envato Downloads page.
Perfex has no auto-update mechanism for modules, so applying one is a download and an upload:
take the new archive from your Downloads page and upload it under Setup > Modules > Upload
Module. The module compares the version header and runs any migration needed. Your settings,
subscriptions, stored tokens and charge history are kept. A full changelog is published with the
documentation and ships in the download.

What is coming

Planned for future releases. None of it is in version 1.0, and no release dates are
promised – buy this for what is on the page above.

• Late fees, in a form that never edits an invoice already carrying its final number.
• More rails. PayPal and Razorpay were deferred rather than forgotten: each needs its own
  mandate model, and neither maps cleanly onto the stored-token, charge-off-session pattern the
  three shipped rails share. A half-built rail that silently fails to collect is worse than
  three that work.
• Usage-based and tiered pricing screens. The engine already computes them; there is no
  screen yet.
• Coupon screens, on the same footing.
• Customer self-signup to a plan from the client portal.
• A migration path from Perfex’s built-in Stripe subscriptions.
• Reconciliation that queries the gateway APIs rather than sweeping local state.
• More language files.