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, des points de terminaison RESTful pour les paiements, les remboursements, les transactions et le rapprochement, avec des exigences de conformité PCI DSS et des limites de taux standard de l'industrie. Ce guide couvre la configuration de l'authentification, le traitement des paiements, l'intégration des webhooks, la conformité de la sécurité et les stratégies de déploiement en production.

Introduction

Le traitement des paiements numériques représente plus de 8 000 milliards de dollars par an dans le monde. Pour les développeurs qui créent des plateformes de commerce électronique, des applications SaaS ou des solutions de place de marché, l'intégration d'une API de paiement n'est pas une option, elle est essentielle pour accepter les paiements des clients de manière sécurisée et conforme.

Voici la réalité : les entreprises perdent 5 à 10 % de leurs revenus à cause des échecs de paiement, du rapprochement manuel et de la fraude au paiement. Une intégration solide de l'API de paiement automatise le traitement des paiements, réduit les échecs grâce à une logique de nouvelle tentative intelligente, permet le rapprochement automatique et met en œuvre la détection de la fraude.

Ce guide vous accompagne tout au long du processus complet d'intégration de l'API de paiement. Vous apprendrez la configuration de l'authentification, le traitement des paiements, la gestion des remboursements, la gestion des webhooks, la conformité PCI DSS, les meilleures pratiques de sécurité et les stratégies de déploiement en production. À la fin, vous disposerez d'une intégration de paiement prête pour la production.

Remarque : Ce guide couvre les modèles généraux d'intégration d'API de paiement applicables à iPay et aux processeurs de paiement similaires. Les URL des points de terminaison spécifiques et les détails d'authentification peuvent varier—référez-vous toujours à la documentation officielle d'iPay pour les détails d'implémentation.

Qu'est-ce que l'API iPay ?

Les API de paiement comme iPay fournissent des interfaces RESTful pour le traitement des transactions financières. L'API gère :

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

Fonctionnalités clés

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        │                    │
     │◀───────────────────│                    │

Environnement API

Démarrage : Configuration de l'authentification

Étape 1 : Créer un compte iPay

Avant d'accéder à l'API :

1. Visitez l'enregistrement commerçant iPay
2. Complétez la vérification de l'entreprise (KYB)
3. Soumettez les documents requis :

• Enregistrement de l'entreprise
• Coordonnées bancaires
• Pièce d'identité gouvernementale

1. Attendez l'approbation (1 à 3 jours ouvrables)

Étape 2 : Obtenir les identifiants API

Générez les identifiants API :

1. Connectez-vous au tableau de bord marchand iPay
2. Accédez à Paramètres > Clés API
3. Créez une nouvelle clé API
4. Copiez les identifiants en toute sécurité

# .env file (NEVER commit to git)
IPAY_API_KEY="live_xxxxxxxxxxxxxxxxxxxx"
IPAY_API_SECRET="secret_xxxxxxxxxxxxxxxxxxxx"
IPAY_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"

Note de sécurité : Utilisez des clés distinctes pour l'environnement de test (sandbox) et de production.

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

iPay prend en charge plusieurs méthodes d'authentification :

É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;

  // Basic authentication (Base64 encoded)
  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)}`;
}

// Usage
const account = await ipayRequest('/account');
console.log(`Merchant: ${account.business_name}`);

Traitement des paiements

Création d'une intention de paiement

Initialisez le paiement :

const createPayment = async (paymentData) => {
  const payment = {
    amount: paymentData.amount, // In smallest currency unit (cents)
    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' or 'manual'
    statement_descriptor: paymentData.statementDescriptor || 'MYCOMPANY'
  };

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

  return response;
};

// Usage
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}`);

Flux des statuts de paiement

requires_payment_method → requires_confirmation → requires_action
                         → processing → requires_capture → succeeded
                                                        → failed
                                                        → canceled

Méthodes de paiement

Tokenisation des détails de carte

Stockez la carte en toute sécurité pour une utilisation future :

const tokenizeCard = async (cardData) => {
  // NEVER send raw card data to your server
  // Use client-side tokenization instead

  // Client-side (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; // Send token.id to your server
};

// Server-side: Use token to create payment method
const createPaymentMethod = async (tokenId, customerId) => {
  const response = await ipayRequest('/payment_methods', {
    method: 'POST',
    body: JSON.stringify({
      type: 'card',
      token: tokenId,
      customer: customerId
    })
  });

  return response;
};

Authentification 3D Secure

Implémentez la conformité SCA :

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

  if (payment.status === 'requires_action') {
    // Client must complete 3DS challenge
    return {
      requiresAction: true,
      clientSecret: payment.client_secret,
      nextAction: payment.next_action
    };
  }

  return { success: true, payment };
};

// Client-side: Handle 3DS challenge
// Use iPay.js or mobile SDK to present authentication challenge

Gestion des remboursements

Traitement d'un remboursement intégral

Rembourser le paiement 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;
};

// Usage
const refund = await refundPayment('pay_12345', 'duplicate');
console.log(`Refund status: ${refund.status}`);
console.log(`Refund ID: ${refund.id}`);

Traitement d'un remboursement partiel

Rembourser une partie du paiement :

const partialRefund = async (paymentId, amount, reason = null) => {
  const refund = {
    payment: paymentId,
    amount: amount, // In smallest currency unit
    reason: reason || 'requested_by_customer'
  };

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

  return response;
};

