Stripe Connector

Stripe Connector

Connect your Stripe account to Brevo via Tajo for complete payment data synchronization, subscription lifecycle management, and revenue-driven marketing automation.

Overview

Features

• Customer sync - Sync Stripe customers with Brevo contacts including metadata
• Payment tracking - Track successful payments, refunds, and failed charges
• Subscription management - Sync subscription lifecycle events for retention campaigns
• Invoice data - Sync invoice details for post-purchase and renewal automation
• Revenue attribution - Map lifetime value and MRR to Brevo attributes
• Webhook events - Real-time event notifications for all payment activities
• Multi-currency support - Handle payments across multiple currencies
• Checkout session tracking - Track Stripe Checkout for abandoned payment recovery

Prerequisites

Before you begin, ensure you have:

1. A Stripe account with API access
2. Stripe API keys (publishable and secret keys)
3. A Brevo account with API access
4. A Tajo account

Authentication

API Key Authentication

Stripe uses bearer token authentication with your secret API key.

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

Restricted API Keys

Create restricted keys with specific permissions for enhanced security:

1. Go to Stripe Dashboard > Developers > API Keys
2. Click “Create restricted key”
3. Grant only the permissions Tajo requires

Required Permissions

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

Configuration

Basic Setup

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

Field Mapping

Map Stripe customer data to Brevo contact attributes:

Custom Attribute Mapping

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

Core Endpoints

Subscription Endpoints

Event Endpoints

Events

Payment Events

Subscription Events

Customer Events

Code Examples

Initialize Connector

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

Run Customer Sync

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

Handle Stripe Webhooks

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 enforces the following rate limits:

Troubleshooting

Common Issues

Debug Mode

Enable verbose logging:

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

Test Connection

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

Best Practices

1. Use restricted API keys - Create keys with minimum required permissions
2. Always verify webhook signatures - Prevent spoofed webhook events
3. Handle idempotency - Use Stripe event IDs to prevent duplicate processing
4. Sync customer metadata - Store marketing-relevant data in Stripe metadata fields
5. Monitor webhook delivery - Check Stripe Dashboard for failed deliveries
6. Use test mode first - Validate your integration with Stripe test mode and test clocks

Security

• API Key Authentication - Secret key-based access with restricted key support
• Webhook signature verification - HMAC SHA-256 signature validation
• TLS encryption - All API communication encrypted via HTTPS
• PCI compliance - Stripe handles PCI DSS compliance for payment data
• IP whitelisting - Optional IP restrictions for API access

Related Resources

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

Open-Source Implementation Map

This section is derived from official or public repository material discovered for the Stripe connector. Use it as the engineering companion to the setup guide above: it shows where the API surface lives, what implementation assets exist, and how Tajo should translate them into reliable Brevo sync behavior.

Repository Snapshot

Integration Shape

graph LR
  Source["Stripe API / repository"] --> Auth["Auth and scopes"]
  Source --> Objects["Objects, events, and schemas"]
  Auth --> Tajo["Tajo connector runtime"]
  Objects --> Tajo
  Tajo --> Brevo["Brevo contacts, attributes, lists, campaigns"]
  Tajo --> Ops["Backfill, cursor, retries, logs"]

What To Reuse

• Stripe’s OpenAPI Specification
• This repository contains [OpenAPI specifications][openapi] for Stripe’s API.
• Changelog
• Directory Structure
• | Directory | Description |

Tajo Revamp Checklist

• Keep authentication setup aligned with the vendor docs and the public repository’s current API shape.
• Map primary resources into explicit Tajo sync objects with stable external IDs.
• Prefer cursor-based or updated-at incremental sync where the API exposes it; otherwise document the fallback.
• Treat webhook handlers as idempotent and replay-safe, especially for order, contact, ticket, and campaign events.
• Capture pagination, rate limits, retry headers, and partial-failure behavior in connector smoke tests.
• Keep examples small and runnable against sandbox or test-mode accounts.

Sources

• stripe/openapi
• Vendor documentation