Orange Money Mali

create_payment

• ⚠Two distinct credentials are required: ORANGE_MONEY_BASIC_TOKEN (base64 of clientId:clientSecret, used to obtain the OAuth Bearer) and ORANGE_MONEY_MERCHANT_KEY (sent in the request body). They are NOT interchangeable.
• ⚠order_id MUST be unique across all attempts. Reusing a previous order_id returns HTTP 403 Forbidden — generate a fresh value (e.g. UUID) for every retry, even after a failure.
• ⚠amount is an integer in the smallest unit of the currency. XOF has no sub-unit, so '1000' means 1 000 FCFA, not 10.00 FCFA. Sending a decimal is rejected.
• ⚠notif_url must be a publicly reachable HTTPS endpoint. Orange Money does not retry on failure — if your endpoint times out or returns a non-2xx, the notification is lost and you must reconcile manually.
• ⚠The OAuth access token returned by /oauth/v3/token is short-lived. Request a fresh token before each create_payment call (or cache it with a safety margin under the documented expires_in) — do not embed a long-lived token in code.
• ⚠The endpoint path is country-specific: /orange-money-webpay/ml/v1/webpayment for Mali. Other countries (SN, CI, BF, etc.) use a different path segment — do not assume one URL covers all Orange Money markets.
• ⚠Always verify the payment server-side via the notif_url callback (using notif_token) before fulfilling the order. The browser redirect to return_url alone can be spoofed and is not proof of payment.

webhook_payment_completed

• ⚠The ONLY authentication mechanism is matching the inbound notif_token against the value you stored when create_payment returned. Reject any POST whose notif_token does not match a known session — anyone who guesses your URL can otherwise POST to it.
• ⚠Return HTTP 200 immediately, before doing any business work. Orange Money does NOT retry a failed delivery — if your handler times out (typically after a few seconds) or throws, the notification is permanently lost and you must reconcile manually.
• ⚠Treat status === 'SUCCESS' as the only paid state. 'FAILED' / 'EXPIRED' (and any other value) mean the customer was not charged. Do not rely on the mere fact of receiving a webhook to fulfill the order.
• ⚠The exact set of fields and casing in the JSON payload may vary across Orange Money country deployments and API versions. Code defensively: validate notif_token first, then read fields with optional chaining and explicit type coercion (e.g. amount may be a string).
• ⚠Orange Money never calls back the return_url server-side — the user's browser is just redirected there. Order fulfillment MUST happen from this webhook handler (or a polled status check), never from the return_url request.