Skip to main content

Stripe

Stripe Integration Guide

Overview

This guide explains how to connect Bridged with Stripe to read payment data including customers, subscriptions, invoices, payment intents, and transaction history. The integration supports reading this data for activation, qualification, and nurture playbooks where payment and subscription context are needed.

Stripe is a payment processing platform for online transactions and subscriptions. It provides REST APIs for programmatic access to customers, charges, invoices, subscriptions, and payouts .

Primary Use Case: Read Payment Data

For Bridged's monetization and commercial integrations, the primary use case is reading payment-related data, including:

Data Type

Use in Bridged

Customer data

Personalize outreach based on subscription status

Subscription details

Identify active/past subscribers for qualification

Payment history

Track successful/failed payments for lead scoring

Invoice data

Confirm purchase amounts and payment dates

Prerequisites

Before starting, ensure you have:

  • A Stripe account with API access

  • Your Secret API Key (from Dashboard → Developers → API keys)

  • For webhook support: Your Webhook Signing Secret

⚠️ Important: Stripe enforces a single platform connection policy for read/write access. Only one platform can be connected to a Stripe account at a time for read/write operations. Extensions with read-only permissions are exempt from this policy .

Connection Methods

Method

Best for

Setup complexity

Access Level

API Key (Secret Key)

Direct API access for automated pulls

Low

Read + Write

Restricted Key

Limited-scope access (e.g., read-only)

Low

Configurable

OAuth 2.0 (Connect)

Multi-platform scenarios

Medium

Read + Write

Recommendation: For standard use, use your Secret API Key. For enhanced security or read-only needs, generate a Restricted Key.

Access Levels

Permission Level

Capabilities

Read Only

View customers, subscriptions, charges, invoices, payouts, account balance

Read and Write

All read capabilities plus: create/update customers, charges, invoices, subscriptions; refund charges; delete customers

Step 1: Obtain Your API Key

  1. Log in to your Stripe Dashboard

  2. Navigate to Developers → API keys

  3. Locate your Secret Key (starts with sk_live_ or sk_test_)

  4. Click Create secret key if you need a new one

Optional: Create a Restricted Key

For read-only access or limited permissions:

  1. Click Create restricted key

  2. Select permissions (e.g., Read for customers, subscriptions, invoices)

  3. Name the key and create

  4. Copy the restricted key immediately — it won't be shown again

Step 2: Configure Bridged to Connect to Stripe

  1. Log in to your Bridged dashboard

  2. Navigate to the Integrations section. If you do not see this section, contact support@bridged.media

  3. Click Stripe → Connect Account

  4. Select API Key as your authentication method

  5. Enter your Secret API Key (or Restricted Key)

  6. Click Connect

API Request Example

To verify your connection works:

bash

curl -X GET "https://api.stripe.com/v1/customers?limit=3" \
  -u "YOUR_SECRET_KEY:"

Step 3: Configure Webhooks for Real-time Events (Optional)

Stripe webhooks allow Bridged to receive real-time notifications for payment events .

Step 3.1: Get Your Webhook Secret

  1. In Stripe Dashboard, go to Developers → Webhooks

  2. Click Add endpoint or select an existing endpoint

  3. The webhook signing secret (starts with whsec_) is displayed

Step 3.2: Configure Webhook Endpoint in Stripe

Field

Value

Endpoint URL

https://gateway.bridged.media/webhooks/stripe

Description

Bridged Integration

Events to send

Select relevant events (see below)

Step 3.3: Select Events to Send

Event

When it triggers

customer.created

New customer created

customer.subscription.created

New subscription started

customer.subscription.updated

Subscription changed

customer.subscription.deleted

Subscription canceled

invoice.payment_succeeded

Successful payment

invoice.payment_failed

Failed payment

charge.dispute.created

New dispute filed

Step 3.4: Webhook Security

Stripe includes a Stripe-Signature header with each webhook request. Bridged automatically verifies this signature using your webhook secret to ensure requests are genuinely from Stripe .

Step 4: Reading Data via API

Stripe's REST API uses cursor-based pagination with starting_after and ending_before parameters .

List Customers

bash

GET /v1/customers

Parameters:

  • limit - Max records per page (default 10, max 100)

  • starting_after - Cursor for next page

List Subscriptions

bash

GET /v1/subscriptions?customer={CUSTOMER_ID}

List Invoices

bash

GET /v1/invoices?customer={CUSTOMER_ID}

List Payment Intents

bash

GET /v1/payment_intents?customer={CUSTOMER_ID}

Pagination Pattern

Stripe returns a has_more flag and starting_after cursor :

json

{
  "has_more": true,
  "data": [...],
  "url": "/v1/customers"
}

To retrieve all records, loop until has_more is false, using the last record's ID as starting_after for the next request .

Step 5: Configure Sync Settings

Setting

Options

Description

Data objects

Customers, Subscriptions, Invoices, Payment Intents, Charges

Which payment data to read

Sync frequency

Hourly, Daily, Weekly

How often to refresh data

Sync method

API Direct, Webhooks, Both

Preferred data access method

Customer filter

All, Active subscriptions only, By status

Filter which customers to sync

Bulk sync limit: Each bulk operation is limited to 50 records per request. Use pagination with limit parameter (max 100) to retrieve larger datasets .

Common Use Cases

Playbook

How Payment Data Is Used

Activation

Read customer data to trigger payment reminders or subscription confirmations via WhatsApp

Qualification Agent

Read subscription status and payment history to prioritize high-value customers

Nurture & Conversion

Read invoice and payment data for post-purchase follow-up and retention campaigns

Example Conversation Powered by Stripe Data

When a customer asks "When is my next payment due?", Bridged:

  1. Reads customer's active subscriptions from Stripe API

  2. Retrieves next invoice date

  3. Returns payment schedule conversationally

Rate Limiting & Performance

Consideration

Details

Rate limits

Vary by API endpoint and plan; default ~100 reads/second

Pagination

Use limit parameter (max 100) for each request

Bulk operations

Maximum 50 records per request

Cursor-based pagination

Use starting_after with last record ID for next page

Security & Permissions

  • Stripe uses API Key authentication via HTTP Basic Auth

  • Secret keys should never be exposed in client-side code

  • Use Restricted Keys for limited-scope access (e.g., read-only)

  • Webhook signatures use HMAC-SHA256 for verification

  • All API calls should be made over TLS 1.2+

  • Credentials are encrypted and never stored in plain text

Troubleshooting

Issue

Likely cause

Solution

Connection fails (401)

Invalid API key

Verify key in Dashboard → Developers → API keys

No data returned

Wrong key permissions

Use key with read access; test with curl

Webhook not received

Invalid signature

Verify webhook secret matches Stripe Dashboard

Pagination incomplete

Limit set too high

Use limit (max 100) and loop with starting_after

Rate limiting (429)

Too many requests

Reduce sync frequency; implement exponential backoff

Single connection error

Another platform connected

Only one platform can have read/write access at a time

Support

For integration support, contact your Bridged account manager or email support@bridged.media.

For Stripe-specific questions: