A REST API to get paid in Morocco by card or in cash at an agency: one base URL, a key that picks the environment, idempotency, explicit errors and signed webhooks. Test mode opens as soon as you sign up — free, with no time limit and no approval to wait for: you integrate today, without waiting on anyone.
Sandbox and production share the same address: https://api-psp.charipay.ma. The key sent in the X-CHARI-PAY-API-KEY header decides: chari_sk_test_… works on test data, chari_sk_live_… on live data, with no OAuth and no token to refresh. Until production is enabled, a live key receives 403 PRODUCTION_ACCESS_NOT_ENABLED. On go-live day, you change the key and the webhook secret, not your code.
A network glitch must never charge twice. The Idempotency-Key header covers the technical replay of the same request; the externalId field, unique per account and per environment, covers business re-submission: if the object already exists, the API returns it with 200 instead of creating it with 201. Refunds follow the same logic with a deterministic refundReference: 202 on creation, 200 on replay. Keep separate Idempotency-Key values for sandbox and production.
A single envelope, { "error": { "code", "message" }, "correlationId" }, and a stable machine code: test the code, never the message. The correlationId comes back on every response, success and error alike; send an X-Request-Id and it becomes your correlationId, so you can follow a call end to end. HTTP statuses tell the rest: 400, 401, 403, 404, 409, 410, 422, 429.
Publicly exposed endpoints advertise X-RateLimit-Limit, -Remaining and -Reset, and answer 429 with Retry-After when exceeded. Amounts are in dirhams, in major units (149.90 = MAD 149.90), timestamps in ISO-8601 UTC; lists paginate by page and size, and by cursor on transactions. Every URL you declare must use HTTPS.
One key per company and per environment, with per-module permissions (scopes): each key gets only what it needs. You create it yourself from the portal, after re-authenticating; the full key is shown exactly once and is never sent by email. Two keys can coexist during a rotation, with no downtime.
Every event carries X-CHARI-SIGNATURE, an HMAC-SHA256 computed over the timestamp and the raw body, and X-CHARI-TIMESTAMP in milliseconds: compare in constant time and reject any gap beyond five minutes. Deduplicate on Chari-Event-Id, which stays stable across attempts: delivery is guaranteed at least once, not necessarily in order. Signing secrets differ between sandbox and production.
Everything is set up from the portal, without going through us: you create your test keys and choose their permissions, declare your receiving URLs and the list of events each one receives, send a test event, then review every delivery alongside the code your server returned. A failed delivery can be replayed in one click, and two-factor authentication (TOTP) is available to protect access.
Verify the signature before reading the body, deduplicate by event ID, reply 2xx as soon as the event is stored: the platform handles the rest. Without a 2xx, it retries immediately, then after 1 min, 5 min, 30 min and 1 h, then every 6 h, up to 16 attempts over about 72 hours; beyond that, the delivery is marked failed and can be replayed from the portal. Twenty events are documented — payments, subscriptions, refunds, payment account movements, distribution — and you choose which ones each endpoint receives. During a secret rotation, the X-CHARI-SIGNATURE-NEXT header carries the signature computed with the new secret.
// En-têtes reçusX-CHARI-SIGNATURE: a3f19c… (HMAC-SHA256)X-CHARI-TIMESTAMP: 1756166400000Chari-Event-Id: 9f2c31a4-…Chari-Event-Type: payment.succeeded // Corps — signé tel quel, octet par octet{ … }Test mode is a complete environment — API keys, payment links, checkout sessions, subscriptions, refunds, webhooks — open as soon as you sign up. Three fields (name, work email, company), an activation link sent by email, the password of your choice: you are in the portal, where you create your own test key. Then pay with the test card 4918 9141 0719 5005, CVV 123, any future expiry date and 3-D Secure code 555: you see your customer's journey and receive the payment.succeeded webhook. Only this card is accepted in the sandbox, and no real money moves. It is free, with no time limit, no bank card to provide and no commitment, and there is no approval to wait for: your business verification (KYB) runs in parallel and only gates the move to production. The eight sign-up steps are also documented as API calls, for those who want to automate everything.
The full reference — 13 modules, 58 endpoints, examples in curl, JavaScript, Python and PHP — is published on this site, freely accessible with no account. It is generated from the API's OpenAPI specification; the Postman collection and the specification can both be downloaded, as can a pack for coding assistants — one Markdown file per module, the guides, the test card and the specification.
Sign up on the portal, activate by email, choose your password: your test key is created from the developer space and shown exactly once. Nothing to pay, nothing to sign, no documents to provide at this stage.
Payment links, hosted checkout, subscriptions, refunds, webhooks: everything works in the sandbox with the test card. For a subscription, a start date set to today opens the first instalment immediately, and a daily frequency brings the next one the following day. Webhooks are sent as usual in the sandbox: check your signature, deduplication and 2xx replies before go-live day.
When you are ready: KYB verification (identity documents and trade register, with dual human review), a priced proposal, the MAD 6,000 activation fee (VAT included) paid once, then activation. You swap the test key for the production key, along with the webhook secret: the rest of your code stays the same.
Create your test account: free, with no time limit and no approval to wait for. Your test key is created from the portal, your first payment goes through with the test card — and if you prefer, tell us about your integration first.