// Usage - Refund $15.00 of $29.99 payment
const refund = await partialRefund('pay_12345', 1500, 'partial_ship');
console.log(`Refunded: $${refund.amount / 100}`);

Motifs de remboursement

Gestion des clients

Création d'un client

Stockez le 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;
};

// Usage
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}`);

Associer un mode de paiement à un client

Enregistrez la carte pour une utilisation future :

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

  return response;
};

// Usage
await attachPaymentMethod('pm_67890', 'cus_12345');

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;
};

// Usage
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}`);
});

Webhooks

Configuration des Webhooks

Configurez les points de terminaison de webhook :

1. Connectez-vous au tableau de bord iPay
2. Accédez à Développeurs > Webhooks
3. Cliquez sur Ajouter un point de terminaison
4. Entrez votre URL HTTPS
5. Sélectionnez les événements à s'abonner

Événements de Webhook

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;

  // Verify webhook signature
  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());

  // Route to appropriate handler
  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);
  }

  // Acknowledge receipt
  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}`);

  // Update order status
  await db.orders.update(data.metadata.orderId, {
    status: 'paid',
    paymentId: data.id,
    paidAt: new Date()
  });

  // Send confirmation email
  await sendOrderConfirmation(data.metadata.orderId);
}

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

  // Notify customer
  await sendPaymentFailedEmail(data.customer, data.failure_message);

  // Retry logic or mark order as failed
  await db.orders.update(data.metadata.orderId, {
    status: 'payment_failed',
    failureReason: data.failure_message
  });
}

Sécurité et Conformité

Exigences PCI DSS

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

Bonnes pratiques de sécurité

// 1. Use tokenization - NEVER handle raw card data
const token = await tokenizeCard(cardData); // Client-side

// 2. Implement idempotency for all payment operations
const idempotencyKey = `pay_${orderId}_${Date.now()}`;

// 3. Validate amounts server-side
if (req.body.amount !== calculatedAmount) {
  throw new Error('Amount mismatch - possible tampering');
}

// 4. Log all payment operations (without sensitive data)
logger.info('Payment attempted', {
  orderId,
  amount,
  currency,
  customerId,
  timestamp: new Date().toISOString()
  // NEVER log: card numbers, CVV, full payment method details
});

// 5. Use environment variables for secrets
const apiKey = process.env.IPAY_API_KEY; // Not hardcoded

// 6. Implement rate limiting on payment endpoints
const paymentLimiter = rateLimit({
  windowMs: 60000,
  max: 10 // 10 payment attempts per minute
});

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

Avant de traiter des paiements en direct :

• [ ] Remplissez le questionnaire d'auto-évaluation PCI DSS
• [ ] Utilisez HTTPS pour tous les points de terminaison
• [ ] Stockez les clés API dans une gestion de secrets sécurisée
• [ ] Implémentez la vérification de la signature des webhooks
• [ ] Ajoutez l'idempotence pour toutes les opérations de paiement
• [ ] Configurez une journalisation complète (sans données sensibles)
• [ ] Configurez les règles de détection de fraude
• [ ] Testez les flux de remboursement et de litige
• [ ] Créez un guide d'opération pour les échecs de paiement
• [ ] Mettez en place la surveillance et les alertes
• [ ] Implémentez un processeur de paiement de secours

Cas d'utilisation concrets

Paiement E-commerce

Un détaillant en ligne intègre les paiements :

• Défi : Traitement manuel des paiements, taux d'abandon élevé
• Solution : Processus de paiement sur une seule page avec cartes tokenisées
• Résultat : Augmentation de 35 % de la conversion, paiements instantanés

Facturation d'abonnement SaaS

Une entreprise de logiciels automatise la facturation :

• Défi : Génération et recouvrement manuel des factures
• Solution : Paiements récurrents avec nouvelle tentative automatique
• Résultat : 95 % de paiements à temps, 80 % de gain de temps administratif

Séquestre de place de marché

Une plateforme gère les paiements multipartites :

• Défi : Paiements fractionnés complexes entre fournisseurs
• Solution : Intentions de paiement avec planification des virements
• Résultat : Versements automatisés aux fournisseurs, réduction de la fraude

Conclusion

L'intégration de l'API de paiement exige une attention particulière à la sécurité, à la conformité et à la gestion des erreurs. Points clés à retenir :

• 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 pour prévenir la fraude
• Soyez conforme aux exigences PCI DSS
• Testez minutieusement en mode sandbox avant la production
• Apidog rationalise les tests API et la collaboration d'équipe

Section FAQ

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

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

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

Oui, mais vous devez être conforme PCI DSS. Utilisez la tokenisation pour stocker les cartes en toute sécurité dans le coffre-fort d'iPay.

Comment gérer les paiements échoués ?

Implémentez une logique de nouvelle tentative avec un backoff exponentiel, informez les clients et proposez des méthodes de paiement alternatives.

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é produisent le même résultat, évitant ainsi les frais en double.

Comment tester les paiements sans débiter de cartes ?

Utilisez le mode sandbox avec les numéros de carte de test fournis dans la documentation iPay.

Que sont les signatures de webhook ?

Des signatures cryptographiques qui vérifient que les webhooks proviennent bien d'iPay, et non d'un acteur malveillant.