Braintree API Nutzung: Eine Anleitung

TL;DR

Braintree APIs verarbeiten Zahlungen von Kreditkarten, PayPal, Venmo und digitalen Geldbörsen. Die Integration erfolgt über serverseitige SDKs (Node, Python, Ruby usw.), Sie erstellen Client-Tokens für die Frontend-Sicherheit und wickeln Transaktionen, Rückerstattungen und Abonnements ab. Verwenden Sie für Tests Apidog, um Webhook-Payloads zu validieren und Ihre Integration vor der Live-Schaltung mit Sandbox-Daten zu testen.

Einleitung

Braintree verarbeitet jährlich Milliarden von Zahlungen. Es ist der Zahlungsdienstleister hinter Unternehmen wie Uber, Airbnb und GitHub. Die Plattform unterstützt Kreditkarten, PayPal, Venmo, Apple Pay, Google Pay und ACH-Überweisungen.

Zahlungs-APIs unterscheiden sich von anderen APIs. Ein Fehler in einem Produktkatalog ist ärgerlich. Ein Fehler bei Zahlungen kostet echtes Geld und zerstört das Vertrauen der Kunden. Sie müssen es richtig machen.

Braintree bietet zwei Integrationswege an: Drop-in UI (vorgefertigtes Zahlungsformular) und Custom UI (volle Kontrolle). Beide verwenden dieselben serverseitigen APIs für die eigentliche Zahlungsabwicklung. Dieser Leitfaden behandelt die serverseitige Arbeit, die stattfindet, nachdem ein Kunde auf „Bezahlen“ klickt.

💡

Wenn Sie Zahlungsintegrationen erstellen, hilft Ihnen Apidog beim Testen von Webhook-Handlern und Validieren von Zahlungsantworten. Sie können die Webhooks von Braintree lokal simulieren und so sicherstellen, dass Ihr Code Erfolgs-, Fehler- und Edge-Fälle verarbeitet, bevor Sie reale Transaktionen bearbeiten.

button

Testen Sie Braintree-Webhooks mit Apidog – kostenlos

Braintree einrichten

Ein Braintree-Konto erstellen

Gehen Sie zu braintreepayments.com (Braintree ist jetzt PayPal Enterprise Payments) und erstellen Sie ein Sandbox-Konto. Sie erhalten:

Händler-ID: abc123xyz
Öffentlicher Schlüssel: def456...
Privater Schlüssel: ghi789...

Bewahren Sie diese sicher auf. Der private Schlüssel ist wie ein Passwort – committen Sie ihn niemals in Git.

Das SDK installieren

Braintree bietet serverseitige SDKs für die meisten Sprachen:

Node.js:

npm install braintree

Python:

pip install braintree

Ruby:

gem install braintree

Das Gateway initialisieren:

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

Einen Client-Token generieren

Bevor das Zahlungsformular angezeigt wird, generieren Sie einen Client-Token. Dieser autorisiert das Frontend zur Kommunikation mit Braintree.

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

Das Frontend verwendet diesen Token, um die Drop-in-UI oder eine benutzerdefinierte Integration zu initialisieren.

Zahlungen verarbeiten

Der Zahlungsablauf

Frontend sendet Zahlungsmethoden-Nonce an Ihren Server
Server erstellt eine Transaktion unter Verwendung der Nonce
Braintree verarbeitet die Zahlung
Server empfängt Erfolgs-/Fehlerantwort
Sie erfüllen die Bestellung oder zeigen einen Fehler an

Eine Kreditkarte belasten

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

Mit gespeicherter Zahlungsmethode belasten

Nach der ersten Transaktion können Sie die Zahlungsmethode für zukünftige Verwendungen speichern:

// Kunden mit Zahlungsmethode erstellen
const result = await gateway.customer.create({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  paymentMethodNonce: nonce
})

// Die Zahlungsmethode ist gespeichert
const paymentMethodToken = result.customer.paymentMethods[0].token

// Gespeicherte Zahlungsmethode später belasten
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})

PayPal-Transaktionen

Braintree verarbeitet PayPal genauso wie Karten. Das Frontend erhält eine Nonce von PayPal, Sie belasten diese:

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

Rückerstattungen und Stornierungen

Vollständige Rückerstattung

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

if (result.success) {
  console.log('Rückerstattet:', result.transaction.id)
}

Teilweise Rückerstattung

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

if (result.success) {
  console.log('Teilweise Rückerstattung verarbeitet')
}

Eine Transaktion stornieren

Eine Stornierung beendet eine Transaktion, bevor sie abgewickelt wird. Verwenden Sie dies für autorisierte, aber noch nicht erfasste Zahlungen:

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

if (result.success) {
  console.log('Transaktion storniert')
}

Transaktionsstatusfluss

autorisiert → zur Abrechnung eingereicht → abgewickelt
                    ↓
                  storniert
                    
