Unpaid subscription installment: reminders, deadline and decisions

An unpaid subscription installment follows a simple sequence at ChariPay: on the due date, your customer received a payment link for the period by email; until they pay it, they get a reminder every day with the same link, and no new period opens. The link stays payable for 14 days after the due date; once that deadline passes without payment, the subscription is canceled automatically and your server receives the subscription.canceled webhook. What is left to you: deciding what happens to the service, following up with the customer through your own channel if needed and keeping a clean accounting trail. This guide walks through each step, then your options.

What happens when an installment is not paid, step by step

ChariPay is a Moroccan payment platform, a PSP operated by Chari Money, a payment institution licensed by Bank Al-Maghrib. Its subscriptions run on payment links: on every due date, ChariPay generates a single-use payment link for the period and emails it to your customer, who pays it by card on the hosted payment page, with 3-D Secure. The full setup is described in subscriptions through the API. When that link is not paid, here is what happens, in order:

1. 1The installment link goes out by email. On the due date, the customer receives an email titled "Nouvelle échéance" (new installment), followed by the subscription's description, with the payment link for the period.
2. 2A reminder goes out every day. As long as the installment is unpaid, the customer receives an email titled "Rappel de paiement" (payment reminder) every day, with the same link.
3. 3No new period opens. While the installment remains unpaid, no new link is generated: the customer never piles up several overdue installments.
4. 4A declined attempt does not close the link. If the customer tries to pay and their card is declined, your server receives subscription.payment_failed; the link stays payable, and the customer can try again.
5. 5A payment settles the installment. As soon as the customer pays, your server receives subscription.payment_succeeded, and the subscription carries on.
6. 6Without payment within the deadline, the subscription is canceled. An installment's link stays payable for 14 days after the due date — or after it was sent, if it went out later. If it expires unpaid, the subscription moves to the canceled status (CANCELED) and your server receives subscription.canceled.

None of this requires action from you. It does leave decisions in your hands — about the service, the follow-up and the subscription itself — which the next sections cover.

The timeline of an unpaid installment

The deadline is counted from the due date, on the Africa/Casablanca time zone like the due dates themselves.

Example: for an installment due on the 5th, the customer receives the link on the 5th, then a reminder every day until they pay; the link stays payable until the 19th; if it is still unpaid when it expires, the subscription is canceled. A paid installment is signaled by the subscription.payment_succeeded event. Write this timeline into your procedures: it sets the pace of your own messages to the customer.

Before a real customer is involved, see in the portal what a subscription, its installments and its webhooks look like. Test mode opens as soon as your account is activated, with no approval to wait for: Start in test mode — three fields (name, work email, company), an activation link received by email to choose your password, then the portal, where you create your own test key after re-authenticating; the full key is shown only once. Pay with the test card 4918 9141 0719 5005, CVV 123, any future expiry date, 3-D Secure code 555: only this card is accepted, and no real money moves. Your business verification (KYB) runs in parallel and only gates the move to production. In test mode, create a subscription whose start date is today: the first link is created immediately and returned in currentCharge. Pay it with the test card — the subscription becomes active and subscription.payment_succeeded arrives — then, with a daily frequency (DAILY), leave the next day's installment unpaid and follow its state with GET /v1/subscriptions/{reference}/charges.

What your customer receives: the installment link and its reminders

Every email — the installment email and each reminder — carries the same payment link. It opens a ChariPay payment page where the customer pays the installment by card. Like any card payment, it goes through 3-D Secure authentication: the cardholder confirms with their bank. The subscription's description appears on every link and in the subject of the installment email: write it so the customer recognizes your service at a glance, "Pro plan — monthly" rather than an internal code.

The payment still has to be able to go through. If the customer's card is capped for online payments, or closed to them — many Moroccan cards are closed to online payment by default — their attempt is declined: you receive subscription.payment_failed, and the link stays payable. Your customer then needs to sort it out with their bank, or pay with another card, on the same link. Declines seen from the buyer's side, and what to do about each, are explained in card declined online; measuring failures on the merchant side is covered in 3-D Secure and success rates.

Your role at this stage: make sure the customer knows the link exists and that it really comes from you. A message of your own, signed with your brand (see the templates below), keeps them from ignoring it or mistaking it for a suspicious email.

What you see: statuses, installments and webhooks

During the deadline, the subscription's status does not change: it stays active — or not yet started (INCOMPLETE) if this is the first installment, since the first payment is what activates the subscription. The installment itself carries the unpaid state. In the portal, the Subscriptions page lists your subscriptions, their next due date and their status, and each subscription's record shows every installment sent with its state. Through the API, GET /v1/subscriptions/{reference}/charges lists the installments, most recent first, each with its status and its link (payUrl); the response to GET /v1/subscriptions/{reference} carries the current period's link in currentCharge. Three webhook events track a subscription's life:

No event is sent just because the due date passes: an installment is unpaid as long as you have not received subscription.payment_succeeded for its period. Three receiving rules prevent the classic mistakes. Route every event on the Chari-Event-Type header. Deduplicate on Chari-Event-Id, not on Chari-Webhook-Id — the latter identifies the delivery, not the event. And find the customer and the period through what every subscription event sends back: your metadata, unchanged, your subscription identifier (ExternalId) and the date of the period concerned (PeriodDate) — no need to guess from an amount or a delivery date.

Reply 2xx only once you have recorded the event and updated the customer record; delivery is at least once, sometimes out of order. Signature checks and replays are covered in getting your webhook integration right.

Your decisions: wait, follow up another way, pause, cancel

Automatic reminders do not take control away from you. Four decisions are available — pause, resume and cancel work from the subscription's record in the portal, or through the API:

