DEV Community

Cover image for Comment utiliser l'API iPay pour l'intégration de paiement en 2026 ?
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser l'API iPay pour l'intégration de paiement en 2026 ?

En bref

L'API iPay permet aux développeurs d'intégrer le traitement des paiements, la facturation et les transactions financières par programmation. Elle utilise l'authentification OAuth 2.0 et les clés API, propose des points de terminaison RESTful pour les paiements, remboursements, transactions et rapprochement, avec des exigences de conformité PCI DSS et des limites de taux standard. Ce guide détaille la configuration de l'authentification, le traitement des paiements, l'intégration des webhooks, la conformité sécurité et les stratégies de déploiement en production.

Essayez Apidog dès aujourd'hui

Introduction

Le traitement des paiements numériques dépasse 8 000 milliards de dollars par an à l'échelle mondiale. Pour les développeurs de plateformes e-commerce, applications SaaS ou marketplaces, l'intégration d'une API de paiement est indispensable pour accepter les paiements clients de manière sécurisée et conforme.

Les entreprises perdent entre 5 et 10 % de leur chiffre d'affaires à cause des échecs de paiement, du rapprochement manuel et de la fraude. Une intégration robuste d'API de paiement automatise le traitement, réduit les échecs grâce à la relance intelligente, facilite le rapprochement automatique et permet la détection de fraude.

Ce guide vous fournit les étapes clés pour intégrer une API de paiement iPay prête pour la production : configuration de l’authentification, gestion des paiements et remboursements, intégration des webhooks, conformité PCI DSS, sécurité et déploiement.

💡 Astuce : Apidog simplifie le test de l'API de paiement. Testez les endpoints en sandbox, validez les signatures de webhook, inspectez les réponses de transaction et déboguez l'intégration dans un seul workspace. Importez la spec API, simulez les réponses, partagez les tests avec votre équipe.

Remarque : Ce guide décrit des modèles d'intégration génériques pour les APIs de paiement dont iPay. Les URL de endpoints et détails d'authentification peuvent différer—consultez toujours la documentation officielle iPay pour les détails précis.

Qu'est-ce que l'API iPay ?

Les APIs de paiement comme iPay offrent une interface RESTful pour gérer :

  • Autorisation et capture des paiements
  • Remboursements et rejets de débit
  • Historique des transactions et reporting
  • Tokenisation des clients (coffre-fort)
  • Abonnements et facturation récurrente
  • Génération/gestion des factures
  • Rapprochement et règlement
  • Détection/prévention de la fraude

Fonctionnalités clés

Fonctionnalité Description
API RESTful Endpoints JSON
OAuth 2.0 + Clés API Authentification sécurisée
Webhooks Notifications en temps réel
Tokenisation Stockage sécurisé des cartes
3D Secure Conformité SCA
PCI DSS Conformité de niveau 1 requise
Multi-devises + de 100 devises supportées
Outils anti-fraude Évaluation des risques, contrôles vélocité

Aperçu du flux de paiement 

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Customer  │───▶│   Merchant  │───▶│  Payment    │
│   (Browser) │    │   (Server)  │    │  Gateway    │
└─────────────┘    └─────────────┘    └─────────────┘
     │                    │                    │
     │  1. Enter Card     │                    │
     │───────────────────▶│                    │
     │                    │                    │
     │  2. Tokenize       │                    │
     │───────────────────▶│  3. Create Intent  │
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  4. Confirm Payment│
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  5. Result         │
     │                    │◀───────────────────│
     │                    │                    │
     │  6. Receipt        │                    │
     │◀───────────────────│                    │
Enter fullscreen mode Exit fullscreen mode

Environnement API

Environnement URL Cas d'utilisation
Sandbox https://sandbox.ipay.com/api Développement, test
Production https://api.ipay.com/api Transactions en direct

Démarrage : Configuration de l'authentification

Étape 1 : Créer un compte iPay

  1. Rendez-vous sur la page d'inscription commerçant iPay
  2. Effectuez la vérification d'entreprise (KYB)
  3. Envoyez les documents demandés :
    • Enregistrement société
    • Coordonnées bancaires
    • Pièce d'identité officielle
  4. Attendez la validation (1 à 3 jours ouvrés)

Étape 2 : Obtenir les identifiants API

Générez vos credentials API :

  1. Connectez-vous au dashboard marchand iPay
  2. Naviguez vers Paramètres > Clés API
  3. Créez une nouvelle clé API
  4. Copiez les identifiants en lieu sûr 
# .env file (NEVER commit to git)
IPAY_API_KEY="live_xxxxxxxxxxxxxxxxxxxx"
IPAY_API_SECRET="secret_xxxxxxxxxxxxxxxxxxxx"
IPAY_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"
Enter fullscreen mode Exit fullscreen mode

