Comment utiliser les APIs Braintree ?

En bref

Les API Braintree traitent les paiements par cartes de crédit, PayPal, Venmo et portefeuilles numériques. Vous vous intégrez via des SDK côté serveur (Node, Python, Ruby, etc.), créez des jetons client pour la sécurité front-end et gérez les transactions, les remboursements et les abonnements. Pour les tests, utilisez Apidog pour valider les charges utiles des webhooks et tester votre intégration avec des données de bac à sable avant la mise en production.

Introduction

Braintree traite des milliards de paiements chaque année. C'est le processeur de paiement derrière des entreprises comme Uber, Airbnb et GitHub. La plateforme gère les cartes de crédit, PayPal, Venmo, Apple Pay, Google Pay et les virements ACH.

Les API de paiement sont différentes des autres API. Une erreur dans un catalogue de produits est ennuyeuse. Une erreur de paiement coûte de l'argent réel et brise la confiance des clients. Vous devez faire les choses correctement.

Braintree propose deux chemins d'intégration : l'interface utilisateur "Drop-in" (formulaire de paiement pré-construit) et l'interface utilisateur personnalisée (contrôle total). Les deux utilisent les mêmes API côté serveur pour le traitement réel des paiements. Ce guide couvre le travail côté serveur qui se produit après qu'un client clique sur "Payer".

Testez les webhooks Braintree avec Apidog - gratuitement

Configuration de Braintree

Créer un compte Braintree

Allez sur braintreepayments.com (Braintree est maintenant PayPal Enterprise Payments) et créez un compte sandbox. Vous obtiendrez :

• ID du marchand : abc123xyz
• Clé publique : def456...
• Clé privée : ghi789...

Stockez-les en toute sécurité. La clé privée est comme un mot de passe - ne la commettez jamais sur Git.

Installer le SDK

Braintree fournit des SDK côté serveur pour la plupart des langages :

Node.js :

npm install braintree

Python :

pip install braintree

Ruby :

gem install braintree

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

Générer un jeton client

Avant d'afficher le formulaire de paiement, générez un jeton client. Cela autorise le front-end à communiquer avec Braintree.

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

Le front-end utilise ce jeton pour initialiser l'interface utilisateur "Drop-in" ou l'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 le nonce
3. Braintree traite le paiement
4. Le serveur reçoit une réponse de 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
    })
  }
})

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

Après la première transaction, vous pouvez enregistrer la méthode de paiement pour une utilisation future :

// 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
})

// La méthode de paiement est enregistrée
const paymentMethodToken = result.customer.paymentMethods[0].token

// Débiter la méthode de paiement enregistrée plus tard
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})

Transactions PayPal

Braintree gère PayPal de la même manière que les cartes. Le front-end obtient un nonce de PayPal, vous le débitez :

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

Remboursements et annulations

Remboursement intégral

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

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

Remboursement partiel

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

if (result.success) {
  console.log('Remboursement partiel traité')
}

Annuler une transaction

L'annulation arrête une transaction avant qu'elle ne soit réglée. Utilisez-le pour les paiements autorisés mais non capturés :

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

if (result.success) {
  console.log('Transaction annulée')
}

Flux d'état des transactions

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

Abonnements et facturation récurrente

Braintree gère les abonnements pour les paiements récurrents.

Créer un plan

Tout d'abord, créez un plan dans le panneau de configuration Braintree ou via l'API :

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

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

Annuler un abonnement

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

if (result.success) {
  console.log('Abonnement annulé')
}

Mettre à jour l'abonnement

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

Webhooks pour les événements de paiement

Les webhooks notifient votre serveur des événements de transaction. C'est essentiel pour les abonnements et les litiges.

Créer un point de terminaison de webhook

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

  // Vérifier et analyser le webhook
  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')
    }
  )
})

Enregistrer un webhook dans Braintree

Dans le panneau de configuration Braintree, allez dans Paramètres → Webhooks et ajoutez l'URL de votre point de terminaison. En développement, utilisez un service de tunneling comme ngrok pour recevoir les webhooks localement.

Tester avec Apidog

Les API de paiement nécessitent des tests approfondis. Vous ne pouvez pas vous fier aux données de production. Apidog vous aide à tester sans risque.

1. Simuler les charges utiles des webhooks

Au lieu d'attendre que Braintree envoie des webhooks, créez des charges utiles simulées :

{
  "bt_signature": "test_signature",
  "bt_payload": "eyJraW5kIjoidHJhbnNhY3Rpb25fc2V0dGxlZCIsInRyYW5zYWN0aW9uIjp7ImlkIjoiYWJjMTIzIiwiYW1vdW50IjoiNDkuOTkiLCJzdGF0dXMiOiJzZXR0bGVkIn19"
}