abgewickelt → rückerstattet

Abonnements und wiederkehrende Abrechnungen

Braintree verwaltet Abonnements für wiederkehrende Zahlungen.

Einen Plan erstellen

Erstellen Sie zuerst einen Plan im Braintree-Kontrollpanel oder über die API:

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

Ein Abonnement erstellen

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

if (result.success) {
  console.log('Abonnement erstellt:', result.subscription.id)
}

Ein Abonnement kündigen

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

if (result.success) {
  console.log('Abonnement gekündigt')
}

Abonnement aktualisieren

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

Webhooks für Zahlungsereignisse

Webhooks benachrichtigen Ihren Server über Transaktionsereignisse. Dies ist entscheidend für Abonnements und Streitigkeiten.

Einen Webhook-Endpunkt erstellen

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

  // Den Webhook überprüfen und parsen
  gateway.webhookNotification.parse(
    signature,
    payload,
    (err, webhookNotification) => {
      if (err) {
        return res.status(400).send('Ungültiger Webhook')
      }

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

Webhook in Braintree registrieren

Gehen Sie im Braintree-Kontrollpanel zu Einstellungen → Webhooks und fügen Sie Ihre Endpunkt-URL hinzu. Verwenden Sie in der Entwicklung einen Tunneling-Dienst wie ngrok, um Webhooks lokal zu empfangen.

Testen mit Apidog

Zahlungs-APIs erfordern eine gründliche Prüfung. Sie können sich nicht auf Produktionsdaten verlassen. Apidog hilft Ihnen, risikofrei zu testen.

1. Webhook-Payloads simulieren

Anstatt darauf zu warten, dass Braintree Webhooks sendet, erstellen Sie Mock-Payloads:

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

Senden Sie diese an Ihren Webhook-Endpunkt und überprüfen Sie, ob Ihr Code sie korrekt verarbeitet.

2. Umgebungstrennung

Erstellen Sie separate Umgebungen:

# Sandbox
BRAINTREE_MERCHANT_ID: sandbox_merchant
BRAINTREE_PUBLIC_KEY: sandbox_public
BRAINTREE_PRIVATE_KEY: sandbox_private
BRAINTREE_ENVIRONMENT: sandbox

# Produktion
BRAINTREE_MERCHANT_ID: live_merchant
BRAINTREE_PUBLIC_KEY: live_public
BRAINTREE_PRIVATE_KEY: live_private
BRAINTREE_ENVIRONMENT: production

3. Webhook-Antworten validieren

pm.test('Webhook erfolgreich verarbeitet', () => {
  pm.response.to.have.status(200)
  pm.response.to.have.body('OK')
})

pm.test('Transaktions-ID protokolliert', () => {
  // Überprüfen Sie Ihre Protokolle oder Datenbank
  const transactionId = pm.environment.get('last_transaction_id')
  pm.expect(transactionId).to.not.be.empty
})

Testen Sie Braintree-Webhooks mit Apidog – kostenlos

Häufige Fehler und Behebungen

Verarbeitung abgelehnt

Ursache: Die Bank hat die Transaktion abgelehnt.

Behebung: Dies ist oft auf unzureichende Deckung oder Betrugsfilter zurückzuführen. Zeigen Sie dem Kunden einen allgemeinen Fehler an und schlagen Sie vor, eine andere Karte zu versuchen. Protokollieren Sie den processorResponseCode zur Fehlersuche.

if (!result.success) {
  if (result.transaction.processorResponseCode === '2000') {
    // Bank hat abgelehnt
    return res.status(400).json({
      error: 'Ihre Bank hat diese Transaktion abgelehnt. Bitte versuchen Sie es mit einer anderen Karte.'
    })
  }
}

Gateway abgelehnt

Ursache: Die Betrugsfilter von Braintree haben die Transaktion blockiert.

Behebung: Überprüfen Sie den gatewayRejectionReason:

if (result.transaction.gatewayRejectionReason === 'cvv') {
  // CVV-Fehler
}
if (result.transaction.gatewayRejectionReason === 'avs') {
  // Adressverifizierung fehlgeschlagen
}
if (result.transaction.gatewayRejectionReason === 'fraud') {
  // Erweiterte Betrugstools haben es blockiert
}

Abrechnungsfehler

Ursache: Die Transaktion konnte nach der Autorisierung nicht abgewickelt werden.

Behebung: Überwachen Sie transaction_settlement_declined Webhooks. Häufige Ursachen:

Zahlungsmethode zwischen Autorisierung und Abrechnung abgelaufen
Emittent hat die Transaktion blockiert
Unzureichende Deckung wurde offensichtlich

Doppelte Transaktionen

Ursache: Der Kunde hat zweimal auf „Bezahlen“ geklickt oder Ihr Code hat einen erneuten Versuch unternommen.

Behebung: Verwenden Sie den Parameter orderId. Braintree lehnt Duplikate innerhalb eines Zeitfensters ab:

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

Alternativen und Vergleiche

Funktion	Braintree	Stripe	PayPal
Preise	2.9% + 30¢	2.9% + 30¢	2.9% + 30¢
PayPal-Unterstützung	Nativ	Add-on	Nativ
Abonnements	Ja	Ja	Begrenzt
International	46 Länder	46 Länder	200+ Länder
Betrugstools	Integriert	Integriert	Basis
SDK-Qualität	Ausgezeichnet	Ausgezeichnet	Gut
Auszahlungen	Ja	Ja	Ja

Der Hauptvorteil von Braintree ist die native Unterstützung von PayPal und Venmo. Wenn Sie sowohl Kartenverarbeitung als auch PayPal benötigen, ist dies oft einfacher als Stripe + PayPal separat.

Anwendungsfälle aus der Praxis

SaaS-Abonnementplattform. Ein Projektmanagement-Tool nutzt Braintree für monatliche Abonnements. Webhooks verwalten fehlgeschlagene Zahlungen (Karte abgelaufen, unzureichende Deckung), indem sie E-Mail-Benachrichtigungen senden. Benutzer aktualisieren Zahlungsmethoden, ohne den Support zu kontaktieren.

Marktplatz-Zahlungen. Eine Freelancer-Plattform teilt Zahlungen zwischen Plattformgebühr und Freelancer auf. Braintrees Händlerkonten und die Sub-Händler-Einrichtung bewältigen die Komplexität.

E-Commerce mit PayPal. Ein Online-Shop bietet Kreditkarten und PayPal an. Braintrees einheitliche API bedeutet, dass eine Integration beides abwickelt. Dasselbe Kundenobjekt funktioniert über alle Zahlungsmethoden hinweg.

Fazit

Das haben Sie gelernt:

Braintree SDKs wickeln die serverseitige Zahlungsabwicklung ab
Client-Tokens autorisieren die Frontend-Kommunikation
Transaktionsverkäufe belasten Kreditkarten und PayPal
Abonnements verwalten wiederkehrende Abrechnungen
Webhooks benachrichtigen Sie über Zahlungsereignisse
Testen Sie gründlich mit Apidog, bevor Sie live gehen

button

FAQ

Was ist eine Zahlungsmethoden-Nonce?

Eine Nonce ist ein einmaliger Token, der eine Zahlungsmethode repräsentiert. Das Frontend generiert ihn, nachdem ein Kunde Kartendaten eingegeben hat. Ihr Server verwendet die Nonce, um die Karte zu belasten. Nonces verfallen nach 3 Stunden.

Was ist der Unterschied zwischen Autorisierung und Abrechnung?

Autorisierung reserviert Gelder auf der Karte. Abrechnung belastet die Karte tatsächlich. Standardmäßig wickelt Braintree automatisch ab. Bei Vorbestellungen autorisieren Sie zuerst und wickeln dann beim Versand ab:

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

// Später abrechnen
await gateway.transaction.submitForSettlement('transaction_id')

Wie gehe ich mit Währungen um?

Jedes Braintree-Händlerkonto hat eine Standardwährung. Mehrere Währungen erfordern mehrere Händlerkonten. Erkundigen Sie sich beim Braintree-Support nach der Einrichtung mehrerer Währungen.

Welche Testkartennummern sollte ich verwenden?

Braintree stellt Testkarten in der Sandbox bereit:

4111111111111111 - Visa (Erfolg)
4000111111111115 - Visa (Ablehnung)
5555555555554444 - Mastercard (Erfolg)
378282246310005 - Amex (Erfolg)

Wie gehe ich mit Streitigkeiten/Rückbuchungen um?

Überwachen Sie die Webhooks dispute_opened, dispute_won und dispute_lost. Legen Sie Beweismittel über das Braintree-Kontrollpanel vor. Dokumentieren Sie alles – Kundenkommunikation, Lieferbestätigungen, Nutzungsbedingungen.

Kann ich Kreditkartennummern speichern?

Nein. Die PCI-Konformität verbietet die Speicherung von Roh-Kartennummern. Speichern Sie stattdessen Zahlungsmethoden-Tokens. Braintree kümmert sich um den PCI-Bereich.

Was ist 3D Secure?

3D Secure fügt einen zusätzlichen Verifizierungsschritt für Transaktionen ohne Kartenvorlage hinzu. Braintree unterstützt dies. Aktivieren Sie es im Kontrollpanel und verarbeiten Sie authentication_required Antworten:

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

Wie lange dauern Rückerstattungen?

Rückerstattungen werden typischerweise innerhalb von 3-5 Werktagen bearbeitet. Der Zeitpunkt hängt von der Bank des Kunden ab. Sie erhalten einen transaction_refunded Webhook, wenn der Vorgang abgeschlossen ist.