Stripe-Connector

Stripe-Connector

Verbinde deinen Stripe-Account mit Brevo über Tajo für eine vollständige Synchronisation von Zahlungsdaten, Management des Abonnement-Lifecycles und umsatzgetriebene Marketing-Automation.

Überblick

Funktionen

• Kundendaten-Synchronisation – Synchronisiere Stripe-Kund:innen mit Brevo-Kontakten inklusive Metadaten
• Zahlungsverfolgung – Verfolge erfolgreiche Zahlungen, Rückerstattungen und fehlgeschlagene Charges
• Abonnement-Management – Synchronisiere Lifecycle-Events für Retention-Kampagnen
• Rechnungsdaten – Synchronisiere Rechnungsdetails für Post-Purchase- und Renewal-Automation
• Umsatzzuordnung – Ordne Lifetime Value und MRR Brevo-Attributen zu
• Webhook-Events – Echtzeit-Benachrichtigungen für alle Zahlungsvorgänge
• Multi-Currency-Unterstützung – Verarbeite Zahlungen in verschiedenen Währungen
• Checkout-Session-Tracking – Verfolge Stripe Checkout für die Recovery abgebrochener Zahlungen

Voraussetzungen

Bevor du beginnst, stelle sicher, dass du Folgendes hast:

1. Einen Stripe-Account mit API-Zugang
2. Stripe-API-Schlüssel (Publishable und Secret Key)
3. Einen Brevo-Account mit API-Zugang
4. Einen Tajo-Account

Authentifizierung

API-Key-Authentifizierung

Stripe nutzt Bearer-Token-Authentifizierung mit deinem Secret API Key.

curl https://api.stripe.com/v1/customers \
  -u sk_live_YOUR_SECRET_KEY:

Restricted API Keys

Erstelle Restricted Keys mit spezifischen Berechtigungen für erhöhte Sicherheit:

1. Gehe ins Stripe Dashboard > Developers > API Keys
2. Klicke auf „Create restricted key”
3. Gewähre nur die Berechtigungen, die Tajo benötigt

Erforderliche Berechtigungen

customers: read
charges: read
payment_intents: read
subscriptions: read
invoices: read
events: read
products: read
prices: read

Konfiguration

Grundlegende Einrichtung

connectors:
  stripe:
    enabled: true
    secret_key: "${STRIPE_SECRET_KEY}"
    webhook_secret: "${STRIPE_WEBHOOK_SECRET}"

    # Data sync options
    sync:
      customers: true
      payments: true
      subscriptions: true
      invoices: true
      products: true

    # Brevo list assignment
    lists:
      all_customers: 20
      subscribers: 21
      churned: 22

Feld-Mapping

Mappe Stripe-Kundendaten auf Brevo-Kontaktattribute:

Mapping benutzerdefinierter Attribute

field_mapping:
  # Standard fields
  email: email
  name: FULLNAME
  phone: SMS

  # Payment metrics
  total_spent: TOTAL_SPENT
  payment_count: PAYMENT_COUNT
  last_payment_date: LAST_PAYMENT_DATE
  average_order_value: AOV

  # Subscription fields
  subscription_status: SUB_STATUS
  plan_name: PLAN_NAME
  mrr: MONTHLY_REVENUE
  subscription_start: SUB_START_DATE

  # Custom metadata
  metadata.customer_tier: VIP_TIER
  metadata.referral_source: REFERRAL_SOURCE

API-Endpoints

Kern-Endpoints

Abonnement-Endpoints

Event-Endpoints

Events

Zahlungs-Events

Abonnement-Events

Kunden-Events

Code-Beispiele

Connector initialisieren

import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Stripe
await tajo.connectors.connect('stripe', {
  secretKey: process.env.STRIPE_SECRET_KEY,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET
});

Kundendaten-Synchronisation ausführen

// Full historical sync
await tajo.connectors.sync('stripe', {
  type: 'full',
  resources: ['customers', 'subscriptions', 'payments'],
  since: '2023-01-01'
});

// Check sync status
const status = await tajo.connectors.status('stripe');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   customersSynced: 12500,
//   subscriptionsSynced: 8200,
//   paymentsSynced: 45000
// }

Stripe-Webhooks verarbeiten

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

app.post('/webhooks/stripe', async (req, res) => {
  const sig = req.headers['stripe-signature'];

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Forward to Tajo for Brevo sync
  await tajo.connectors.handleWebhook('stripe', {
    type: event.type,
    data: event.data.object
  });

  res.status(200).json({ received: true });
});

Rate Limits

Stripe erzwingt folgende Rate Limits:

Fehlerbehebung

Häufige Probleme

Debug-Modus

Ausführliches Logging aktivieren:

connectors:
  stripe:
    debug: true
    log_level: verbose
    log_webhooks: true

Verbindung testen

tajo connectors test stripe
# ✓ API connection successful
# ✓ Customers readable
# ✓ Subscriptions readable
# ✓ Payments readable
# ✓ Webhook endpoint verified

Best Practices

1. Restricted API Keys verwenden – Erstelle Keys mit den minimal erforderlichen Berechtigungen
2. Webhook-Signaturen immer verifizieren – Verhindere gefälschte Webhook-Events
3. Idempotenz handhaben – Nutze Stripe-Event-IDs, um doppelte Verarbeitung zu vermeiden
4. Kunden-Metadaten synchronisieren – Speichere marketingrelevante Daten in Stripe-Metadatenfeldern
5. Webhook-Zustellung überwachen – Prüfe das Stripe-Dashboard auf fehlgeschlagene Zustellungen
6. Zuerst den Test-Modus nutzen – Validiere deine Integration mit Stripe-Test-Modus und Test Clocks

Sicherheit

• API-Key-Authentifizierung – Zugriff via Secret Key mit Unterstützung für Restricted Keys
• Webhook-Signatur-Verifizierung – Validierung mit HMAC SHA-256
• TLS-Verschlüsselung – Gesamte API-Kommunikation über HTTPS verschlüsselt
• PCI-Compliance – Stripe verantwortet die PCI-DSS-Compliance für Zahlungsdaten
• IP-Whitelisting – Optionale IP-Einschränkungen für den API-Zugriff

Verwandte Ressourcen

• Stripe-API-Dokumentation
• Stripe-Webhooks-Guide
• Shopify-Connector
• Customer-Sync-Skill
• Brevo Contacts API