7 endpoints
Subscriptions
A payment link e-mailed at every due date, with its reminders, pauses and history.
Endpoint names and descriptions come from the OpenAPI contract, in English — they cannot drift from the API.
You create your test key in the portal as soon as your account is activated.
In plain English
Send the same customer a payment link at regular intervals.
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 e-mail, since every instalment is sent there — with its cadence and its amount.
- 2At each due date, ChariPay generates a single-use payment link and sends it to the customer; the first payment moves the subscription from
INCOMPLETEtoACTIVE. - 3While an instalment is unpaid, a reminder goes out every day and no new period opens; the link stays payable for 14 days after the due date, then the subscription is cancelled — watch
subscription.payment_succeeded,subscription.payment_failedandsubscription.canceled. - 4Pause, resume or cancel as the contract evolves; read the instalments for your invoicing.
- 5In the sandbox, a start date set to today opens the first instalment immediately; a
DAILYfrequency brings the next one the following day.
- 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
Resume a subscription
Resumes a paused subscription's billing cycle. Periods elapsed while paused are not billed retroactively.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
reference | string | path | Required |
Pause a subscription
Suspends the subscription: no new period is opened and no payment link is sent until /resume.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
reference | string | path | Required |
Cancel a subscription
Permanently ends the subscription. No further payment link is generated.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
reference | string | path | Required |
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 |
Create a subscription
Starts a subscription for an existing client; the returned status is INCOMPLETE until the first period is paid. At each due date a single-use payment link is generated for the period and e-mailed to the client, who pays it on the hosted checkout with 3DS. While a period stays unpaid, a reminder is e-mailed daily and no later period is opened; a link left unpaid 14 days after its due date cancels the subscription. 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). The client needs an e-mail address: each period's payment link is sent there. |
amount | number | body | Required | Amount of each period's payment link, in MAD major units. |
description | string | body | Required | Description shown on each generated payment link. |
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 send each period's payment link to the client. EMAIL is the supported channel. |
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. |
List a subscription's charges
Returns every charge generated by the subscription (one single-use payment link per billing period), most recent period first.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
reference | string | path | Required |
Retrieve a subscription
Fetches a subscription with its lifecycle state and its open charge: the current period's payment link, when one is open.
| Field | Type | In | Required | Description |
|---|---|---|---|---|
reference | string | path | Required | Subscription reference. |
Make your first test-mode call
Create your account, generate your test key in the portal and send your first request today — or talk to an integrator.
- Free, no commitment
- Test mode from sign-up
- No approval to wait for