Payment Intents

Use fee quotes to calculate and display processing fees before confirming a PaymentIntent.

Un PaymentIntent représente un flux de paiement. Il suit le cycle de vie depuis la création jusqu’à la finalisation.

Famille de routes actuellement implémentée : /api/v1/payment-intents

Objet PaymentIntent

{
  "id": "pi_1a2b3c4d5e",
  "object": "payment_intent",
  "created": 1708300800,
  "livemode": false,
  "amount": 10000,
  "currency": "XOF",
  "status": "requires_payment_method",
  "description": "Order #1234",
  "metadata": {
    "order_id": "order_123"
  },
  "next_action": null,
  "customer": "cus_123"
}

Créer un PaymentIntent

POST /api/v1/payment-intents

Paramètre	Type	Requis	Description
amount	integer:int64	Oui	Montant dans la plus petite unité monétaire.
currency	string	Oui	Code devise ISO à trois lettres, par exemple XOF.
transaction_country	string	Oui	Code pays ISO 3166-1 alpha-2 de la transaction, par exemple SN, CI ou BJ.
payer_country	string	Non	Code pays ISO 3166-1 alpha-2 du payeur si différent ou connu.
rail_country	string	Non	Code pays ISO 3166-1 alpha-2 du rail/opérateur à utiliser.
description	string	Non	Description lisible du paiement.
metadata	object<string,string>	Non	Métadonnées métier. Les clés et valeurs doivent être des chaînes.
customer	string	Non	Identifiant public d’un client existant.
customer_email	string	Non	Email client utilisé pour retrouver ou créer un client.
customer_phone	string	Non	Téléphone client utilisé pour retrouver ou créer un client.

{
  "amount": 10000,
  "currency": "XOF",
  "transaction_country": "SN",
  "description": "Order #1234",
  "metadata": {
    "order_id": "order_123",
    "checkout_session_id": "cs_123"
  },
  "customer_email": "customer@example.com"
}

Paramètres pays

transaction_country est requis. Il détermine le contexte pays principal utilisé par les règles d’éligibilité pays/devise et par la sélection des rails.

payer_country et rail_country sont optionnels. Utilisez-les uniquement lorsque le pays du payeur ou du rail de paiement doit être explicite. Les trois valeurs sont des codes ISO 3166-1 alpha-2 de deux caractères.

Metadata

metadata est un objet object<string,string> destiné aux références métier comme order_id, cart_id, checkout_session_id ou source.

Les valeurs non-string ne sont pas renvoyées dans l’objet PaymentIntent. N’utilisez pas les clés réservées Description, FailureReason, Environment, ni les prefixes country_context., internal. et technical. : ils sont réservés à la plateforme et filtrés dans les réponses.

Récupérer un PaymentIntent

GET /api/v1/payment-intents/{id}

Paramètre	Type	Requis	Description
id	string	Oui	Identifiant public du PaymentIntent.

Mettre à jour un PaymentIntent

PATCH /api/v1/payment-intents/{id}

Paramètre	Type	Requis	Description
id	string	Oui	Identifiant public du PaymentIntent.
description	string	Non	Nouvelle description.
metadata	object<string,string>	Non	Métadonnées à ajouter ou remplacer.

Confirmer un PaymentIntent

POST /api/v1/payment-intents/{id}/confirm

Paramètre	Type	Requis	Description
id	string	Oui	Identifiant public du PaymentIntent.
payment_method.type	string	Oui	Type de méthode, par exemple mobile_money ou card.
payment_method.mobile_money.country	string	Mobile money	Code pays ISO 3166-1 alpha-2. Doit correspondre au transaction_country du PaymentIntent.
payment_method.mobile_money.operator	string	Mobile money	Opérateur mobile money, par exemple orange_money, wave ou mtn.
payment_method.mobile_money.msisdn	string	Mobile money	Numéro mobile money du payeur.
payment_method.mobile_money.preferred_flow	string	Non	Flux préféré lorsque le provider le supporte.
payment_method.card.token	string	Carte	Token de carte.
return_url	string	Non	URL vers laquelle rediriger le client après le paiement.

{
  "payment_method": {
    "type": "mobile_money",
    "mobile_money": {
      "country": "SN",
      "operator": "orange_money",
      "msisdn": "+221770000000"
    }
  }
}

URL de retour

Utilisez return_url pour indiquer la page de votre application vers laquelle le client doit revenir une fois le paiement terminé.

Cette URL est optionnelle. Si elle est absente, Ikawaari utilise l’URL de retour par défaut configurée dans le dashboard marchand, lorsqu’elle existe. Sinon, le client reste sur la page de statut Ikawaari.

Le même return_url est utilisé quel que soit le résultat du paiement. Lors de la redirection, Ikawaari ajoute des paramètres à l’URL pour vous aider à afficher la bonne page de confirmation :

https://votre-site.com/payment/return?status=succeeded&payment_intent=pi_...&operation_id=pi_...

status vaut notamment succeeded ou failed. Utilisez payment_intent pour récupérer le statut final côté API si vous devez valider le résultat côté serveur.

Concurrence et idempotence de confirmation

La confirmation est protégée par un verrou côté plateforme. Si deux appels confirm ciblent le même PaymentIntent en même temps, Ikawaari ne lance qu’une seule confirmation provider active.

• Si le PaymentIntent est déjà passé dans un état non confirmable, par exemple processing, requires_action, succeeded ou failed, l’API retourne l’objet courant sans relancer le provider.
• Si une confirmation est déjà en cours et que le verrou ne peut pas être acquis immédiatement, l’API renvoie 409 Conflict avec code: "IKW-RES-003", retryable: true et le message Payment intent confirmation is already in progress.
• Si une concurrence de persistance est détectée côté base de données, l’API renvoie aussi 409 Conflict avec code: "IKW-RES-003" et retryable: true, au lieu d’une erreur interne.

Les clients peuvent réessayer après un court délai ou récupérer le PaymentIntent pour afficher son état courant.

Annuler un PaymentIntent

POST /api/v1/payment-intents/{id}/cancel

Paramètre	Type	Requis	Description
id	string	Oui	Identifiant public du PaymentIntent.

Lister les PaymentIntents

GET /api/v1/payment-intents

Paramètre	Type	Requis	Description
limit	integer:int32	Non	Nombre de résultats demandés.