Sécurité : Utilisez des clés séparées pour sandbox et production.

Étape 3 : Comprendre les méthodes d'authentification

Méthode Idéal pour Sécurité
Authentification de base Serveur à serveur Élevé
OAuth 2.0 Apps multi-tenants Très élevé
JWT Microservices Élevé

Étape 4 : Effectuer des appels API authentifiés

Créez un client API réutilisable :

const IPAY_BASE_URL = process.env.IPAY_SANDBOX
  ? 'https://sandbox.ipay.com/api'
  : 'https://api.ipay.com/api';

const ipayRequest = async (endpoint, options = {}) => {
  const apiKey = process.env.IPAY_API_KEY;
  const apiSecret = process.env.IPAY_API_SECRET;

  // Authentification de base (Base64)
  const authHeader = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

  const response = await fetch(`${IPAY_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Basic ${authHeader}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': options.idempotencyKey || generateIdempotencyKey(),
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`iPay API Error: ${error.message}`);
  }

  return response.json();
};

function generateIdempotencyKey() {
  return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}

// Exemple d'utilisation
const account = await ipayRequest('/account');
console.log(`Merchant: ${account.business_name}`);
Enter fullscreen mode Exit fullscreen mode

Traitement des paiements

Création d'une intention de paiement

Initialisez le paiement :

const createPayment = async (paymentData) => {
  const payment = {
    amount: paymentData.amount, // En centimes
    currency: paymentData.currency || 'USD',
    customer: paymentData.customerId,
    payment_method: paymentData.paymentMethodId,
    confirm: true,
    description: paymentData.description,
    metadata: {
      orderId: paymentData.orderId,
      customerId: paymentData.customerId
    },
    capture_method: paymentData.captureMethod || 'automatic', // 'automatic' ou 'manual'
    statement_descriptor: paymentData.statementDescriptor || 'MYCOMPANY'
  };

  const response = await ipayRequest('/payments', {
    method: 'POST',
    body: JSON.stringify(payment),
    idempotencyKey: paymentData.idempotencyKey
  });

  return response;
};

// Exemple d'utilisation
const payment = await createPayment({
  amount: 2999, // $29.99
  currency: 'USD',
  customerId: 'cus_12345',
  paymentMethodId: 'pm_67890',
  description: 'Order #ORD-001',
  orderId: 'ORD-001',
  statementDescriptor: 'MYCOMPANY INC'
});

console.log(`Payment status: ${payment.status}`);
console.log(`Payment ID: ${payment.id}`);
Enter fullscreen mode Exit fullscreen mode

Flux des statuts de paiement 

requires_payment_method → requires_confirmation → requires_action
                         → processing → requires_capture → succeeded
                                                        → failed
                                                        → canceled
Enter fullscreen mode Exit fullscreen mode

Méthodes de paiement

Méthode Type Cas d'utilisation
carte Crédit/Débit Paiements standards
virement_bancaire ACH, SEPA Virements à faible coût
portefeuille_numérique Apple/Google Pay Paiement mobile
acheter_maintenant_payer_plus_tard Klarna, Afterpay Paiements échelonnés

Tokenisation des détails de carte

Stockez la carte de façon sécurisée :

const tokenizeCard = async (cardData) => {
  // NE JAMAIS envoyer les données de carte brutes au serveur
  // Utilisez la tokenisation côté client

  // Côté client (browser/mobile)
  const response = await fetch(`${IPAY_BASE_URL}/tokens`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${CLIENT_PUBLISHABLE_KEY}`
    },
    body: JSON.stringify({
      card: {
        number: cardData.number,
        exp_month: cardData.expMonth,
        exp_year: cardData.expYear,
        cvc: cardData.cvc
      }
    })
  });

  const token = await response.json();
  return token; // Transmettez token.id au serveur
};

// Côté serveur : utiliser le token pour créer un mode de paiement
const createPaymentMethod = async (tokenId, customerId) => {
  const response = await ipayRequest('/payment_methods', {
    method: 'POST',
    body: JSON.stringify({
      type: 'card',
      token: tokenId,
      customer: customerId
    })
  });

  return response;
};
Enter fullscreen mode Exit fullscreen mode

Authentification 3D Secure

Implémentez la conformité SCA :

const createPaymentWith3DS = async (paymentData) => {
  const payment = await createPayment({
    ...paymentData,
    confirmation_token: true // Retourne le client secret pour 3DS
  });

  if (payment.status === 'requires_action') {
    // Le client doit effectuer le challenge 3DS
    return {
      requiresAction: true,
      clientSecret: payment.client_secret,
      nextAction: payment.next_action
    };
  }

  return { success: true, payment };
};

