Short answer. The customer’s card never enters your application: your server creates a pending order with an amount computed on its side, registers that order with the gateway, and sends the customer to the gateway’s payment page. When the customer returns to your site, that return is a hint, not a proof: your server asks the gateway for the real status, or receives a signed webhook, and only then does the order become paid. Every order has an idempotency key so that a double click or a webhook received twice neither charges nor counts twice. Every week, the bank statement is reconciled with the orders, and a refund goes through the gateway’s API, never through a manual transfer. Ten weeks, two of them a small-amount pilot.
This guide is for the merchant or manager who wants to take card payments in their application or shop, the founder settled in France who wants to sell in dinars to customers in Algeria, and the person who must compare one “payment integration” quote with another. It does not repeat which business model to choose, described in the marketplace guide and the SaaS guide, nor how to take payment at the counter, described in the point-of-sale guide; it describes what is built between your application and the gateway, and extends our page on software engineering.
What the documentation says
The entry is administrative before it is technical, and it is public. GIE Monétique’s CIBWEB portal describes a merchant’s path: create an account and file a request, which the GIE “processes and rules on within 24 hours” in its own words; pass “the technical integration tests on the electronic payment platform”; obtain an “authorisation to enter operation”. The eligibility conditions it shows are registration in the commercial register or the crafts register and registration in the national e-suppliers file. What this imposes: both registrations are checked in week one, before writing a line, and the duration of the test phase is requested in writing, because the portal does not give it.
The technical mechanism is that of a hosted payment page, documented by third parties. The unofficial documentation of the SATIM gateway we read describes an order registration that returns an identifier and a payment page address, an amount “multiplied by 100” before sending, a 50-dinar minimum, a return address and a failure address, then a server-side confirmation that returns the status, an action code and an approval code. It distinguishes a test environment and a production environment. We say this with care: it is third-party documentation, and the exact parameters are reread in the integration guide handed over by your bank or integrator. What this imposes: the same architecture whatever the provider, an order on your side, a page on theirs, a confirmation at the source.
Aggregators document the part shops forget: the notification. The documentation of an Algerian aggregator that supports CIB and Edahabia describes a webhook sent over HTTPS with an event type, “checkout.paid” for instance, an HMAC-SHA256 signature of the raw request body computed with your secret key, a 200 response expected from your server, prefixed test keys and a field that distinguishes live mode from test mode; it notes that a webhook cannot reach a local server, hence a tunnel during development. What we did not find: an official fee grid, a published settlement delay, a webhook retry policy; all three are requested in writing, and third-party guides that quote percentages contradict each other, which is why we quote none.
One payment, from the customer’s screen to the bank statement
Payment is not understood on an API diagram but on the path of a real payment, and on the station where you are allowed to believe it.
First station, on your side: the customer validates the basket, your server freezes the lines, computes the amount, creates the pending order with a number and an idempotency key, and registers that order with the gateway, sending it the amount; your server states the amount, never the screen. Second, at the gateway: the customer is sent to its payment page, the only one that sees the card. Third, on the customer’s phone: they enter their CIB or Edahabia card and the code received by SMS, depending on their bank’s flow. Fourth, the return: the browser comes back to your success address with an identifier in the address. That is the hint. It sometimes arrives before the payment, sometimes after, sometimes never.
Fifth station, the only one that counts: your server asks the gateway for the order’s status, or receives the signed webhook, and reads “paid” at the source. That is the proof, and only here does the order change state. Sixth: paid, receipt sent on WhatsApp and e-mail per the notifications guide, stock reserved. Then, one to three days later, a line appears on the acquiring bank’s statement, net or before fees depending on your contract, and reconciliation links it to the order number; whatever does not match becomes a question asked of the bank, not a gap discovered at closing.
«The browser’s return is what you see first and believe last.»
Online payment in an application, in five layers
Behind those six stations, five layers, and only one truly belongs to you.
The screen: the basket, the pay button, the waiting page, the success and failure pages; it displays the state, it never decides it, and a success screen that says “paid” because the address contains the word success is the first defect we fix. Your server: the order and its state machine, server-side amounts, the idempotency key, the log; it is the only layer that writes “paid”, and only after checking at the source. The gateway: the hosted payment page, registration, status, refund; SATIM directly through your bank, or an aggregator that carries the contract and the page; the card never crosses the border between that layer and yours.
The bank and the network: the acquiring bank that pays you, the customer’s issuing bank, the interbank network, GIE Monétique that authorises; fees, settlement delay and contract are negotiated here, and no line of code changes them. Supervision: statement ↔ orders reconciliation, orders pending too long, webhooks rejected for invalid signature, the month’s refunds; a screen read every week, built like the manager’s dashboard. The choice between SATIM directly and an aggregator is made in writing in week one, with each one’s fees and settlement delay, and it changes nothing in layers two and five: that is the reason to write the state machine before connecting anyone.
An order’s states, and what is allowed to change them
The state machine is the heart of the integration, and the drawing reread with the client before the first line.
Seven states. Created: the basket is frozen and the amount computed. Awaiting payment: the order is registered with the gateway and the page is open. Paid: the status was read at the source. Delivered: the parcel was scanned or the service rendered. Failed: the bank refused. Expired: thirty minutes without confirmation, stock released. Refunded: full or partial, dated, with the reason. Three events move the normal path forward: server-side validation, the “paid” status read at the gateway, the scanned delivery. Each is verified by your server, and each writes a log line with the state before and after, as the audit log guide provides.
Two things do nothing. The browser’s return to your success address, crossed out on the drawing: it displays the state from the database, it does not change it, and that is what makes the arrival order between return and webhook irrelevant. The second copy of a webhook: its signature is verified, its event id recognised, your server answers 200 and writes nothing. The rule fits in one sentence, written in the specification: a state changes only on an event verified by your server, never on what the customer’s browser says. Everything else, receipt, stock, accounting, follows from the state, never from the screen.
«A state changes only on an event verified by your server, never on what the customer’s browser says.»
Six real situations, and what the architecture does
Six situations we see every week on shops that work, and the mechanism that settles each.
The customer pays then closes the tab: the return never arrives; the webhook, or the scheduled check of pending orders every five minutes, moves the order to paid, and the receipt goes out without the customer coming back. Two clicks on pay: one idempotency key per basket, and the second click returns the same order and the same page instead of creating a second one; it is the mechanism described in the offline guide. The webhook arrives before the return: the success page reads the state from the database and displays it; the order is irrelevant.
The same webhook arrives twice: id remembered, second delivery acknowledged without writing; without this, two receipts, two accounting lines and stock deducted twice. Paid, but the stock is gone: the last item left at the counter during the payment; refund through the gateway’s API, refunded state, message to the customer, and never a manual transfer that no reconciliation will find. The gateway stops responding: cash on delivery or bank transfer stays offered, pending orders expire cleanly and release stock, and supervision flags it; a shop that has only card sells nothing that evening.
Seen elsewhere: hosted payment pages, signed webhooks, and what transposes
Three sources say the essentials. GIE Monétique’s portal says the entry is a request, technical tests and an authorisation; what transposes is that the file is filed in week one, alongside code in the test environment. Third-party documentation of the SATIM gateway describes an order registered server-side, a hosted page and a confirmation at the source; what transposes is that your server never sees the card and never believes the browser. An aggregator’s documentation describes a signed webhook, acknowledged with a 200 and impossible to receive locally; what transposes is signature verification on the raw body, memory of received events, and a tunnel during development.
What these sources do not say: fees, settlement delay, webhook retry policy, and the exact behaviour of the payment page on your customers’ phones; the first two are requested in writing, the last two are measured in the pilot.
The rules of a payment integration you can put into production
Six rules, written in week one. The amount is computed server-side, never read from the screen or the return address. The browser’s return is only a hint; only the status read at the source or a signed webhook changes the state. One idempotency key per order, and one remembered id per webhook: nothing is charged or counted twice. A pending order expires and releases stock. The statement is reconciled with orders every week, and every gap is a question asked. A refund goes through the API and leaves a state, a reason and a date.
A seventh rule concerns the quote: “CIB/Edahabia payment integration” is not a requirement, it is a sentence; the requirement reads “order state machine with seven states and the allowed events; server-side amounts; order registration with the gateway and hosted page; status confirmation at the source; webhook with signature verified on the raw body and remembered ids; idempotency key per basket; expiry of pending orders; statement ↔ orders reconciliation with a list of gaps; refund through the API; test environment, the platform’s technical tests, small-amount pilot”, and it is checked as the specification guide recommends. A quote that prices “the payment button” has priced the screen, that is, the layer that decides nothing.
Six companies, and what is particular about their payment
Six companies we often equip, and for each the particularity the state machine must carry.
- Ticketing, described in the dedicated guide. The ticket exists only in the paid state; expiry releases seats in minutes, not hours.
- The gym and its subscription, described in the dedicated guide. Each due date is an order; access follows the state, and renewal offers the payment page over WhatsApp.
- The developer selling off-plan to the diaspora, described in the dedicated guide. Dated instalments, each an order, and a receipt carrying the lot number; card limits are checked with the bank before announcing online payment.
- The Umrah agency, described in the dedicated guide. Payment in instalments, a file status that follows the payment states, and a partial refund that keeps the reason.
- The tutoring platform, described in the dedicated guide. The parent in France pays in dinars for the pupil in Algeria; the order carries both identities, and the receipt goes to both.
- The shop run from France, described in the dedicated guide. The founder sees every morning the orders paid, pending too long and refunded, and the statement reconciliation on Friday.
The 2027 calendar
The calendar is that of online payment put into production in ten weeks, the first two of administrative waiting overlapping with the code.
Week 0 to 1 files the request and settles the choice: CIBWEB account, register and e-supplier checked, SATIM directly through the bank or an aggregator, decided in writing with fees and settlement delay. Weeks 1 to 3 write the state machine in the test environment: order, server-side amounts, idempotency key, success and failure pages, with simulated webhooks; nothing is connected to the real gateway yet, and that is deliberate. Weeks 3 to 5 connect confirmation and webhook: status read at the source, signature verified, ids remembered, scheduled check of pending orders.
Weeks 5 to 7 pass the platform’s technical tests and obtain the authorisation; their duration depends on the platform and is requested in writing. Week 7 to 8 builds reconciliation and refund. Weeks 8 to 10 are the small-amount pilot: real payments by the team then by ten customers, every gap read daily, then the decision to open to all. Every batch is demoed as the delivery guide describes, and servers are placed per the hosting guide: the payment page is at the gateway, but your state machine must answer the webhook fast, wherever it is.
What makes a payment integration fail
The integrations we take over almost always failed for one of these reasons.
- Believing the browser’s return. The order becomes paid because the address contains “success”; orders paid without a charge, charges without an order.
- The amount read from the screen. A parameter changed in the browser, and an 8,500-dinar item paid 85.
- No idempotency key. A double click, two orders; a drop, two charges.
- No signature verification. Anyone can send a fake “paid” webhook to your server.
- No expiry. Orders pending for days, stock blocked, a warehouse that does not understand.
- No reconciliation. The gap between statement and sales is found at closing, three months too late.
- Refund by manual transfer. Not found in reconciliation, forgotten in accounting, and the customer calls back.
Frequently asked questions
The questions we receive from merchants, founders and IT managers.
- Does the customer’s card go through our application?
- No. Your server registers the order and its amount with the gateway, then sends the customer to the payment page the gateway hosts. The card and the confirmation code are entered there, never in your application, and that is what spares you from protecting card data.
- Why is the success page not enough to mark the order paid?
- Because the browser’s return is a hint, not a proof: it can arrive before the charge, after it, or never if the customer closes the tab, and its address can be forged. The order becomes paid only when your server has read the status at the source, through a request to the gateway or through a webhook whose signature has been verified.
- What happens if the same payment is notified twice?
- Every webhook carries an event id that your server remembers; the second delivery is acknowledged with a 200 and writes nothing. On the customer side, one idempotency key per basket makes a double click return the same order instead of creating a second one.
- What does card payment cost and when are we paid out?
- No official grid is published, and third-party guides that quote percentages contradict each other; fees, settlement delay and limits are requested in writing from the acquiring bank or the aggregator, and checked in the pilot by comparing the statement with the orders. We write the figures obtained into the specification, not into the article.
- SATIM directly or an aggregator?
- Both give the same architecture: an order on your side, a page on theirs, a confirmation at the source. The aggregator carries the contract, the page and the documentation, and charges for it; the direct connection goes through your bank and GIE Monétique. We write the state machine before choosing, so that the choice is made on fees and delay, and can change without rewriting the application.
- How long to put payment into production?
- Ten weeks: one for the file and the choice, two for the state machine in the test environment, two for confirmation and webhook, two for the platform’s technical tests, one for reconciliation and refund, two of small-amount pilot. The duration of the technical tests depends on the platform and is requested in writing.