The link to send again is the one in currentCharge, or the pending installment in the list of installments: it is the same as the one in the emails, and it can only be paid once. A customer who wants to pay with another card has nothing to change in the subscription: they enter the card of their choice on the link's page.

A pause acts on the future: it stops new links from being generated during a difficulty you have been warned about — a seasonal customer, a tight month. It does not replace a conversation with the customer about the installment already sent.

These decisions can be combined: you can let the deadline run while writing to the customer, then cancel if they ask you to. The matching calls — pause, resume, cancel, list of installments — are described in subscriptions through the API and in the Subscriptions module reference.

Cut or keep the service: your rule, triggered by webhook

ChariPay collects the money; the service you provide — access to software, a box shipment, entry to the gym — stays under your control. Set your rule in advance and wire it to webhooks, never to a redirect: the redirect says the buyer came back, not that the payment is secured. Each case has its own guide: SaaS billing in Morocco, subscription commerce and gym membership payments.

Three policies come up often:

The gradual and strict policies rely on your own calendar: your system knows each installment's date and notices that no subscription.payment_succeeded has arrived for that period. When you cancel yourself, from the portal or through the API, cut the service at the same time, without waiting for an event: the cancellation response already carries the CANCELED status. To restore the service, rely on subscription.payment_succeeded, which signals a paid installment. If the customer tells you they paid, check that the installment is paid — on the subscription's record in the portal, or through the API — before reopening access. After a cancellation, resuming the relationship takes a new subscription.

Write this rule into your subscription terms — what happens during the payment deadline, at cancellation, and how to come back — without promising timings that do not depend on you. A customer who knows the rule knows what to expect.

Following up on an unpaid installment: your message templates

The daily reminders do their job; a message from you, signed with your brand and sent through your usual channel, gives them context. Three messages to adapt:

A few days after the due date

Hi Salma, your subscription installment has not been paid yet. You received a payment link from us by email: just open it to pay by card. Can't find it? Reply to this message and we will send it again.

Before the deadline ends

Hi Salma, your installment is still unpaid today. The payment link you received by email stays valid until the 19th; after that, your subscription will be canceled. If your card is declined, your bank can open it to online payments, or you can pay with another card on the same link.

At cancellation

Hi Salma, since the payment did not go through, your subscription has been canceled and your access is suspended. If you would like to come back, reply to this message and we will set up a new subscription with you.

Three tips for adapting them: stick to your service rule (do not mention a suspension if you keep access open), stay factual — a declined card is not a fault — and always give the customer a way to reply. For a one-off invoice, follow-up works differently: see getting invoices paid online.

The accounting trail of an unpaid installment

An unpaid installment should never become a ghost line in your books. A subscription's installments can be viewed in the portal and through the API (GET /v1/subscriptions/{reference}/charges): the unpaid one stays visible with its state, and since no new period opens while it remains unpaid, there are never phantom installments to reconcile behind it.

To tie every event to your customer record, rely on the metadata, ExternalId and PeriodDate echoed by subscription events. Each paid installment then becomes an account movement with its reference, included in the CSV export of transactions.

Three habits for your accountant:

• record an installment as paid when subscription.payment_succeeded arrives, never before;
• keep unpaid installments on a separate list, reviewed every week, with their payment deadline;
• close the customer file at cancellation, noting the last period actually paid.

The offer and its other features are presented on the subscriptions and recurring payments page.

Frequently asked questions

How long does the customer have to pay an installment?

An installment's link stays payable for 14 days after the due date — or after it was sent, if it went out later — counted on the Africa/Casablanca time zone. During that time, the customer receives a reminder by email every day, with the same link. If they do not pay before the link expires, the subscription is canceled automatically and your server receives subscription.canceled.

Is the customer notified when their installment is not paid?

Yes: as long as the installment is unpaid, they receive a "Rappel de paiement" (payment reminder) email every day, with the period's link. Nothing stops you from adding your own message, signed with your brand, to explain the situation, remind them of the deadline and tell them how to reach you. You can also send them the link again by WhatsApp or SMS.

Does an unpaid subscription keep billing new periods?

No. While an installment remains unpaid, no new period opens and no new link is sent: your customer never piles up several overdue installments, and your books never carry a silent debt. If the pending installment is never paid, the subscription is canceled automatically when the link expires, and your server is told through subscription.canceled.

When is an unpaid subscription canceled automatically?

When the installment's link expires without being paid, 14 days after the due date. The status then turns to canceled (CANCELED) and your server receives the subscription.canceled event. Cancellation is permanent: to resume the relationship with that customer, you will need to create a new subscription on their client record.

What happens if the customer's card is declined on the link?

Your server receives subscription.payment_failed, but the link stays payable: the customer can try again after sorting it out with their bank, or pay with another card on the same page. Daily reminders continue as long as the installment is unpaid, within the 14-day limit. The most common causes of declines are covered in card declined online.

Which webhook signals an unpaid installment?

No event is sent just because the date passes: an installment is unpaid as long as you have not received subscription.payment_succeeded for its period (PeriodDate). subscription.payment_failed signals a declined card payment attempt on the link, and subscription.canceled the cancellation at the end of the deadline. Route on Chari-Event-Type, deduplicate on Chari-Event-Id, and reply 2xx once the event is stored.

What does the portal show when an installment is not paid?

The Subscriptions page lists your subscriptions, their next due date and their status. On a subscription's record, every installment sent appears with its state: the unpaid one stays pending there until it is paid. From that record, you can pause, resume or cancel the subscription. If it is canceled when the link expires, its status turns to canceled, in the portal as well as through the API.

Next step

Create a test subscription, wire your subscription.* webhooks and write your service rule for unpaid installments before you sign up your first customer: Start in test mode. To review how a subscription is set up, from the client record to the first link, reread subscriptions through the API; for the call reference, see the Subscriptions module documentation.