// Côté client : gérez le challenge 3DS via iPay.js ou SDK mobile
Enter fullscreen mode Exit fullscreen mode

Gestion des remboursements

Traitement d'un remboursement intégral 

const refundPayment = async (paymentId, reason = null) => {
  const refund = {
    payment: paymentId,
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${Date.now()}`
  });

  return response;
};

// Exemple d'utilisation
const refund = await refundPayment('pay_12345', 'duplicate');
console.log(`Refund status: ${refund.status}`);
console.log(`Refund ID: ${refund.id}`);
Enter fullscreen mode Exit fullscreen mode

Traitement d'un remboursement partiel 

const partialRefund = async (paymentId, amount, reason = null) => {
  const refund = {
    payment: paymentId,
    amount: amount, // En centimes
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${amount}_${Date.now()}`
  });

  return response;
};

// Exemple : rembourser $15.00 sur un paiement de $29.99
const refund = await partialRefund('pay_12345', 1500, 'partial_ship');
console.log(`Refunded: $${refund.amount / 100}`);
Enter fullscreen mode Exit fullscreen mode

Motifs de remboursement

Code du motif Description
duplicata Charge en double
frauduleux Transaction frauduleuse
demandé_par_le_client Demande du client
commande_annulée Annulation de commande
produit_non_reçu Article non livré
produit_non_conforme Article différent de la description

Gestion des clients

Création d'un client

Stockez un client pour les paiements récurrents :

const createCustomer = async (customerData) => {
  const customer = {
    email: customerData.email,
    name: customerData.name,
    phone: customerData.phone,
    metadata: {
      internalId: customerData.internalId,
      tier: customerData.tier
    }
  };

  const response = await ipayRequest('/customers', {
    method: 'POST',
    body: JSON.stringify(customer)
  });

  return response;
};

// Exemple d'utilisation
const customer = await createCustomer({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '+1-555-0123',
  internalId: 'USR-12345',
  tier: 'premium'
});

console.log(`Customer created: ${customer.id}`);
Enter fullscreen mode Exit fullscreen mode

Associer un mode de paiement à un client

Enregistrez la carte pour un usage futur :

const attachPaymentMethod = async (paymentMethodId, customerId) => {
  const response = await ipayRequest(`/payment_methods/${paymentMethodId}/attach`, {
    method: 'POST',
    body: JSON.stringify({
      customer: customerId
    })
  });

  return response;
};

// Exemple d'utilisation
await attachPaymentMethod('pm_67890', 'cus_12345');
Enter fullscreen mode Exit fullscreen mode

Liste des modes de paiement du client

Obtenez les cartes enregistrées :

const getCustomerPaymentMethods = async (customerId) => {
  const response = await ipayRequest(`/customers/${customerId}/payment_methods`);
  return response;
};

// Exemple d'utilisation
const methods = await getCustomerPaymentMethods('cus_12345');
methods.data.forEach(method => {
  console.log(`${method.card.brand} ending in ${method.card.last4}`);
  console.log(`Expires: ${method.card.exp_month}/${method.card.exp_year}`);
});
Enter fullscreen mode Exit fullscreen mode

Webhooks

Configuration des Webhooks

  1. Connectez-vous au dashboard iPay
  2. Allez dans Développeurs > Webhooks
  3. Cliquez sur Ajouter un point de terminaison
  4. Saisissez votre URL HTTPS
  5. Sélectionnez les événements à suivre

Événements de Webhook

Événement Déclencheur
payment.succeeded Paiement réussi
payment.failed Paiement refusé
payment.refunded Remboursement traité
payment.disputed Contestation déposée
customer.created Nouveau client
customer.subscription.updated Abonnement modifié

Gestion des Webhooks 

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/ipay', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['ipay-signature'];
  const payload = req.body;

  // Vérification de la signature du webhook
  const isValid = verifyWebhookSignature(payload, signature, process.env.IPAY_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Unauthorized');
  }

  const event = JSON.parse(payload.toString());

  // Routage selon l'événement
  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    case 'payment.refunded':
      await handlePaymentRefunded(event.data);
      break;
    case 'payment.disputed':
      await handlePaymentDisputed(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  // Accusé de réception
  res.status(200).send('OK');
});

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

async function handlePaymentSucceeded(data) {
  console.log(`Payment succeeded: ${data.id}`);

  // Mise à jour du statut commande
  await db.orders.update(data.metadata.orderId, {
    status: 'paid',
    paymentId: data.id,
    paidAt: new Date()
  });

  // Email de confirmation
  await sendOrderConfirmation(data.metadata.orderId);
}

