DEV Community

Cover image for Comment utiliser les APIs Braintree ?
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser les APIs Braintree ?

En bref

Les API Braintree traitent les paiements par cartes de crédit, PayPal, Venmo et portefeuilles numériques. L’intégration côté serveur se fait via des SDK (Node, Python, Ruby, etc.) et implique la génération de jetons client pour la sécurité front-end, la gestion des transactions, remboursements et abonnements. Pour tester efficacement, utilisez Apidog pour valider les charges utiles des webhooks et simuler des paiements avec des données de bac à sable avant la mise en production.

Essayez Apidog dès aujourd'hui

Introduction

Braintree traite des milliards de paiements chaque année, utilisé par Uber, Airbnb, GitHub, etc. La plateforme prend en charge cartes bancaires, PayPal, Venmo, Apple Pay, Google Pay, virements ACH.

Les API de paiement exigent une gestion rigoureuse : une erreur coûte de l’argent réel et nuit à la confiance utilisateur. Il faut donc une intégration et des tests irréprochables.

Braintree propose une interface "Drop-in" (formulaire de paiement préfabriqué) ou une interface personnalisée (contrôle total). Les deux reposent sur les mêmes API serveur pour le traitement effectif. Ce guide se concentre sur l’intégration côté serveur après le clic sur “Payer”.

💡 Astuce efficace : Pour le développement d’intégrations de paiement, Apidog facilite le test des webhooks et la validation des réponses. Simulez localement les webhooks Braintree pour vérifier la gestion de tous les scénarios (succès, échecs, cas limites) avant le passage en production.

Testez les webhooks Braintree avec Apidog – gratuitement

Configuration de Braintree

Créer un compte Braintree

  1. Rendez-vous sur braintreepayments.com (désormais PayPal Enterprise Payments).
  2. Créez un compte sandbox.
  3. Récupérez vos identifiants :
    • ID du marchand : abc123xyz
    • Clé publique : def456...
    • Clé privée : ghi789...

Stockez la clé privée de manière sécurisée (jamais dans Git).

Capture d'écran des informations d'identification de l'API Braintree dans le panneau de configuration.

Installer le SDK

Braintree offre des SDK serveur pour les principaux langages :

Node.js :

npm install braintree
Enter fullscreen mode Exit fullscreen mode

Python :

pip install braintree
Enter fullscreen mode Exit fullscreen mode

Ruby :

gem install braintree
Enter fullscreen mode Exit fullscreen mode

Initialiser la passerelle :

const braintree = require('braintree')

const gateway = new braintree.BraintreeGateway({
  environment: braintree.Environment.Sandbox,
  merchantId: process.env.BRAINTREE_MERCHANT_ID,
  publicKey: process.env.BRAINTREE_PUBLIC_KEY,
  privateKey: process.env.BRAINTREE_PRIVATE_KEY
})
Enter fullscreen mode Exit fullscreen mode

Générer un jeton client

Avant d’afficher le formulaire de paiement, générez un jeton côté serveur :

app.get('/checkout/token', async (req, res) => {
  const clientToken = await gateway.clientToken.generate()
  res.json({ clientToken: clientToken.clientToken })
})
Enter fullscreen mode Exit fullscreen mode

Ce jeton est utilisé par le front-end pour initialiser l’UI “Drop-in” ou une intégration personnalisée.

Traitement des paiements

Le flux de paiement

  1. Le front-end envoie un nonce de méthode de paiement à votre serveur.
  2. Le serveur crée une transaction en utilisant ce nonce.
  3. Braintree traite le paiement.
  4. Le serveur reçoit le résultat (succès/échec).
  5. Vous honorez la commande ou affichez une erreur.

Débiter une carte de crédit 

app.post('/checkout', async (req, res) => {
  const { paymentMethodNonce, amount, orderId } = req.body

  const result = await gateway.transaction.sale({
    amount: amount,
    paymentMethodNonce: paymentMethodNonce,
    orderId: orderId,
    options: {
      submitForSettlement: true
    }
  })

  if (result.success) {
    res.json({
      success: true,
      transactionId: result.transaction.id
    })
  } else {
    res.status(400).json({
      success: false,
      message: result.message
    })
  }
})
Enter fullscreen mode Exit fullscreen mode

Débiter avec une méthode de paiement enregistrée

Après une première transaction, stockez le moyen de paiement :

// Créer un client avec une méthode de paiement
const result = await gateway.customer.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  paymentMethodNonce: nonce
})

// Token de la méthode enregistrée
const paymentMethodToken = result.customer.paymentMethods[0].token

// Débiter ultérieurement
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})
Enter fullscreen mode Exit fullscreen mode

Transactions PayPal

Gestion identique aux cartes :

const result = await gateway.transaction.sale({
  amount: '99.00',
  paymentMethodNonce: paypalNonce,
  orderId: 'ORDER-123',
  options: {
    submitForSettlement: true
  }
})
Enter fullscreen mode Exit fullscreen mode

Remboursements et annulations

