Tester les intégrations de paiement : guide de l'environnement sandbox

Intégration API

Tester les intégrations de paiement : guide de l'environnement sandbox

15 janvier 2025 8 min de lecture Équipe TIB Finance

Table des matières

Aperçu de l'environnement sandbox
Identifiants sandbox
Numéros de cartes de test
Simuler différentes réponses
Tester les cas d'erreur
Tester les webhooks
Liste de vérification avant la mise en production

L'une des causes les plus fréquentes d'échecs de paiement en production est un test insuffisant. Une intégration qui ne gère que le scénario idéal, soit une transaction par carte réussie, échouera de façon spectaculaire face à une carte refusée, un moyen de paiement expiré, un délai réseau dépassé ou une exigence d'authentification 3DS. L'environnement sandbox de TIB Finance existe justement pour vous permettre de rencontrer et de gérer tous ces scénarios avant vos clients.

Ce guide couvre tout ce qu'il faut savoir pour utiliser le sandbox de TIB Finance afin de bâtir une suite de tests rigoureuse. Combiné au guide d'intégration de l'API, il vous donne un portrait complet pour construire et valider une intégration de qualité production.

Aperçu de l'environnement sandbox

Le sandbox de TIB Finance est un environnement entièrement isolé qui reproduit les fonctionnalités de l'API de production, mais ne traite aucune transaction réelle et ne facture aucun montant réel. Principales caractéristiques :

Point d'accès API distinct : https://sandbox-api.tib.finance/v1, distinct de l'URL de production.
Identifiants distincts : les clés API sandbox commencent par sk_test_ et pk_test_. Les clés de production utilisent sk_live_ et pk_live_. Ne les mélangez jamais.
Tableau de bord sandbox : consultez les transactions, clients et événements sandbox depuis le tableau de bord sandbox de TIB Finance, distinct de votre tableau de bord marchand en direct.
Les données de test ne sont pas réelles : aucun fonds réel ne bouge. Aucun émetteur de carte n'est contacté. Toutes les réponses sont simulées selon le numéro de carte de test utilisé.
Parité complète des fonctionnalités : les webhooks, la tokenisation, le 3DS, les remboursements, les litiges et toutes les autres fonctionnalités sont disponibles dans le sandbox.

Conseil : incluez toujours une vérification d'environnement au démarrage de votre application afin de confirmer que les identifiants sandbox ne sont jamais utilisés en production et que les identifiants de production ne sont jamais utilisés en développement.

Identifiants sandbox

Accédez à vos identifiants sandbox depuis le tableau de bord développeur de TIB Finance. Vous y trouverez :

Clé secrète sandbox : sk_test_xxxxxxxxxxxxxxxxxxxx, à utiliser sur votre serveur
Clé publiable sandbox : pk_test_xxxxxxxxxxxxxxxxxxxx, à utiliser dans le JavaScript côté client
Secret webhook sandbox : utilisé pour vérifier les signatures des webhooks sandbox (distinct du secret webhook de production)

Conservez les identifiants sandbox dans un fichier .env.test ou .env.development distinct de votre fichier de production .env ou .env.production. Votre pipeline de déploiement doit définir les variables d'environnement à partir du fichier approprié selon l'environnement cible.

Numéros de cartes de test

TIB Finance fournit un ensemble de numéros de cartes de test qui déclenchent des réponses précises. Utilisez n'importe quelle date d'expiration future (par exemple, 12/27), n'importe quel CVV à 3 chiffres (par exemple, 123) et n'importe quel code postal de facturation valide (par exemple, 10001).

Numéro de carte	Marque	Résultat
4111 1111 1111 1111	Visa	payment.succeeded
5500 0000 0000 0004	Mastercard	payment.succeeded
3714 496353 98431	Amex	payment.succeeded
6011 1111 1111 1117	Discover	payment.succeeded
4000 0000 0000 0002	Visa	card_declined
4000 0000 0000 9995	Visa	insufficient_funds
4000 0000 0000 0069	Visa	expired_card
4000 0000 0000 0127	Visa	incorrect_cvc
4000 0027 6000 3184	Visa	authentication_required (3DS)
4000 0000 0000 3220	Visa	payment.pending (asynchrone)

Simuler différentes réponses

Au-delà des cartes de test spécifiques, le sandbox de TIB Finance prend en charge d'autres mécanismes de simulation :

Simulation basée sur le montant

Vous pouvez déclencher des comportements précis selon le montant défini dans les transactions de test :

Montant se terminant par ,01 (par exemple, 49,01 $ / 4901 cents) : déclenche un refus générique
Montant se terminant par ,02 : déclenche un refus pour fonds insuffisants
Montant de exactement 0,00 $ / 0 cent : déclenche une vérification de carte (autorisation à zéro)
Montant supérieur à 999,99 $ : déclenche une réponse authentication_required

Tester le flux d'authentification 3DS

Utilisez le numéro de carte 4000 0027 6000 3184 pour tester le flux complet d'authentification 3D Secure 2. Dans le sandbox, la page de défi 3DS affiche un code de passe 424242 pour une authentification réussie, ou vous pouvez soumettre un code incorrect pour tester un échec 3DS. Votre intégration doit gérer la réponse requires_action et guider le client tout au long du flux d'authentification.

Tester les cas d'erreur

Une intégration robuste gère chaque erreur avec élégance. Voici une approche systématique pour tester les cas d'erreur :

