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 de retour pour les flux redirigés.

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

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.