Aller au contenu principal

Accepter un paiement

Ce guide vous accompagne dans une intégration de paiement complète côté serveur.

Avant de commencer​

Étapes d’intégration​

Étape 1 : Créer un PaymentIntent (côté serveur)​

Créez un PaymentIntent sur votre serveur quand le client initie le checkout.

curl -X POST https://api.ikawaari.com/v1/payment-intents \
  -H "Authorization: Bearer ik_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "XOF",
    "payment_method_types": ["mobile_money", "card"],
    "metadata": {
      "order_id": "order_123"
    }
  }'

Étape 2 : Collecter les détails de paiement​

Option A : Rediriger vers Ikawaari Checkout​

L’intégration la plus simple — redirigez le client vers une page de paiement hébergée :

const session = await ik.checkoutSessions.create({
  payment_intent: paymentIntent.id,
  success_url: 'https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://yoursite.com/cancel',
});

// Redirigez le client vers session.url

Option B : Utiliser Payment Links (sans code)​

Créez un lien de paiement réutilisable depuis le dashboard — aucun code requis. Voir Payment Links.

Option C : UI personnalisée​

Construisez votre propre formulaire de paiement et confirmez le paiement :

// Confirmer avec mobile money
const result = await ik.paymentIntents.confirm(paymentIntent.id, {
  payment_method: {
    type: 'mobile_money',
    mobile_money: {
      phone: '+2250700000000',
      operator: 'orange_ci',
    },
  },
});

Étape 3 : Traiter le résultat du paiement​

Après confirmation, le paiement entre dans l’état processing. Pour le mobile money, le client reçoit une invite USSD sur son téléphone.

{
  "id": "pi_1a2b3c4d5e",
  "status": "processing",
  "next_action": {
    "type": "mobile_money_ussd",
    "mobile_money_ussd": {
      "message": "Please confirm the payment on your phone"
    }
  }
}

Étape 4 : Écouter les webhooks​

Configurez un endpoint webhook pour recevoir les confirmations de paiement :

// POST /webhooks/ikawaari
app.post('/webhooks/ikawaari', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data;
      // Traiter la commande
      fulfillOrder(paymentIntent.metadata.order_id);
      break;
    case 'payment_intent.payment_failed':
      // Notifier le client
      notifyCustomer(event.data.metadata.order_id);
      break;
  }

  res.json({ received: true });
});
Important

Utilisez toujours les webhooks pour confirmer le succès d’un paiement. Ne vous reposez pas uniquement sur les redirections côté client.

Gestion des erreurs​

Code d’erreurDescriptionAction
insufficient_fundsLe client n’a pas assez de balanceDemander au client de recharger
payment_timeoutLe client n’a pas confirmé à tempsCréer un nouveau paiement
provider_unavailableL’opérateur mobile money est indisponibleRéessayer ou proposer une méthode alternative
invalid_phoneLe format du numéro de téléphone est incorrectValider le format du numéro

Étapes suivantes​