Erreurs réseau et d'infrastructure

Simulation de délai dépassé : utilisez la carte spéciale 4000 0000 0000 1000 dans le sandbox pour simuler un délai dépassé de la passerelle. Votre code doit gérer les délais dépassés avec une logique de nouvelle tentative appropriée, à l'aide de votre clé d'idempotence.
Limitation du débit : envoyez plus de 100 requêtes API par seconde pour déclencher une erreur HTTP 429. Vérifiez votre logique de nouvelle tentative avec délai exponentiel.
Erreur serveur (500) : définissez l'en-tête X-TIB-Simulate-Error: 500 dans les requêtes sandbox pour simuler une erreur serveur. Sécuritaire uniquement avec des clés d'idempotence.

Erreurs de validation des données

// Tester les champs requis manquants
POST /v1/transactions
{
  // 'amount' manquant — devrait retourner 400 invalid_request
  "currency": "USD",
  "payment_method": "pm_test_xxx"
}

// Tester un format de numéro de carte invalide
// Utiliser le numéro de carte : 4000 0000 0000 XXXX où XXXX échoue la vérification de Luhn
// Devrait retourner : invalid_card_number

// Tester explicitement une carte expirée
// Carte : 4000 0000 0000 0069 — retourne expired_card
                        

Erreurs d'authentification

Utilisez une clé API invalide pour vérifier que votre intégration retourne un 401 et n'expose pas la clé invalide dans les journaux ou les messages d'erreur
Utilisez une clé publiable pour une opération côté serveur afin de vérifier que votre intégration détecte et gère l'erreur de « mauvais type de clé »
Testez avec une clé API expirée ou révoquée en désactivant temporairement une clé de test dans le tableau de bord

Tester les webhooks dans le sandbox

Le tableau de bord sandbox de TIB Finance offre un outil de test de webhooks qui vous permet de déclencher manuellement n'importe quel type d'événement vers votre point de terminaison enregistré, sans avoir à créer une transaction qui génère l'événement naturellement. C'est très utile pour tester des événements marginaux comme dispute.created ou refund.failed.

Utiliser l'inspecteur de webhooks du sandbox

Accédez à Paramètres > Webhooks dans le tableau de bord sandbox
Sélectionnez votre point de terminaison webhook
Cliquez sur « Envoyer un événement de test » et sélectionnez le type d'événement
L'inspecteur affiche la charge utile sortante, la réponse de votre point de terminaison et le statut de livraison
Pour le développement local, utilisez un outil comme ngrok pour exposer votre serveur local avec une URL HTTPS publique

Tests automatisés de webhooks

// Exemple de test Jest pour un gestionnaire de webhook
const crypto = require('crypto');

test('traite le webhook payment.succeeded', async () => {
  const payload = JSON.stringify({
    id: 'evt_test_001',
    type: 'payment.succeeded',
    data: { object: { id: 'txn_test_001', reference: 'ORDER-001', status: 'succeeded' } }
  });

  const timestamp = Math.floor(Date.now() / 1000);
  const signature = crypto
    .createHmac('sha256', process.env.TEST_WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  const response = await request(app)
    .post('/webhook')
    .set('TIB-Signature', `t=${timestamp},v1=${signature}`)
    .set('Content-Type', 'application/json')
    .send(payload);

  expect(response.status).toBe(200);
  // Vérifier que la logique métier a été exécutée
  expect(mockOrderFulfillment).toHaveBeenCalledWith('ORDER-001');
});
                        

Liste de vérification avant la mise en production

Lorsque vos tests sandbox sont complets et que tous les cas de test réussissent, utilisez cette liste pour confirmer que vous êtes prêt pour la production :

Tous les flux de paiement testés : transaction réussie, carte refusée, fonds insuffisants, carte expirée, CVV incorrect, authentification 3DS

Gestion des erreurs vérifiée : tous les codes d'erreur de la référence API ont des messages correspondants destinés aux utilisateurs

Webhooks implémentés et testés : tous les types d'événements pertinents sont gérés, la vérification de signature est en place, l'idempotence est implémentée

Clés d'idempotence utilisées : toutes les requêtes de création de transaction incluent des clés d'idempotence uniques

Clés API dans les variables d'environnement : aucune clé codée en dur dans le code source ou le contrôle de version

URL de production configurée : les appels API pointent vers api.tib.finance et non sandbox-api.tib.finance

TLS appliqué : toutes les pages de paiement et les appels API utilisent HTTPS

Indicateur livemode vérifié : l'application vérifie le champ livemode dans les réponses API et les événements webhook

Journalisation en place : tous les événements de paiement, erreurs API et livraisons de webhooks sont journalisés à des fins d'audit et de débogage

Surveillance et alertes : des alertes sont configurées pour les taux d'échec de paiement élevés ou les échecs de livraison de webhooks

Point de terminaison webhook de production configuré : distinct du point de terminaison sandbox, avec le secret webhook de production

Test de fumée en production : complétez une véritable transaction avec une vraie carte immédiatement après le déploiement en production

Accédez au sandbox de TIB Finance

Le sandbox de TIB Finance offre un accès API complet, des numéros de cartes de test, une simulation de webhooks et un environnement de test complet, entièrement gratuit.

Ouvrir le sandbox Documentation API

Tester les intégrations de paiement : guide de l'environnement sandbox