DEV Community

Cover image for Braintree API Nutzung: Eine Anleitung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

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.

Teste Apidog noch heute

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.

💡 Tipp: Beim Erstellen von Zahlungsintegrationen hilft Ihnen Apidog beim Testen von Webhook-Handlern und Validieren von Zahlungsantworten. Simulieren Sie Braintree-Webhooks lokal, um Ihren Code für Erfolgs-, Fehler- und Edge-Fälle abzusichern, bevor Sie live gehen.

Testen Sie Braintree-Webhooks mit Apidog – kostenlos

Braintree einrichten

Ein Braintree-Konto erstellen

  1. Gehen Sie zu braintreepayments.com und erstellen Sie ein Sandbox-Konto.
  2. Notieren Sie Ihre Zugangsdaten:
    • Händler-ID: abc123xyz
    • Öffentlicher Schlüssel: def456...
    • Privater Schlüssel: ghi789...

Speichern Sie diese sicher. Der private Schlüssel ist wie ein Passwort – niemals in Git committen!

Braintree Dashboard

Das SDK installieren

Installieren Sie das Braintree-SDK für Ihre Serverseite:

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

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
})
Enter fullscreen mode Exit fullscreen mode

Einen Client-Token generieren

Vor dem Anzeigen des Zahlungsformulars generieren Sie einen Client-Token für das Frontend:

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

Das Frontend initialisiert damit die Drop-in-UI oder Ihre eigene Integration.

Zahlungen verarbeiten

Der Zahlungsablauf

  1. Das Frontend sendet eine Zahlungsmethoden-Nonce an Ihren Server.
  2. Der Server erzeugt eine Transaktion mit dieser Nonce.
  3. Braintree verarbeitet die Zahlung.
  4. Ihr Server erhält Erfolg oder Fehler zurück.
  5. Sie liefern die Bestellung aus 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
    })
  }
})
Enter fullscreen mode Exit fullscreen mode

Mit gespeicherter Zahlungsmethode belasten

Nach der ersten Transaktion können Sie die Zahlungsmethode speichern:

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

// Token der gespeicherten Zahlungsmethode
const paymentMethodToken = result.customer.paymentMethods[0].token

// Später mit Token belasten
await gateway.transaction.sale({
  amount: '49.99',
  paymentMethodToken: paymentMethodToken,
  options: {
    submitForSettlement: true
  }
})
Enter fullscreen mode Exit fullscreen mode

PayPal-Transaktionen

Braintree behandelt PayPal wie Kreditkarten. Sie erhalten eine Nonce und belasten diese:

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

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)
}
Enter fullscreen mode Exit fullscreen mode

Teilweise Rückerstattung 

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

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

Eine Transaktion stornieren

Verwenden Sie dies für autorisierte, aber noch nicht abgerechnete Zahlungen:

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

if (result.success) {
  console.log('Transaktion storniert')
}
Enter fullscreen mode Exit fullscreen mode

Transaktionsstatusfluss 

autorisiert → zur Abrechnung eingereicht → abgewickelt
                    ↓
                  storniert

abgewickelt → rückerstattet
Enter fullscreen mode Exit fullscreen mode

Abonnements und wiederkehrende Abrechnungen

Braintree verwaltet Abonnements für wiederkehrende Zahlungen.

Einen Plan erstellen

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

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

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)
}
Enter fullscreen mode Exit fullscreen mode

Ein Abonnement kündigen 

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

if (result.success) {
  console.log('Abonnement gekündigt')
}
Enter fullscreen mode Exit fullscreen mode

Abonnement aktualisieren 

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

Webhooks für Zahlungsereignisse

Webhooks informieren Ihren Server über Transaktionsereignisse – essenziell für Abos und Disputes.

Einen Webhook-Endpunkt erstellen 

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

  // Webhook verifizieren 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')
    }
  )
})
Enter fullscreen mode Exit fullscreen mode

Webhook in Braintree registrieren

Im Braintree-Kontrollpanel unter Einstellungen → Webhooks Ihre Endpunkt-URL hinzufügen. Für lokale Entwicklung empfiehlt sich ein Tunneling-Dienst wie ngrok.

Testen mit Apidog

Zahlungs-APIs müssen gründlich getestet werden. Apidog hilft, risikofrei zu testen.

Braintree Webhook Test

1. Webhook-Payloads simulieren

Erstellen Sie Mock-Payloads und senden Sie sie an Ihren Webhook für lokale Tests:

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

2. Umgebungstrennung

Konfigurieren Sie Sandbox und Produktion klar getrennt:

# 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
Enter fullscreen mode Exit fullscreen mode

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
})
Enter fullscreen mode Exit fullscreen mode

