Intégration de l'API de paiement : guide complet pour développeurs

Intégration API

Intégration de l'API de paiement : guide complet pour développeurs

1er août 2024 15 min de lecture Équipe TIB Finance

Table des matières

Bases de l'API REST pour les paiements
Authentification
Création de sessions de paiement
Traitement des transactions
Gestion des réponses
Référence des codes d'erreur
Webhooks
SDK : .NET, PHP, Python, JavaScript
Liste de vérification avant la mise en production

Intégrer une API de paiement est l'une des décisions techniques les plus lourdes de conséquences dans toute application qui accepte de l'argent. Bien réalisée, elle offre une expérience client fluide, une sécurité à toute épreuve et une base qui évolue avec votre entreprise. Mal réalisée, elle crée des failles de sécurité, des échecs de paiement et un cauchemar de conformité.

Ce guide passe en revue chaque étape d'une intégration à l'API de TIB Finance, de l'authentification initiale jusqu'au déploiement en production. Tous les points de terminaison de l'API sont documentés en détail dans la documentation pour développeurs de TIB Finance. Utilisez l'environnement de bac à sable de TIB Finance pour tout tester avant la mise en production.

Bases de l'API REST pour les paiements

L'API de TIB Finance est une API RESTful qui communique par HTTPS. Les API REST (Representational State Transfer) utilisent des méthodes HTTP standards et retournent des réponses au format JSON. Avant de plonger dans les concepts propres aux paiements, assurez-vous d'être à l'aise avec :

Méthodes HTTP : POST (créer), GET (récupérer), PUT/PATCH (mettre à jour), DELETE (supprimer)
Codes de statut : 200/201 (succès), 400 (requête invalide), 401 (non autorisé), 404 (introuvable), 422 (erreur de validation), 500 (erreur serveur)
En-têtes de requête : Content-Type, Authorization, et en-têtes propres aux paiements
Corps de requête et de réponse en JSON
Idempotence : essentielle pour les paiements, soit la capacité de réessayer une requête en toute sécurité sans créer de charges en double

Toutes les requêtes API doivent être effectuées en HTTPS. Les requêtes HTTP seront rejetées. L'URL de base pour la production est https://api.tib.finance/v1 et pour le bac à sable, https://sandbox-api.tib.finance/v1.

Authentification

L'API de TIB Finance utilise l'authentification par clé API. Chaque requête doit inclure votre clé API dans l'en-tête Authorization, au format jeton porteur (Bearer). Vous disposerez de deux types de clés :

Clé API secrète : utilisée pour les requêtes côté serveur. Cette clé donne un accès complet à l'API. Ne l'exposez jamais dans du JavaScript côté client, des applications mobiles ou des dépôts publics.
Clé publiable : utilisée dans le code côté client pour initialiser les champs de paiement. Sa portée est limitée : elle ne peut servir qu'à tokeniser les données de carte, pas à facturer ou récupérer des informations sensibles.

# All server-side API requests
curl https://api.tib.finance/v1/transactions \
  -H "Authorization: Bearer sk_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json"
                        

Faites tourner vos clés API immédiatement si vous soupçonnez qu'elles ont été compromises. Les clés peuvent être régénérées à partir de votre tableau de bord marchand TIB Finance. N'inscrivez jamais de clés API directement dans le code source, utilisez des variables d'environnement ou un service de gestion des secrets.

Création de sessions de paiement

Pour les intégrations utilisant les champs de paiement hébergés de TIB Finance, le flux commence sur votre serveur par la création d'une session de paiement. Une session représente l'intention de percevoir un paiement pour un montant donné et retourne un jeton côté client que votre interface utilise pour initialiser les champs de paiement.

POST /v1/sessions

// Request body
{
  "amount": 4999,          // Amount in cents (e.g., $49.99)
  "currency": "USD",
  "reference": "ORDER-20240801-001",  // Your internal order ID
  "customer": {
    "email": "[email protected]",
    "name": "Jane Smith"
  },
  "capture_method": "automatic",  // or "manual" for auth-only
  "idempotency_key": "ide_ORDER-20240801-001"
}

