9 endpoints

Subscriptions

A recurring charge on a saved payment method, with its due dates, pauses and dunning.

Endpoint names and descriptions come from the OpenAPI contract, in English — they cannot drift from the API.

In plain English

Charge the same customer at regular intervals, automatically.

When to use it

For any recurring revenue: monthly subscription, plan, or a service billed in instalments.

How to integrate it

1Create the subscription for an existing customer — one with a valid email, since the mandatory pre-debit notice always goes out by email — with its cadence and its amount.
2The first payment happens with the customer present, with their explicit consent to store their payment method.
3Set the payment method to charge, or leave the client's default.
4Pause, resume or cancel as the contract evolves; consult the due dates for your billing.
5When a charge fails, the subscription turns PAST_DUE: up to 4 automatic attempts, a fallback payment link sent to the customer, then cancellation — watch subscription.payment_failed and subscription.canceled.
6In the sandbox, a dedicated endpoint forces the next due date so you can test a year of subscription in a minute.

PUT/v1/subscriptions/{reference}/payment-methodSelect a subscription payment method
POST/v1/subscriptions/{reference}/test-auto-payForce the next automatic payment (sandbox only)
POST/v1/subscriptions/{reference}/resumeResume a subscription
POST/v1/subscriptions/{reference}/pausePause a subscription
POST/v1/subscriptions/{reference}/cancelCancel a subscription
GET/v1/subscriptionsList subscriptions
POST/v1/subscriptionsCreate a subscription
GET/v1/subscriptions/{reference}/chargesList a subscription's charges
GET/v1/subscriptions/{reference}Retrieve a subscription

PUT

Select a subscription payment method

Switches an auto-pay subscription to one of its client's saved payment methods. Only the local payment-method UUID is accepted; provider tokens and CVV are never exposed.

Schema · SelectSubscriptionPaymentMethodRequest

Field	Type	In	Required	Description
`reference`	string	path	Required
`paymentMethodId`	string (uuid)	body	Required	Client-owned local payment-method UUID.

POST200

Force the next automatic payment (sandbox only)

Test helper available only with a SANDBOX API key. It creates or reuses the charge for the currently outstanding period, queues the pre-debit e-mail, and immediately executes the saved-token payment with its internally decrypted CVV and 3DS disabled. The CVV never appears in the request or response. The subscription must be INCOMPLETE, ACTIVE or retryable PAST_DUE, autoPay must be enabled, and the first keepAlive + 3DS checkout must already have attached a saved payment method. On success, nextRunDate advances. On failure, it does not advance: an initial failure stays INCOMPLETE; a renewal failure becomes PAST_DUE. The response contains a safe failure category/code, attempt count, retry/cancellation timing and fallbackPayUrl. Hard declines such as an expired card require a replacement payment method or manual payment. Idempotency-Key is mandatory; replaying it returns the same operation without another debit.

Field	Type	In	Required	Description
`reference`	string	path	Required	Subscription reference.
`Idempotency-Key`	string	header	Required	Required unique key. Reuse it only to replay this exact test request.

POST

Resume a subscription

Resumes a paused subscription's billing cycle.

Field	Type	In	Required	Description
`reference`	string	path	Required

POST

Pause a subscription

Suspends future charges without cancelling. Resume later with /resume.

Field	Type	In	Required	Description
`reference`	string	path	Required

POST

Cancel a subscription

Permanently ends the subscription. No further charges are generated.

Field	Type	In	Required	Description
`reference`	string	path	Required

GET

List subscriptions

Returns the caller's subscriptions for the key's environment, as a paginated Page.

Field	Type	In	Required	Description
`origin`	enum	query	Optional	Filter by creation origin (API or DASHBOARD).Values `APIDASHBOARD`
`pageable`	Pageable	query	Required

POST200

Create a subscription

Starts a recurring subscription for an existing client. Auto-pay defaults to true; the returned status is INCOMPLETE until the first billing period succeeds. The first hosted checkout uses 3DS, saves a provider token, masks the PAN and stores reusable authentication material in the restricted audited vault. Neither token nor CVV is returned. Future charges are announced by e-mail and collected at billingTime in Africa/Casablanca. If the start date is today or earlier, the first charge is opened immediately and returned in currentCharge. Supply an optional client-owned externalId (unique per merchant) to make the create idempotent: a duplicate externalId returns the existing subscription with 200 OK.

Schema · CreateSubscriptionRequest

Field	Type	In	Required	Description
`clientId`	string (uuid)	body	Required	UUID of the client to bill (create it first via /v1/clients).
`amount`	number	body	Required	Amount to charge each period, in MAD major units.
`description`	string	body	Required	Description shown on each generated charge.
`frequency`	enum	body	Required	Billing cadence.Values `DAILYWEEKLYMONTHLYYEARLY`
`startDate`	string (date)	body	Required	Date of the first billing period (YYYY-MM-DD).
`endDate`	string (date)	body	Optional	Optional end date; open-ended when omitted.
`channels`	array of enum	body	Required	Channels used to notify the client of each charge.
`externalId`	string	body	Optional	Your subscription identifier, unique per merchant and environment. Creating a subscription with an externalId that already exists returns the existing subscription. It is echoed as ExternalId in every subscription payment webhook for reconciliation.
`metadata`	object	body	Optional	Optional merchant-owned reconciliation attributes (maximum 4 KB serialized), echoed unchanged as metadata in every subscription payment webhook. Use opaque identifiers such as customerId or contractId; do not include card data, CVV, credentials, or unnecessary personal data.
`autoPay`	boolean	body	Optional	Save the payment method after the first 3DS payment and automatically collect future periods. Defaults to true.
`billingTime`	LocalTime	body	Optional	Recurring charge time in Africa/Casablanca.
`billingTime.hour`	integer (int32)	body	Optional
`billingTime.minute`	integer (int32)	body	Optional
`billingTime.second`	integer (int32)	body	Optional
`billingTime.nano`	integer (int32)	body	Optional
`reminderDaysBefore`	integer (int32)	body	Optional	How many days before an automatic debit to e-mail the client (0-30).
`paymentMethodId`	string (uuid)	body	Optional	Optional client-owned payment-method UUID. When omitted, the client's default payment method is reused when one exists; otherwise the first checkout captures a new method.

GET

List a subscription's charges

Returns every charge (payment link) generated by the subscription, most recent period first.

Field	Type	In	Required	Description
`reference`	string	path	Required

GET

Retrieve a subscription

Fetches a subscription, its safe saved-method display data, open charge and billing recovery state. For a failed INCOMPLETE setup or PAST_DUE renewal, billingRecovery contains a normalized reason, customer action, attempt count, next retry and cancellation deadline; provider error JSON and sensitive card data are never returned.

Field	Type	In	Required	Description
`reference`	string	path	Required	Subscription reference.

Talk to an integrator

A question about integration?

Our technical team supports integrators from the first sandbox call through to go-live.