async function handlePaymentFailed(data) {
  console.log(`Payment failed: ${data.id} - ${data.failure_code}`);

  // Notification client
  await sendPaymentFailedEmail(data.customer, data.failure_message);

  // Logique de relance ou marquage échoué
  await db.orders.update(data.metadata.orderId, {
    status: 'payment_failed',
    failureReason: data.failure_message
  });
}
Enter fullscreen mode Exit fullscreen mode

Sécurité et Conformité

Exigences PCI DSS

Les intégrations de paiement doivent être conformes à PCI DSS :

Exigence Implémentation
Réseau sécurisé HTTPS, firewall, configurations sécurisées
Protection des données du titulaire Jamais stocker CVV, chiffrer le PAN
Gestion des vulnérabilités Mises à jour sécurité, antivirus
Contrôle d'accès Moindre privilège, MFA, IDs uniques
Surveillance Logs, détection d'intrusion
Politique de sécurité Politiques documentées, formation régulière

Bonnes pratiques de sécurité 

// 1. Utilisez la tokenisation — NE JAMAIS manipuler les cartes brutes
const token = await tokenizeCard(cardData); // Côté client

// 2. Implémentez l'idempotence sur toutes les opérations paiement
const idempotencyKey = `pay_${orderId}_${Date.now()}`;

// 3. Validez les montants côté serveur
if (req.body.amount !== calculatedAmount) {
  throw new Error('Amount mismatch - possible tampering');
}

// 4. Loggez toutes les opérations paiement (sans données sensibles)
logger.info('Payment attempted', {
  orderId,
  amount,
  currency,
  customerId,
  timestamp: new Date().toISOString()
  // NE PAS logguer : numéros de carte, CVV, détails complets
});

// 5. Utilisez les variables d'environnement pour les secrets
const apiKey = process.env.IPAY_API_KEY; // Jamais en dur

// 6. Limitez le débit sur les endpoints paiement
const paymentLimiter = rateLimit({
  windowMs: 60000,
  max: 10 // 10 tentatives paiement/min
});
Enter fullscreen mode Exit fullscreen mode

Liste de contrôle pour le déploiement en production

Avant de passer en live :

  • [ ] Questionnaire d'auto-évaluation PCI DSS complété
  • [ ] HTTPS pour tous les endpoints
  • [ ] Clés API stockées dans un gestionnaire de secrets
  • [ ] Vérification signature des webhooks
  • [ ] Idempotence pour chaque opération paiement
  • [ ] Journalisation complète (sans données sensibles)
  • [ ] Règles de détection de fraude configurées
  • [ ] Tests complets des flux remboursement et litige
  • [ ] Guide d'opération pour les paiements échoués
  • [ ] Monitoring et alertes en place
  • [ ] Processeur de paiement de secours configuré

Cas d'utilisation concrets

Paiement E-commerce

  • Défi : Paiement manuel, taux d'abandon élevé
  • Solution : Paiement en une page avec cartes tokenisées
  • Résultat : +35% conversion, paiements instantanés

Facturation d'abonnement SaaS

  • Défi : Facturation et recouvrement manuels
  • Solution : Paiements récurrents avec relance automatique
  • Résultat : 95% paiements à temps, 80% de gain admin

Séquestre de place de marché

  • Défi : Paiements fractionnés complexes
  • Solution : Intentions de paiement + planification des virements
  • Résultat : Payouts automatisés, fraude réduite

Conclusion

Pour intégrer une API de paiement de façon fiable :

  • Ne jamais manipuler de données de carte brutes—utilisez la tokenisation
  • Implémentez l'idempotence pour toutes les opérations de paiement
  • Vérifiez les signatures de webhook contre la fraude
  • Soyez conforme PCI DSS
  • Testez en profondeur en sandbox avant la prod
  • Apidog rationalise les tests API et la collaboration équipe

Section FAQ

Comment m'authentifier auprès de l'API iPay ?

Utilisez l'authentification de base avec clé API et secret, ou OAuth 2.0 pour les applications multi-locataires.

Puis-je stocker les détails de carte du client ?

Oui, mais seulement via la tokenisation et le coffre-fort iPay, et en respectant la conformité PCI DSS.

Comment gérer les paiements échoués ?

Mettez en place une logique de relance avec backoff exponentiel, informez les clients et proposez d'autres moyens de paiement.

Qu'est-ce que l'idempotence et pourquoi est-elle importante ?

L'idempotence garantit que des requêtes dupliquées avec la même clé ne génèrent pas de frais doubles.

Comment tester les paiements sans débiter de cartes ?

Passez par le mode sandbox et utilisez les numéros de carte de test de la documentation iPay.

Que sont les signatures de webhook ?

Des signatures cryptographiques qui valident que les webhooks viennent bien d'iPay et non d'un tiers malveillant.

Top comments (0)