How Recurring Billing and Saved Cards Work?
A subscription charges your customer's card automatically on a schedule, without asking them to pay again each cycle. This explains what is actually happening behind that, and what the saved card can and cannot be used for.
Every payment method supports automatic renewal
Automatic recurring charges work on every payment method Stream supports — mada, Apple Pay, Visa and Mastercard alike. There is no method that is excluded from subscriptions or from tokenisation.
The card is tokenised, and tied to one plan
When a customer pays for a recurring product, their card is tokenised and charged automatically on each cycle of that plan, with no re-entry of details.
The important limit: the token belongs to that one plan. Stream is not a digital wallet. A card saved for one subscription or installment plan:
- cannot be reused for a new subscription or a different invoice, and
- cannot be charged for separate one-off amounts such as a late fee or a damage charge.
The customer gives explicit consent by ticking a checkbox at checkout before their card is saved for automatic charges.
Charging something extra, outside the plan
Because the saved card is locked to its plan, extra amounts are not collected automatically. To charge a late fee, a damage charge or any other amount that is due, create an additional one-time invoice for that customer — Create → Instant, linked to the customer — with the amount and due date you set. For a customer-linked invoice, Stream sends it by WhatsApp by default.
Never assume a late fee will be taken automatically. It will not be.
A free first cycle: use a trial period, not a coupon
If you want the first month free, use Stream's trial period. This is the supported way to give a free first cycle — not a 100% discount coupon.
The card is tokenised before the first cycle falls due, so the trial ends in an automatic charge with no card re-entry from the customer. For installment plans there is a special first-installment feature that serves the same purpose.
A setup fee or deposit on the first payment
You can charge a one-time amount up front and still run a normal subscription afterwards. Subscriptions support collecting a first payment immediately, then a second payment on a date you choose — and that second date is where the regular recurring cycle begins.
Use this for a deposit, a setup or joining fee, or a charge covering days the customer has already used. Set the first payment to that one-time amount, alone or added to the first cycle, and set the second payment date to when the regular cycle should start.
When creating via the API, period_start on POST /api/v2/subscriptions is the start date of the first billing cycle.
What is not available
- An API for payment mandates or card authorisations. You cannot programmatically create a mandate or pre-authorise a card.
- Visa Account Updater and Mastercard Automatic Billing Updater are not supported, so an expired or reissued card is not refreshed automatically. The customer updates it themselves in the Customer Portal.
Managing subscriptions through the API
There are endpoints to create, update, get, list and cancel subscriptions, and to withdraw a scheduled cancellation. Cancelling an active subscription takes effect at the end of the current billing period. See docs.streampay.sa.
Seeing what is due
Your customers can view and cancel their own subscriptions, and update a saved card, from their Payer Profile or the Customer Portal.
Your customers can sign in directly
A payment link is no longer the only way in. Your customers can go to https://billing.streampay.sa/consumer/auth, enter their mobile number, and confirm the one-time code they receive, which takes them straight to their profile.
This helps when a customer has lost the message, and it lets you put the link — or a QR code pointing at it — on a statement, a poster or a reception desk.