Remboursement intégral 

const result = await gateway.transaction.refund('transaction_id')

if (result.success) {
  console.log('Remboursé :', result.transaction.id)
}
Enter fullscreen mode Exit fullscreen mode

Remboursement partiel 

const result = await gateway.transaction.refund('transaction_id', '50.00')

if (result.success) {
  console.log('Remboursement partiel traité')
}
Enter fullscreen mode Exit fullscreen mode

Annuler une transaction (avant règlement) 

const result = await gateway.transaction.void('transaction_id')

if (result.success) {
  console.log('Transaction annulée')
}
Enter fullscreen mode Exit fullscreen mode

Flux d’état des transactions 

autorisé → soumis_pour_règlement → réglé
                    ↓
                  annulé

réglé → remboursé
Enter fullscreen mode Exit fullscreen mode

Abonnements et facturation récurrente

Braintree gère les paiements récurrents via des abonnements.

Créer un plan

Définissez un plan dans le dashboard ou via l’API :

const result = await gateway.plan.create({
  id: 'monthly-premium',
  name: 'Mensuel Premium',
  billingFrequency: 1,
  currencyIsoCode: 'USD',
  price: '29.99'
})
Enter fullscreen mode Exit fullscreen mode

Créer un abonnement 

const result = await gateway.subscription.create({
  paymentMethodToken: paymentMethodToken,
  planId: 'monthly-premium',
  firstBillingDate: new Date()
})

if (result.success) {
  console.log('Abonnement créé :', result.subscription.id)
}
Enter fullscreen mode Exit fullscreen mode

Annuler un abonnement 

const result = await gateway.subscription.cancel('subscription_id')

if (result.success) {
  console.log('Abonnement annulé')
}
Enter fullscreen mode Exit fullscreen mode

Mettre à jour l’abonnement 

const result = await gateway.subscription.update('subscription_id', {
  planId: 'annual-premium',
  price: '299.99'
})
Enter fullscreen mode Exit fullscreen mode

Webhooks pour les événements de paiement

Les webhooks informent votre serveur des événements (paiements, litiges, etc). Indispensable pour les abonnements et la gestion des litiges.

Créer un endpoint de webhook 

app.post('/webhooks/braintree', (req, res) => {
  const signature = req.body.bt_signature
  const payload = req.body.bt_payload

  gateway.webhookNotification.parse(
    signature,
    payload,
    (err, webhookNotification) => {
      if (err) {
        return res.status(400).send('Webhook invalide')
      }

      switch (webhookNotification.kind) {
        case 'subscription_charged_successfully':
          handleSuccessfulCharge(webhookNotification.subscription)
          break
        case 'subscription_charged_unsuccessfully':
          handleFailedCharge(webhookNotification.subscription)
          break
        case 'dispute_opened':
          handleDispute(webhookNotification.dispute)
          break
        case 'transaction_settled':
          handleSettledTransaction(webhookNotification.transaction)
          break
      }

      res.status(200).send('OK')
    }
  )
})
Enter fullscreen mode Exit fullscreen mode

Enregistrer un webhook dans Braintree

Dans le dashboard Braintree, allez dans Paramètres → Webhooks et ajoutez l’URL de votre endpoint. En développement, utilisez ngrok pour recevoir les webhooks localement.

Tester avec Apidog

Les paiements nécessitent des tests exhaustifs. Apidog [https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation] permet de simuler et valider sans risque.

Capture d'écran de l'outil Apidog montrant la simulation de webhook.

1. Simuler les charges utiles des webhooks

Générez des payloads simulés et envoyez-les à votre endpoint :

{
  "bt_signature": "test_signature",
  "bt_payload": "eyJraW5kIjoidHJhbnNhY3Rpb25fc2V0dGxlZCIsInRyYW5zYWN0aW9uIjp7ImlkIjoiYWJjMTIzIiwiYW1vdW50IjoiNDkuOTkiLCJzdGF0dXMiOiJzZXR0bGVkIn19"
}
Enter fullscreen mode Exit fullscreen mode

2. Séparation des environnements

Utilisez des variables d’environnement pour distinguer sandbox/production :

# Bac à sable
BRAINTREE_MERCHANT_ID: sandbox_merchant
BRAINTREE_PUBLIC_KEY: sandbox_public
BRAINTREE_PRIVATE_KEY: sandbox_private
BRAINTREE_ENVIRONMENT: sandbox

# Production
BRAINTREE_MERCHANT_ID: live_merchant
BRAINTREE_PUBLIC_KEY: live_public
BRAINTREE_PRIVATE_KEY: live_private
BRAINTREE_ENVIRONMENT: production
Enter fullscreen mode Exit fullscreen mode

3. Valider les réponses des webhooks

Utilisez des assertions pour vérifier vos endpoints :

