CMI Integration: dirham payments on your e-commerce site

The Centre Monétique Interbancaire was established in 2001 and has been operational since 2004. It now federates more than 35 banks and payment institutions in Morocco — Attijariwafa Bank, CIH, BMCE Bank of Africa, BCP, Société Générale Maroc, Crédit Agricole du Maroc, BMCI and others — all of which issue Visa and Mastercard cards under the CMI interbank network.

An e-commerce site that only accepts PayPal or an international card effectively excludes the vast majority of Moroccan buyers: their bank cards go through the CMI network, and a payment in foreign currency generates conversion fees at their expense. The common objection — "PayPal is enough" — ignores that PayPal adoption remains low among Moroccan individuals, and that exchange fees on each purchase are a real barrier to purchase, particularly for low-value baskets. CMI processes transactions in Moroccan dirhams (MAD), directly from the buyer's bank account, without conversion and without friction.

CMI affiliation is not obtained directly from CMI: it goes through one of the network's partner banks. The merchant opens a professional account at a member bank, then submits an e-commerce merchant membership application to that bank, which forwards it to CMI.

Two profiles are accepted: legal entities (incorporated companies) and self-employed individuals engaged in commercial activity. The documents required vary by status, but the principle is the same in both cases: demonstrating the legal existence of the activity and the signatory's authority.

One prerequisite is often underestimated: the site must be online and fully functional at the time of application. The bank or CMI performs a technical review of the site before validating membership. A site under construction or served over plain HTTP will be rejected.

CMI gateway integration imposes server-side constraints that hosting must satisfy before a single line of payment code is written. These prerequisites are not recommendations: a site that does not meet them will be refused at membership or will see its transactions fail in production.

HTTPS mandatory across the entire site. CMI requires a valid and active SSL certificate on the merchant's domain. Payment pages but also notification pages (callbacks) must be served exclusively over HTTPS. A self-signed or expired certificate results in immediate failure at membership validation.

Notification URL (callback) reachable from outside. The CMI server sends an HTTP POST notification to the callback URL configured in the merchant portal to confirm each transaction. This URL must be reachable from CMI servers at all times, without IP filtering on the firewall side, and must respond within a reasonable time. A hosting environment behind a private network without inbound NAT rules, or a server with port 443 filtered, blocks these notifications and leaves orders in a "pending" state on the merchant side.

Stable DNS resolution. The domain name of the site and callback URL must resolve correctly and consistently. Incomplete DNS propagation at launch or a hosting change without a transition period can cause notification failures.

3D Secure support. The 3D Secure protocol (Verified by Visa / Mastercard SecureCode) is enabled by default on the CMI network. The buyer is redirected to the ACS (Access Control Server) page of their bank, which sends them a validation code. Hosting must allow these redirects and must not block the user agents or IP addresses of CMI servers in application security rules.

CMI offers two main integration protocols for e-commerce sites.

CMI Direct Pay is the standard integration method. The merchant redirects the buyer to the payment page hosted by CMI (CMI-hosted card data entry page), which exempts the merchant site from directly handling card data and simplifies PCI-DSS compliance. Transaction parameters (amount, currency, order reference, return URL, callback URL) are passed in an HTML form signed with a shared key. The CMI server validates the signature, displays the payment page, then notifies the merchant via POST to its callback URL.

3D Secure is enabled by default on CMI transactions. During payment, the buyer is redirected to the ACS (Access Control Server) page of their bank, which sends them a validation code. This mechanism transfers fraud liability to the issuing bank once authentication succeeds — a direct operational benefit for the merchant in case of dispute.

In both cases, the callback URL must be absolute, in HTTPS, and reachable from the public internet. CMI does not support bare IP URLs or non-standard ports on inbound connections to the merchant site.

Dirham billing is a point often overlooked in e-commerce specifications. When a Moroccan buyer pays on a site billing in euros or dollars, their bank applies an exchange rate and may add a conversion commission. This surcharge — often between 2% and 4% depending on the bank and card type — is visible on the buyer's bank statement and constitutes a real psychological barrier to purchase, particularly for low-value baskets.