// Response
{
  "session_id": "ses_7Xb3nP9mQrL2vK8w",
  "client_secret": "ses_7Xb3nP9mQrL2vK8w_secret_...",
  "expires_at": "2024-08-01T13:30:00Z",
  "status": "pending"
}
                        

Le client_secret est transmis à votre interface et sert à initialiser la bibliothèque JavaScript des champs de paiement de TIB Finance. Les données de carte réelles sont saisies directement dans ces champs hébergés et ne transitent jamais par vos serveurs.

Traitement des transactions

Une fois que le client a saisi les détails de sa carte dans les champs de paiement hébergés et a soumis le formulaire, la bibliothèque JavaScript de TIB Finance gère la tokenisation et rappelle votre serveur avec un jeton de méthode de paiement. Votre serveur utilise alors ce jeton pour confirmer la session de paiement ou créer une transaction directement.

Confirmer une session (flux recommandé)

POST /v1/sessions/{session_id}/confirm

// Request
{
  "payment_method": "pm_3Kd9fN7mQpJ2vH4x"  // Token from hosted fields
}

// Successful response (HTTP 200)
{
  "transaction_id": "txn_9Yc4oQ8nRsM3wL5z",
  "status": "succeeded",
  "amount": 4999,
  "currency": "USD",
  "reference": "ORDER-20240801-001",
  "payment_method": {
    "token": "pm_3Kd9fN7mQpJ2vH4x",
    "last4": "1111",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2027
  },
  "created_at": "2024-08-01T12:34:56Z"
}
                        

Facturer une méthode de paiement enregistrée

Pour les clients récurrents disposant d'un jeton de méthode de paiement enregistré, vous pouvez créer une transaction directement, sans passer par une session de champs hébergés :

POST /v1/transactions

{
  "amount": 4999,
  "currency": "USD",
  "payment_method": "pm_3Kd9fN7mQpJ2vH4x",
  "reference": "SUBSCRIPTION-202408",
  "idempotency_key": "sub_SUBSCRIPTION-202408"
}
                        

Gestion des réponses

Chaque réponse de l'API inclut un champ status. Pour les transactions, les statuts possibles sont :

succeeded : la transaction a été approuvée et les fonds seront capturés (ou ont déjà été capturés).
pending : la transaction est en cours de traitement. Attendez-vous à un événement webhook lorsqu'elle sera résolue.
requires_action : une authentification 3DS est requise. Suivez les instructions next_action de la réponse.
failed : la transaction a été refusée ou a échoué. Consultez l'objet error pour les détails.
refunded / partially_refunded : un remboursement complet ou partiel a été traité.

Vérifiez toujours le champ status plutôt que de vous fier uniquement au code de statut HTTP. Une réponse 200 avec status: "failed" signifie que la requête HTTP a réussi, mais que le paiement a été refusé.

Référence des codes d'erreur

L'API de TIB Finance retourne des objets d'erreur structurés pour tous les cas d'échec. L'objet d'erreur contient un code lisible par machine et un message lisible par un humain :

Code d'erreur	Statut HTTP	Signification
card_declined	402	La carte a été refusée par la banque émettrice. Ne pas réessayer automatiquement.
insufficient_funds	402	La carte a un solde insuffisant. Afficher un message invitant l'utilisateur à utiliser une autre carte.
expired_card	402	La date d'expiration de la carte est dépassée.
incorrect_cvc	402	Le CVV fourni ne correspond pas à la carte.
authentication_required	402	Une authentification 3DS est nécessaire. Suivre next_action.
invalid_card_number	400	Le format du numéro de carte est invalide.
rate_limit_exceeded	429	Trop de requêtes. Mettre en place un délai d'attente exponentiel.
api_key_invalid	401	La clé API fournie est invalide ou a été révoquée.
idempotency_conflict	409	Une requête avec cette clé d'idempotence existe déjà avec des paramètres différents.
server_error	500	Une erreur de serveur de TIB Finance. Il est possible de réessayer avec un délai d'attente exponentiel.

Webhooks