Testen Sie Braintree-Webhooks mit Apidog – kostenlos

Häufige Fehler und Behebungen

Verarbeitung abgelehnt

Ursache: Die Bank hat die Transaktion abgelehnt.

Behebung: Oft unzureichende Deckung oder Betrugsfilter. Zeigen Sie dem Kunden einen generischen Fehler, schlagen Sie alternative Karten vor. Protokollieren Sie processorResponseCode.

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.'
    })
  }
}
Enter fullscreen mode Exit fullscreen mode

Gateway abgelehnt

Ursache: Betrugsfilter von Braintree haben blockiert.

Behebung: Prüfen Sie gatewayRejectionReason:

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

Abrechnungsfehler

Ursache: Abwicklung nach Autorisierung fehlgeschlagen.

Behebung: Überwachen Sie transaction_settlement_declined Webhooks. Häufige Gründe:

  • Zahlungsmethode abgelaufen
  • Emittent blockiert Transaktion
  • Unzureichende Deckung erkannt

Doppelte Transaktionen

Ursache: Mehrfaches Klicken oder erneute Versuche.

Behebung: Nutzen Sie den orderId-Parameter, Braintree lehnt Duplikate ab:

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

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 Kartenverarbeitung und PayPal benötigen, ist es oft einfacher als Stripe + PayPal separat zu betreiben.

Anwendungsfälle aus der Praxis

SaaS-Abonnementplattform:

Ein Projektmanagement-Tool nutzt Braintree für monatliche Abos. Webhooks melden fehlgeschlagene Zahlungen (Karte abgelaufen, keine Deckung) und lösen E-Mail-Benachrichtigungen aus. Benutzer aktualisieren ihre Zahlungsmittel eigenständig.

Marktplatz-Zahlungen:

Eine Freelancer-Plattform teilt Zahlungen zwischen Plattformgebühr und Freelancer. Braintrees Händler- und Sub-Händler-Modell vereinfacht die Komplexität.

E-Commerce mit PayPal:

Ein Online-Shop bietet Kreditkarten und PayPal an. Die einheitliche API von Braintree verarbeitet beides. Dasselbe Kundenobjekt gilt für alle Zahlungsarten.

Fazit

Das Wichtigste in Kürze:

  • Braintree SDKs übernehmen die serverseitige Zahlungsabwicklung
  • Client-Tokens autorisieren das Frontend
  • Transaktionsverkäufe belasten Kreditkarten und PayPal
  • Abonnements steuern wiederkehrende Zahlungen
  • Webhooks informieren über Zahlungsereignisse
  • Testen Sie alles mit Apidog, bevor Sie live gehen

FAQ

Was ist eine Zahlungsmethoden-Nonce?

Eine Nonce ist ein einmaliger Token, der eine Zahlungsmethode repräsentiert. Das Frontend generiert ihn nach der Eingabe der Kartendaten. Ihr Server verwendet die Nonce zum Belasten der Karte. Nonces verfallen nach 3 Stunden.

Was ist der Unterschied zwischen Autorisierung und Abrechnung?

Autorisierung reserviert Beträge auf der Karte. Abrechnung belastet die Karte tatsächlich. Standardmäßig wird automatisch abgerechnet. Bei Vorbestellungen können Sie erst autorisieren und später abrechnen:

// 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')
Enter fullscreen mode Exit fullscreen mode

Wie gehe ich mit Währungen um?

Jedes Händlerkonto hat eine Standardwährung. Für mehrere Währungen sind mehrere Händlerkonten notwendig. Kontaktieren Sie den Braintree-Support für Einrichtung.

Welche Testkartennummern sollte ich verwenden?

In der Sandbox stehen diese Testkarten zur Verfügung:

  • 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, dispute_lost. Reichen Sie Beweise über das Kontrollpanel ein. Dokumentieren Sie Kundenkommunikation, Lieferungen und AGB.

Kann ich Kreditkartennummern speichern?

Nein. Aus PCI-Gründen dürfen Sie keine Rohdaten speichern. Verwenden Sie stattdessen Zahlungsmethoden-Tokens. Braintree übernimmt die PCI-Compliance.

Was ist 3D Secure?

3D Secure fügt einen Authentifizierungsschritt für Karten ohne Vorlage hinzu. In Braintree aktivieren und auf authentication_required reagieren:

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

Wie lange dauern Rückerstattungen?

Rückerstattungen werden meist innerhalb von 3–5 Werktagen bearbeitet. Der Zeitrahmen hängt von der Bank ab. Ein transaction_refunded Webhook informiert Sie über den Abschluss.

Top comments (0)