pm.test('Webhook traité avec succès', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('ID de transaction enregistré', () => {
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})
Enter fullscreen mode Exit fullscreen mode

Testez les webhooks Braintree avec Apidog – gratuitement

Erreurs courantes et correctifs

Refusé par le processeur

Cause : Rejeté par la banque (fonds insuffisants, fraude, etc).

Correction : Affichez une erreur générique, proposez une autre carte. Enregistrez processorResponseCode pour le debug.

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    return res.status(400).json({
      error: 'Votre banque a refusé cette transaction. Veuillez essayer une autre carte.'
    })
  }
}
Enter fullscreen mode Exit fullscreen mode

Refusé par la passerelle

Cause : Filtres anti-fraude Braintree.

Correction : Vérifiez gatewayRejectionReason :

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // Incohérence du CVV
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // Vérification d'adresse échouée
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // Outils anti-fraude avancés l'ont bloqué
}
Enter fullscreen mode Exit fullscreen mode

Échecs de règlement

Cause : Impossible de régler après autorisation.

Correction : Surveillez le webhook transaction_settlement_declined. Causes classiques : carte expirée, blocage émetteur, fonds insuffisants.

Transactions en double

Cause : Double clic sur “Payer” ou retry code.

Correction : Utilisez orderId pour éviter les doublons :

const result = await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodNonce: nonce,
  orderId: 'UNIQUE-ORDER-123',
  options: {
    submitForSettlement: true
  }
})
Enter fullscreen mode Exit fullscreen mode

Alternatives et comparaisons

Fonctionnalité Braintree Stripe PayPal
Tarification 2.9% + 30¢ 2.9% + 30¢ 2.9% + 30¢
Support PayPal Natif Module compl. Natif
Abonnements Oui Oui Limité
International 46 pays 46 pays 200+ pays
Outils anti-fraude Intégrés Intégrés Basiques
Qualité du SDK Excellente Excellente Bonne
Versements Oui Oui Oui

Braintree se distingue par son support natif de PayPal et Venmo. Si vous gérez cartes + PayPal, cela simplifie grandement l’intégration par rapport à Stripe + PayPal séparés.

Cas d’utilisation réels

  • SaaS d’abonnement : Un outil de gestion de projets utilise Braintree pour les abonnements mensuels. Les webhooks gèrent échecs de paiement et notifications. Les utilisateurs mettent à jour leur carte sans support.
  • Marketplace : Une plateforme de freelancing sépare paiement freelance/frais de plateforme via la gestion des sous-marchands Braintree.
  • E-commerce avec PayPal : Une boutique propose cartes et PayPal avec une seule intégration côté serveur grâce à l’API unifiée de Braintree.

Conclusion

À retenir pour une intégration Braintree robuste :

  • Les SDK gèrent le traitement serveur (Node, Python, Ruby…)
  • Les jetons client sécurisent la communication front-end
  • Les transactions gèrent à la fois cartes et PayPal
  • Les abonnements automatisent la facturation récurrente
  • Les webhooks sont essentiels pour suivre les paiements et litiges
  • Testez systématiquement avec Apidog avant toute mise en production

FAQ

Qu'est-ce qu'un nonce de méthode de paiement ?

Un nonce est un jeton à usage unique généré côté front-end, représentant une méthode de paiement. Il expire après 3 heures.

Quelle est la différence entre l’autorisation et le règlement ?

  • Autorisation : réserve les fonds sur la carte
  • Règlement : prélève la somme

Par défaut, Braintree règle automatiquement. Pour les précommandes, autorisez puis réglez manuellement :

// Autoriser uniquement
await gateway.transaction.sale({
  amount: '99.00',
  paymentMethodNonce: nonce,
  options: {
    submitForSettlement: false
  }
})

// Régler plus tard
await gateway.transaction.submitForSettlement('transaction_id')
Enter fullscreen mode Exit fullscreen mode

Comment gérer la devise ?

Chaque compte marchand Braintree a une devise par défaut. Pour la multi-devise, ouvrez plusieurs comptes marchands ; contactez le support Braintree pour la configuration.

Quels numéros de carte de test dois-je utiliser ?

  • 4111111111111111 – Visa (succès)
  • 4000111111111115 – Visa (refus)
  • 5555555555554444 – Mastercard (succès)
  • 378282246310005 – Amex (succès)

Comment gérer les litiges/rétrofacturations ?

Surveillez les webhooks dispute_opened, dispute_won, dispute_lost. Fournissez des preuves via le dashboard Braintree (emails, livraisons, CGU…).

Puis-je stocker les numéros de carte ?

Non. Pour la conformité PCI, stockez uniquement les jetons fournis par Braintree.

Qu’est-ce que 3D Secure ?

3D Secure ajoute une vérification pour les paiements sans carte physique. Activez-le dans le dashboard et gérez la réponse authentication_required :

const result = await gateway.transaction.sale({
  amount: '100.00',
  paymentMethodNonce: nonce,
  threeDSecure: {
    required: true
  }
})
Enter fullscreen mode Exit fullscreen mode

Combien de temps prennent les remboursements ?

En général 3 à 5 jours ouvrés, selon la banque du client. Surveillez le webhook transaction_refunded pour confirmation.

Top comments (0)