Les webhooks permettent à TIB Finance de transmettre des notifications d'événements en temps réel à votre serveur, plutôt que de vous obliger à interroger l'API pour connaître les mises à jour de statut. C'est essentiel pour gérer des événements asynchrones comme les confirmations de paiement différées, la création de litiges et le renouvellement des abonnements. Pour une analyse approfondie, consultez notre guide sur la gestion des événements webhook.

Configurez l'URL de votre point de terminaison webhook dans le tableau de bord marchand de TIB Finance. Votre point de terminaison doit être accessible publiquement, accepter les requêtes POST et répondre avec un code HTTP 200 dans un délai de 10 secondes. Toutes les charges utiles de webhook sont signées avec votre secret de webhook, vérifiez toujours la signature avant de traiter la demande.

SDK : .NET, PHP, Python, JavaScript

TIB Finance fournit des bibliothèques clientes officielles pour les langages côté serveur les plus courants, qui abstraient la couche HTTP et offrent une gestion d'erreurs native :

.NET (C#)

// Install via NuGet
// dotnet add package TibFinance.NET

using TibFinance;

var client = new TibFinanceClient("sk_live_YOUR_SECRET_KEY");
var transaction = await client.Transactions.CreateAsync(new TransactionCreateOptions {
    Amount = 4999,
    Currency = "USD",
    PaymentMethod = "pm_3Kd9fN7mQpJ2vH4x",
    Reference = "ORDER-001"
});
                        

PHP

// Install via Composer
// composer require tib-finance/php-sdk

require_once 'vendor/autoload.php';
\TibFinance\TibFinance::setApiKey('sk_live_YOUR_SECRET_KEY');

$transaction = \TibFinance\Transaction::create([
    'amount' => 4999,
    'currency' => 'USD',
    'payment_method' => 'pm_3Kd9fN7mQpJ2vH4x',
    'reference' => 'ORDER-001'
]);
                        

Python

# Install via pip
# pip install tibfinance

import tibfinance
tibfinance.api_key = "sk_live_YOUR_SECRET_KEY"

transaction = tibfinance.Transaction.create(
    amount=4999,
    currency="USD",
    payment_method="pm_3Kd9fN7mQpJ2vH4x",
    reference="ORDER-001"
)
                        

JavaScript / Node.js

// Install via npm
// npm install @tibfinance/node

const TibFinance = require('@tibfinance/node');
const client = new TibFinance('sk_live_YOUR_SECRET_KEY');

const transaction = await client.transactions.create({
  amount: 4999,
  currency: 'USD',
  payment_method: 'pm_3Kd9fN7mQpJ2vH4x',
  reference: 'ORDER-001'
});
                        

Liste de vérification avant la mise en production

Avant de passer du bac à sable à la production, vérifiez chacun des éléments suivants. Consultez notre guide complet de test en bac à sable pour la méthodologie de test.

Tous les scénarios de test réussissent dans le bac à sable (paiement réussi, carte refusée, fonds insuffisants, flux 3DS)
Le point de terminaison webhook est mis en œuvre, vérifié et gère tous les types d'événements pertinents
Des clés d'idempotence sont utilisées sur toutes les requêtes de création de transaction
La gestion des erreurs couvre tous les codes d'erreur documentés et affiche des messages appropriés à l'utilisateur
Les clés API secrètes sont stockées dans des variables d'environnement, pas dans le code
La clé publiable est correctement distinguée de la clé secrète
Le TLS est appliqué sur toutes les pages du flux de paiement
Des jetons de paiement sont stockés, jamais les numéros de carte bruts
La vérification de signature des webhooks est mise en œuvre
Une limitation de débit et une logique de réessai avec délai d'attente exponentiel sont mises en œuvre
La surveillance et les alertes sont configurées pour les échecs de paiement et les erreurs d'API

Prêt à commencer votre intégration?

Accédez au bac à sable de TIB Finance, à la documentation API complète et aux ressources pour développeurs. Notre équipe de support à l'intégration est disponible pour vous aider.

Voir la documentation API Accéder au bac à sable

Intégration de l'API de paiement : guide complet pour développeurs