Envoyez-les à votre point de terminaison de webhook et vérifiez que votre code les gère correctement.

2. Séparation des environnements

Créez des environnements séparés :

# 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

3. Valider les réponses des webhooks

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é', () => {
  // Vérifiez vos journaux ou votre base de données
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

Testez les webhooks Braintree avec Apidog - gratuitement

Erreurs courantes et correctifs

Refusé par le processeur

Cause : La banque a rejeté la transaction.

Correction : Cela est souvent dû à des fonds insuffisants ou à des filtres anti-fraude. Affichez une erreur générique au client et suggérez d'essayer une autre carte. Enregistrez le processorResponseCode pour le débogage.

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

Refusé par la passerelle

Cause : Les filtres anti-fraude de Braintree ont bloqué la transaction.

Correction : Vérifiez le 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é
}

Échecs de règlement

Cause : La transaction n'a pas pu être réglée après l'autorisation.

Correction : Surveillez les webhooks transaction_settlement_declined. Causes courantes :

• La méthode de paiement a expiré entre l'autorisation et le règlement
• L'émetteur a bloqué la transaction
• Des fonds insuffisants sont devenus apparents

Transactions en double

Cause : Le client a cliqué deux fois sur "Payer" ou votre code a réessayé.

Correction : Utilisez le paramètre orderId. Braintree rejettera les doublons dans une fenêtre de temps :

const result = await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodNonce: nonce,
  orderId: 'UNIQUE-ORDER-123', // Empêche les doublons
  options: {
    submitForSettlement: true
  }
})

Alternatives et comparaisons

Le principal avantage de Braintree est le support natif de PayPal et Venmo. Si vous avez besoin à la fois du traitement par carte et de PayPal, c'est souvent plus simple que Stripe + PayPal séparément.

Cas d'utilisation réels

Plateforme d'abonnement SaaS. Un outil de gestion de projet utilise Braintree pour les abonnements mensuels. Les webhooks gèrent les paiements échoués (carte expirée, fonds insuffisants) en envoyant des notifications par e-mail. Les utilisateurs mettent à jour leurs méthodes de paiement sans contacter le support.

Paiements de place de marché. Une plateforme de freelancing divise les paiements entre les frais de plateforme et le freelance. Les comptes marchands et la configuration de sous-marchands de Braintree gèrent la complexité.

E-commerce avec PayPal. Une boutique en ligne propose les cartes de crédit et PayPal. L'API unifiée de Braintree signifie qu'une seule intégration gère les deux. Le même objet client fonctionne avec toutes les méthodes de paiement.

Conclusion

Voici ce que vous avez appris :

• Les SDK Braintree gèrent le traitement des paiements côté serveur
• Les jetons client autorisent la communication front-end
• Les ventes de transactions débitent les cartes de crédit et PayPal
• Les abonnements gèrent la facturation récurrente
• Les webhooks vous informent des événements de paiement
• Testez minutieusement avec Apidog avant la mise en production

FAQ

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

Un nonce est un jeton à usage unique représentant une méthode de paiement. Le front-end le génère après qu'un client a saisi ses détails de carte. Votre serveur utilise le nonce pour débiter la carte. Les nonces expirent après 3 heures.

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

L'autorisation réserve des fonds sur la carte. Le règlement débite réellement la carte. Par défaut, Braintree règle automatiquement. Pour les précommandes, autorisez d'abord, puis réglez lors de l'expédition :

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

// Régler plus tard
await gateway.transaction.submitForSettlement('transaction_id')

Comment gérer la devise ?

Chaque compte marchand Braintree a une devise par défaut. La multi-devise nécessite plusieurs comptes marchands. Vérifiez auprès du support Braintree pour la configuration multi-devise.

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

Braintree fournit des cartes de test dans le bac à sable :

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

Comment gérer les litiges/rétrofacturations ?

Écoutez les webhooks dispute_opened, dispute_won et dispute_lost. Fournissez des preuves via le panneau de configuration Braintree. Documentez tout - communications client, confirmations de livraison, conditions de service.

Puis-je stocker les numéros de carte de crédit ?

Non. La conformité PCI interdit le stockage des numéros de carte bruts. Stockez plutôt les jetons de méthode de paiement. Braintree gère la portée PCI.

Qu'est-ce que 3D Secure ?

3D Secure ajoute une étape de vérification supplémentaire pour les transactions sans carte présente. Braintree le prend en charge. Activez-le dans le panneau de configuration et gérez les réponses authentication_required :

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

Combien de temps prennent les remboursements ?

Les remboursements sont généralement traités en 3 à 5 jours ouvrables. Le délai dépend de la banque du client. Vous recevrez un webhook transaction_refunded une fois l'opération terminée.