CMI transactions are denominated in Moroccan dirhams (MAD). The buyer sees the exact amount of their order in dirhams, with no conversion surprise. The merchant is settled in dirhams in their Moroccan professional account. Neither party bears conversion costs.

For agencies managing clients whose audience is predominantly Moroccan, this is a direct commercial argument: a CMI integration in the checkout funnel improves conversion on this audience, without any modification to the site content.

The three technical prerequisites of CMI — active HTTPS, publicly reachable callback URL, stable DNS resolution — are directly conditioned by the choice of hosting provider.

A hosting plan that includes the SSL certificate (automatic issuance and renewal via Let's Encrypt or an equivalent authority) avoids the main cause of membership failure: an expired certificate or an incomplete chain. Activating HTTPS from the moment the site goes live, before even submitting the merchant file, is the sequence that avoids back-and-forth with the bank.

Dirham billing on the hosting side is a complementary advantage for agencies managing multiple Moroccan clients: paying for infrastructure in MAD, receiving invoices in MAD with Moroccan VAT, and integrating a CMI gateway into delivered sites form a coherent package from the client accounting perspective. An agency that hosts its e-commerce clients on a plan including SSL, HTTPS and dirham billing brings together the three conditions CMI requires at membership on a single provider.

Five problems recur systematically when putting a CMI integration into production. Here they are with their exact message or symptom and their resolution.

Error 1 — Callback not received / order stuck in "pending".
Symptom: the CMI payment page displays, the buyer validates their payment, but the order remains pending on the merchant side. Cause: the callback URL is not reachable from CMI servers — firewall, iptables rule blocking inbound connections on port 443, or hosting behind a private network. Resolution: verify that port 443 is open inbound and that the callback URL responds to a curl from an external IP.

Error 2 — "Incorrect signature" or "Invalid hash".
Symptom: the CMI page returns a signature error. Cause: the shared key (store key) entered in the integration form does not match the one configured in the merchant portal, or the parameters are encoded differently (URL encoding, field casing). Resolution: re-check the key in client.cmi.co.ma, ensure the field order in the string to sign exactly matches the CMI documentation.

Error 3 — SSL certificate rejected at membership.
Symptom: the membership file is returned with the note "unsecured site" or "invalid certificate". Cause: self-signed certificate, incomplete authority chain, or domain partially served over HTTP. Resolution: test with SSL Labs before submitting, ensure all pages (including the callback) respond over HTTPS with a certificate signed by a recognised authority.

Error 4 — 3D Secure redirect fails or loops.
Symptom: the buyer is redirected to their bank page, but the return to the merchant site results in a 404 error or blank page. Cause: the return URL (okUrl / failUrl) points to a non-existent path after deployment, or the server blocks POST redirects. Resolution: verify the return URLs in the CMI configuration and ensure they are active on the production hosting.

Error 5 — Duplicate amount on merchant statement.
Symptom: the same order appears twice in the CMI statement. Cause: the callback was called twice (server-side timeout → CMI retry) and the application logic has no idempotency on the order reference. Resolution: check the order reference (oid) on callback receipt and only validate the order if it is not already marked as paid.

CMI integration is just one aspect of a Moroccan e-commerce site's compliance. Moroccan VAT (20% on digital services) applies when the provider is based in Morocco and the service is rendered to a Moroccan client — a point developed in the article Moroccan VAT and web hosting. Personal data collected during the payment process is subject to Law 09-08 and CNDP recommendations, particularly if hosted outside Morocco — see CNDP compliance and hosting outside Morocco.

For agencies registering .ma domain names for their clients, the registrar's ANRT accreditation is a prerequisite: a .ma domain registered through a non-accredited registrar is not valid. The article Megalogi, ANRT-accredited registrar details this point.

All of these constraints — CMI, VAT, CNDP, ANRT — form the regulatory framework of a Moroccan e-commerce project. Managing them with a single hosting provider that bills in dirhams, includes SSL, and is itself anchored in the Moroccan legal framework simplifies project management for the agency and its client.