POST

Créer une demande de paiement

Envoie une notification à un utilisateur CaurisPay pour lui demander un paiement. Le payeur confirme depuis son application avec son code PIN, et le montant est débité de son portefeuille vers le vôtre.

URL

https://developer.caurispay.net/v1/developer/payment-requests

Headers

X-Api-KeyrequisVotre clé publique, obtenue depuis votre espace développeur

X-Api-SecretrequisVotre clé secrète, jamais exposée côté client

Content-Typerequisapplication/json

Paramètres

amountstring, requisMontant demandé sous forme numérique, ex : "5000.00". Doit respecter le minimum de la devise choisie (voir tableau ci-dessous)

currencystring, requis3 lettres majuscules, une des 8 devises supportées (voir tableau ci-dessous). Normalisée automatiquement en majuscules

payerPhonestring, requisNuméro du payeur : chiffres uniquement, code pays inclus, sans le signe "+". Entre 8 et 15 chiffres. Ex : 22890123456

callbackUrlstring, requisURL HTTPS qui recevra les webhooks. Refusée si elle pointe vers une adresse locale ou privée (localhost, 127.0.0.1, plages internes)

businessNamestring, requisNom affiché au payeur dans la notification qu'il reçoit

Devises supportées

Chaque devise a un montant minimum propre, exprimé dans cette devise. En interne, CaurisPay convertit toujours le montant vers le XOF (devise pivot) avant de vérifier le solde du payeur.

DeviseMontant minimum

XOF250

EUR0.38

GHS2.25

GNF2 500

KES50

NGN187.5

USD0.45

ZAR6.25

Toute demande sous le minimum de sa devise est refusée avec le code AMOUNT_BELOW_MINIMUM.

Expiration

Une demande de paiement est valable 5 minutes à partir de sa création. Si le payeur ne confirme pas avant la date indiquée dans expiresAt, la demande passe automatiquement au statut expired et ne peut plus être payée. Un webhook payment_request.expired vous est envoyé à ce moment-là.

Réponse — 201 Created

successbooleantrue si la demande a été créée

messagestringMessage lisible décrivant le résultat

statusstringStatut initial de la demande : notified

tokenstringIdentifiant de la demande, à utiliser pour la consulter, l'annuler, ou faire le lien avec les webhooks reçus

expiresAtstring (ISO 8601)Date et heure d'expiration automatique de la demande (5 minutes après création)

Codes d'erreur

API_KEY_MISSING401

Aucune clé API fournie dans les headers

INVALID_API_KEY401

Clé API invalide, révoquée, ou compte introuvable

CURRENCY_NOT_SUPPORTED400

La devise fournie n'est pas dans la liste supportée

AMOUNT_BELOW_MINIMUM400

Le montant est inférieur au minimum autorisé pour cette devise

URL_INVALID400

callbackUrl invalide, non HTTPS, ou pointant vers une adresse interne/privée

PAYER_NOT_ELIGIBLE400

Le numéro fourni n'est lié à aucun compte CaurisPay actif, ou son portefeuille est introuvable

CANNOT_PAY_YOURSELF400

Le numéro du payeur correspond à votre propre compte

INSUFFICIENT_BALANCE409

Le solde du payeur est insuffisant pour ce montant

Webhooks associés

Une fois la demande créée, CaurisPay notifie votre callbackUrl à chaque changement de statut :

payment_request.notifiedEnvoyé immédiatement après la création

payment_request.paidLe payeur a confirmé, le transfert est exécuté

payment_request.rejectedLe payeur a explicitement refusé

payment_request.expiredDélai de 5 minutes dépassé sans réponse

payment_request.cancelledAnnulée par vous via l'endpoint DELETE

Détail du format et de la vérification de signature dans le guide Webhooks.