Stripe is a global payment platform that makes it easy to process payments, manage subscriptions, and distribute money. Stripe’s API allows you to build this payment infrastructure into your app.

Sequin syncs Stripe’s API to an ordered event stream you can use to easily build your payments integration, or connect into your customer’s Stripe account.

You can build directly on the Sequin stream or forward data to your database, Kafka or any other system you use to store and process data. We’ll handle the authentication, rate limit, and consistency for you.

You’ll create, update, and delete Stripe objects (e.g. customers, subscriptions, and invoices) using Sequin’s Collection Mutation API. Sequin simultaneously applies changes to Stripe and the event stream. Giving you a unified interface to Stripe.

Here is how our Stripe sync works:

Sync process

Authentication

You can authenticate with Stripe in the Sequin Console using Stripe Connect (OAuth) or API keys:

You can also authenticate with Stripe by importing a credential via the Management API:

curl --request POST \
  --url https://api.sequin.io/v1/credentials \
  --header 'Content-Type: application/json' \
  --data '{
    "properties": {
      "kind": "stripe_key",
      "secret_key": "sk_live_7eC39HqLyjWDarjtT1zdp7dc"
      "test": false
      "name": Chaom Spice
    },
    "metadata": { "custom_property": 42 }
  }'
If you use a restricted API key, be sure to grant read and write permissions to the objects you want to sync.

Backfill

When you first connect to Stripe, Sequin will extract all the data from the collections you want to sync. This is called backfilling.

To backfill Stripe, Sequin will paginate through each collection starting with the oldest records and working forwards in time. This ensures that you get all the data from Stripe in to your stream.

For larger Stripe accounts, this process can take a few hours.

Real-time

Once the backfill is complete, Sequin polls Stripe’s events endpoint twice per second second to detect changes. Sequin’s Stripe integration is architected around polling to guarantee consistency, removing the risk of missing changes due to webhook issues. When a change is detected, Sequin will fetch the new data and write it to your stream.

With the exception of bulk operations, Sequin will write changes to your stream within 1-2 seconds of the change happening in Stripe.

Pacing

Stripe has both a rate limit and a concurrency limit. Sequin paces requests to Stripe to avoid hitting these limits.

During an initial backfill, Sequin will make at most 50 requests to Stripe per second to rapidly extract all the data from Stripe efficiently. Once the backfill is complete, Sequin will poll Stripe’s events endpoint twice per second to detect changes.

Pacing can be configured in your sync.

Schema

Collections

Sequin syncs the following collections from Stripe:

  • Balance Transaction
  • Bank Account
  • Billing Portal Session
  • Bitcoin Receiver
  • Bitcoin Transaction
  • Capability
  • Charge
  • Checkout Session
  • Connect Collection Transfer
  • Coupon
  • Credit Note
  • Credit Note Line Item
  • Customer
  • Customer Balance Transaction
  • Discount
  • Dispute
  • Event
  • Fee Refund
  • Invoice
  • Invoice Item
  • Issuing Authorization
  • Issuing Card
  • Issuing Cardholder
  • Issuing Dispute
  • Issuing Transaction
  • Item
  • Line Item
  • Mandate
  • Order
  • Order Return
  • Payment Intent
  • Payment Method
  • Payout
  • Person
  • Plan
  • Platform Tax Fee
  • Price
  • Product
  • Promotion Code
  • Recipient
  • Refund
  • Reserve Transaction
  • Review
  • Setup Attempt
  • Setup Intent
  • Source
  • Source Mandate Notification
  • Source Transaction
  • Subscription
  • Subscription Item
  • Subscription Schedule
  • Tax Deducted At Source
  • Tax Id
  • Three D Secure
  • Token
  • Transfer
  • Transfer Reversal
  • Upcoming Customer Invoice
  • Upcoming Line Item
  • Upcoming Subscription Invoice
  • Usage Record
  • Usage Record Summary

Fields

Sequin syncs all fields from each collection. The collections are structured as per the Stripe API:

Amounts

Stripe stores currency amounts in the smallest unit.

As an example, $10.00 USD will be stored as an integer value of 1000 in your stream objects.

Currency

Currency types are stored as ISO 4217 Currency Codes in lower case.

Streams

Your Stripe sync will now populate data into the record and event streams. Here’s how Sequin structures Stripe objects in the stream:

