Payment model

Two families of operations

Family	Who pays	Examples	Result
A. You spend your balance	Your partner account	Service operations for your customers	Immediate: the response gives the result
B. The customer pays you	The customer, from their SAMA Money account	Charge for an order, an invoice, a subscription, a donation	Asynchronous: the customer confirms on their phone, you are notified

The matching guide for family B: Collect a payment.

There is no withdrawal through the API: a customer who withdraws cash starts the withdrawal themselves from their app.

Life cycle of a charge

pending ──► succeeded   the customer confirmed: the payment is secured
        ──► failed      the charge did not go through
        ──► expired     the request was left unanswered for 90 days

A charge is never debited without the customer’s explicit consent (secret code in the app). You never enter a customer’s secret code: there is no route for it. A pending charge is not paid: wait for succeeded.

A request stays pending until it is confirmed or declined. Left unanswered, it expires after 90 days: its state becomes expired.

Identifiers and amounts

Every charge has a reference (shaped like chg_…): it is the identifier to store and to use in GET /v1/charges/{reference}. The reference field you send at creation is your own reference (an order number).
Amounts are integers in CFA francs in amount_xof, with no decimals.
Phone numbers are written with the country code, for example 22370000000.

Idempotency

A timeout is not a failure: the request may have succeeded. Send an Idempotency-Key header (one UUID per business operation) on every money-moving operation: if you replay the same request with the same key, the API returns the same result instead of running the operation a second time. For a new operation, always use a new key.