Passer au contenu principal
Orqex transforme un seul appel API en le bon paiement, chez le bon prestataire, avec basculement automatique. Dépliez chaque concept ci-dessous pour comprendre les rouages.
Un paiement suit un cycle de vie prévisible :
  1. Créer une intention de paiement — montant, devise et client.
  2. Lancer une tentative — méthode et pays ; Orqex route vers la meilleure passerelle.
  3. Résoudre l’action suivante — le client doit parfois agir (OTP, redirection, QR, validation).
  4. Aboutissement — l’intention passe à completed, failed ou expired ; un webhook part.
Une passerelle est une intégration avec un prestataire (mobile money, cartes, wallets, virement, crypto). Un compte passerelle correspond à vos identifiants pour un prestataire, configurés sur votre projet — Orqex ne détient jamais les fonds, il route vers votre compte.Chaque compte déclare les méthodes et devises qu’il sert, par environnement. Vous les connectez dans le dashboard.
Les règles de routage associent une méthode + un pays à un compte primaire et un secours optionnel. La stratégie d’orchestration de votre projet décide comment Orqex choisit parmi les comptes éligibles (suivre vos règles, optimiser le succès, répartir).Si la passerelle primaire échoue pour une raison transitoire, Orqex relance automatiquement sur un secours adapté. La tentative résultante porte is_fallback: true — vous lisez simplement le statut final.
Une intention de paiement représente l’argent à encaisser. Elle porte le montant, la devise, le client et les métadonnées, et passe par pending → completed / failed / expired (et refunded / partially_refunded).Les montants sont envoyés en unités majeures (ex. 50) et renvoyés dans un objet amount dont la value est en unités mineures (ex. 5000).
Une tentative est une exécution d’une intention auprès d’un compte passerelle. Une intention peut en avoir plusieurs (nouvelle méthode, réessai, basculement). Chaque tentative a un status (processing, action_required, completed, failed, cancelled), la method utilisée, la transaction passerelle, et un objet failure en cas d’échec.Une tentative échouée n’est pas une erreur API — la requête réussit et l’échec est reporté sur la tentative.
Quand une méthode exige une action du client, la tentative expose un next_action dont le type indique quoi afficher :
typeÀ faire
redirect_to_urlRediriger le client vers url.
embed_iframeIntégrer url dans une iframe.
collect_otpCollecter un OTP, puis confirmer.
approve_on_phoneDemander la validation sur le téléphone.
scan_qr_codeAfficher content / image_url en QR code.
display_payment_instructionsAfficher les fields listés.
complete_with_sdkPasser la main à un SDK côté client.
noneRien à faire ; interroger le statut.
Envoyez un en-tête X-Idempotency-Key (8-128 caractères) sur les écritures pour qu’une requête réessayée ne soit jamais traitée deux fois — les rejeux renvoient la réponse d’origine avec X-Idempotent-Replayed: true. Le SDK PHP génère et réutilise une clé automatiquement entre ses réessais.
L’API utilise des codes HTTP conventionnels avec un corps JSON ; les échecs de validation incluent une carte errors par champ. Un paiement refusé est reporté dans l’objet failure de la tentative (code + message lisible), pas comme une erreur HTTP.