Record stream

The record stream contains the current state of an object in the Stipe API. For instance, you’ll see the current state of a customer as it exists in Stripe. Below is the shape of a record in the Stripe customer collection:

{
  "collection_id": "stripe:customer",
  "deleted": false,
  "id": "5f7a0dc3-fe07-4d41-81da-bc029a58783f",
  "inserted_at": "2024-02-06T04:29:12.523925Z",
  "payload": {
    "address": null,
    "balance": 0,
    "created": 1707193751,
    "currency": null,
    "default_currency": null,
    "default_source": null,
    "delinquent": false,
    "description": null,
    "discount": null,
    "email": "Idaho@sequin.io",
    "id": "cus_PVhgqH2dJRNIgP",
    "invoice_prefix": "FB6215F7",
    "invoice_settings": {
      "custom_fields": null,
      "default_payment_method": null,
      "footer": null,
      "rendering_options": null
    },
    "livemode": false,
    "metadata": {},
    "name": "Duncan Idaho",
    "next_invoice_sequence": 1,
    "object": "customer",
    "phone": null,
    "preferred_locales": [],
    "shipping": null,
    "tax_exempt": "none",
    "test_clock": null
  },
  "payload_hash": "2RtgGcu4yScK7Wj6E9SM5A==",
  "resource_id": "5f4fd871-4422-4084-900f-f639583aa681",
  "updated_at": "2024-02-06T04:29:12.523925Z",
  "upsert_opts": null,
  "upstream_id": "cus_PVhgqH2dJRNIgP",
  "upstream_updated_at": "2024-02-06T04:29:11.000000Z"
}

Event stream

The event stream contains the changes to an object in the Stripe API. As an example, if the name field of a customer object is updated, the event stream will contain the following event:

{
  "changes": {
    "name": "Duncan Idaho"
  },
  "collection_id": "stripe:customer",
  "created_at": "2024-02-06T04:31:11.508658Z",
  "data": {
    "address": null,
    "balance": 0,
    "created": 1707193751,
    "currency": null,
    "default_currency": null,
    "default_source": null,
    "delinquent": false,
    "description": null,
    "discount": null,
    "email": "Idaho@sequin.io",
    "id": "cus_PVhgqH2dJRNIgP",
    "invoice_prefix": "FB6215F7",
    "invoice_settings": {
      "custom_fields": null,
      "default_payment_method": null,
      "footer": null,
      "rendering_options": null
    },
    "livemode": false,
    "metadata": {},
    "name": "Paul Atreides",
    "next_invoice_sequence": 1,
    "object": "customer",
    "phone": null,
    "preferred_locales": [],
    "shipping": null,
    "tax_exempt": "none",
    "test_clock": null
  },
  "event_type": "updated",
  "id": "298067bf-061f-4527-995d-36f88e1b2ddc",
  "resource_id": "5f4fd871-4422-4084-900f-f639583aa681",
  "upstream_id": "cus_PVhgqH2dJRNIgP",
  "upstream_updated_at": "2024-02-06T04:31:11.000000Z"
}

Consumers

You can build directly on Sequin’s stream using the stream APIs. Or forward data to your database, Kafka or any other system you use to store and process data.

Stripe syncs work with all the consumers Sequin supports.

Mutations

When you need to create, update, or delete a Stripe object, you can use Sequin’s Collection Mutation API. For instance, if you want to create a customer in Stripe, you’ll use the create mutation:

curl -X POST \
  https://api.sequin.io/v1/mutations/run/create \
  -H 'content-type: application/json' \
  -d '{
        "sync_id": "my-sync-id",
        "collection_id": "stripe.customer",
        "data": [
          {
            "name": "Paul Atreides"
          }
        ]
      }'

Sequin will handle the authentication, rate limit, and consistency for the request by simultaneously applying changes to Stripe and the event stream. As an added consistency guarantee, you can also specify which consumers you want to await before returning the mutation response.

For instance, you can ensure that a new customer has been added to your database before the the API returns a 200 OK.

Development

Sequin integrates with Stripe’s test mode accounts to help you build and test your integration.

To setup a sync with a Stripe test account, you can provide Sequin with a test API key or check the “Test mode” box when creating a sync.

Once you’ve tested your integration, you can use the Management API to easily replicate your sync to your production account.