Clickable prototype in 48h
Payments & compliance

Stripe Connect payments

Marketplace money movement on Stripe Connect: one buyer charge split across sellers, escrow and reserves, account onboarding, subscriptions with dunning, and a reconciled ledger.

Repository
timerise-ai/stripe-connect-subscriptions
Released
September 29, 2026
Build it with TimeriseBuild it yourself
npx skills add timerise-ai/stripe-connect-subscriptions
v0.1.11
Current release
13
Reference docs
5
Non-negotiables
MIT
License

The problem

What problem does Stripe Connect payments solve?

A marketplace takes one payment from the buyer and owes several sellers. Stripe Connect moves that money, but every step can fail on its own. The buyer's charge succeeds. A transfer to one seller is rejected. A refund claws back money already paid out. A subscription card expires. Get any of it wrong and someone is paid twice, or never.

This skill builds both money flows on one Stripe account. Marketplace settlement with separate charges and transfers, escrow and rolling reserves, and connected-account onboarding. Platform subscriptions charged to sellers off-session, with dunning when a card fails.

A ledger reconciles what Stripe says against what you recorded. Every webhook is safe to replay, so a crash between two writes never strands a seller.

The module

What does the skill build?

An agent with this skill builds one module for a Next.js App Router app, on your stack. For Stripe Connect payments that module consists of:

  • 1. Split charges
  • 2. Escrow and reserves
  • 3. Account onboarding
  • 4. Off-session billing with dunning
  • 5. Ledger reconciliation

Provenance

Where do the rules come from?

Written by the engineers who have shipped this module. The earlier implementation it was audited against was the payments and billing module of a multi-vendor marketplace on Stripe Connect. The templates hold four properties end to end: every webhook is claimed once and re-run to completion after a crash, every transfer is retried with adoption rather than re-sent, every seller is inside the platform's payout corridor before a charge is split, and every fee, reversal and clawback reconciles to the ledger. The money module's ten tests pin the rounding and distribution; the atomic claims in the store contract carry the rest. The record of what the audit changed is in `references/provenance.md`.

Written by the engineers who have shipped this module. The earlier implementation it was audited against was the payments and billing module of a multi-vendor marketplace running Stripe Connect (separate charges and transfers) plus platform subscription billing on one Stripe account, with unit tests, an operations runbook, and an incident history behind the comments.

The ledger separates what the audit changed, what was kept on purpose, and what has not run in production yet.

  1. Fixed in the templates

    • A crash between two transfer writes strands a seller permanently The earlier implementation built its crash-resume skip set from all transfer rows for the intent, keyed on vendorOrderId regardless of destinationKind. A vendor order can write two rows: the partner split first, then the seller's own leg. If settlement crashed in the window between them, the resumed run saw a transfer for that vendor order and skipped it entirely: no seller transfer, no escrow hold, no reserve, and the sub-order left pending forever.
    • One declined charge can burn two dunning attempts applySubscriptionChargeOutcome deduped a failure against invoice.payment_intent_id === pi.id. But the synchronous path only records an intent id when the Stripe SDK error carries one: a card decline does, a network error or timeout does not. When the charge failed that way, the row kept its old (or null) intent id, the webhook's comparison did not match, and a second failure was recorded for the same charge.
    • The Stripe client pinned no API version new Stripe(key, { appInfo }) with no apiVersion falls back to the version the installed SDK pins to. Deterministic per lockfile, so nothing is broken today, but bumping the stripe package silently changes request and response shapes across every call site in the module, including money-carrying ones.
    • Unbounded sweeps chargeDueInvoices selected every due invoice with no limit and charged them sequentially, one Stripe round-trip each. Correct, but on a large tenant base it exceeds the function timeout mid-run; the next run picks up, so it self-heals, and therefore nobody notices the sweep never completes.
Read the full record in provenance.md

Non-negotiables

What are the 5 rules the module never breaks?

Every module built from this skill holds these, whoever builds it. The same list is in the skill's README and SKILL.md, so the agent reads it before it writes a line.

  1. Never let a failed transfer fail the settlement.

    Record the leg unfunded and continue. The charge has already succeeded, so the webhook must succeed too; the retry cron funds the leg later.

  2. Never treat a duplicate webhook insert as "already handled".

    The insert is a claim; the retry after a delivery crashed mid-handling re-runs the handlers, so every event runs to completion exactly once.

  3. Never re-send a transfer without asking Stripe whether it already exists.

    A leg recorded unfunded because the response was lost pays twice once Stripe's 24h idempotency window passes.

  4. Never derive settlement exclusivity from a status flag written at the end.

    Two callers reach settlement routinely; an atomic leased claim is what makes inventory and transfers happen once.

  5. Never reverse more than a transfer's remaining headroom.

    Stacked reversals, such as a gateway fee and then a refund, are rejected past the original amount.

Fit

When should you use it, and when not?

Use it for

  • One payment splits across several sellers, with the platform taking a cut.
  • Sellers onboard to Connect and are paid on a delay (escrow, reserves, KYC).
  • The platform bills its own sellers a recurring fee on a saved card.
  • A connected account looks healthy but has never received any money.

Not for

  • Single-seller checkout, no splitInsteadStripe Checkout / Payment Element directly
  • PayPal Marketplace onboarding + payoutsInsteadA PayPal skill; only the seams are shared
  • Card UI, Payment Element stylingInsteadYour design system; this skill is server-side

Build it yourself

How do I install it?

One command. The skills.sh CLI installs the skill into every skills-compatible agent it finds.

$ npx skills add timerise-ai/stripe-connect-subscriptions

Claude Code

Invoke with /stripe-connect-subscriptions

Codex CLI

Invoke with $stripe-connect-subscriptions

Gemini CLI

Invoke with /skills

Name the agents instead with -a, for example npx skills add timerise-ai/stripe-connect-subscriptions -a claude-code -a codex. Or clone the repository into your agent's skills folder. Nothing in it is agent-specific.

What is inside the repository (20 entries)
  • SKILL.mdEntry point: when to use and when not to, the architecture, six critical facts, five hard rules, the quick start, and the reference directory
  • README.mdThis file: the human-facing front door
  • CHANGELOG.mdEvery release, newest first
  • CLAUDE.mdWhat this repository is and its editing conventions, for an agent editing the skill itself
  • LICENSEMIT
  • references/adaptation.mdThe seam contract with the host app: fitting it to your app, including which parts to leave behind
  • references/architecture.mdWhy separate charges and transfers, and the ledger it implies
  • references/data-model.mdSchema, columns, RLS
  • references/store.mdThe PaymentsStore data-access contract and its atomic claims
  • references/money.mdAmounts, rounding, largest-remainder distribution
  • references/stripe-adapter.mdStripe client, pinned API version, dual webhook secrets
  • references/connect-accounts.mdConnect onboarding, account.updated, capability flags
  • references/webhooks.mdReceiving events idempotently (claims, not dedupe)
  • references/settlement.mdSettlement fan-out, escrow holds, rolling reserves
  • references/reconciliation.mdTransfer retry with adoption, fee and clawback reconciliation
  • references/subscriptions.mdOff-session charges, saved cards, dunning, suspension
  • references/operations.mdEnv, setup order, crons, observability, troubleshooting
  • references/provenance.mdThe audit record: what changed from the earlier implementation, what was kept, and what is unverified
  • evals/The prompts an operator types after installing (prompts.md) and one file per agent eval: the skill installed into an empty Next.js app, one prompt, no help, then type-checked, built and tested
  • .github/workflows/agent-eval.ymlRuns the agent evals on every published release through the index's reusable workflow; the same in every skill

Recent releases

  1. v0.1.11September 29, 2026

    Fix release, from scoring the prompt-1 agent eval runs against 0.1.10.

  2. v0.1.10September 29, 2026

    Fix release, from scoring the prompt-1 agent eval runs against 0.1.9.

  3. v0.1.9September 29, 2026

    Brings the repository to the current skill standard. The money model, the templates' logic and the non-negotiables are unchanged from 0.1.8.

SKILL.md README.md CHANGELOG.md

After installing

What do I tell my agent?

Say what you need in your own words; the skill supplies the how. These are starting points, and the ones we tested say how it went.

  1. Add marketplace payments with Stripe Connect: a buyer pays once for items from several sellers, each seller gets their share minus our 10% fee, paid out after a 7-day hold.

    StripeGemini CLIBuilt, checks passCodex CLIBuilt, checks passClaude CodeBuilt, checks pass

  2. Bill each seller on our platform a monthly fee on their saved card, with retries and emails when the card fails.

    Stripe

  3. One of our connected accounts looks healthy in Stripe but has never received a payout. Find out why.

    Stripe

Tested

How does it do in each agent?

We install the skill into an empty Next.js app, give the agent one of the prompts above and no further help, then type-check, build and run the tests it left behind. Nothing is fixed by hand before the checks, and a failing run is published like a passing one. The procedure and every result are public, and the first prompt runs again before each release.

  • Gemini CLI0.61.0

    gemini-3.8-flash

    Built, checks pass
    Add marketplace payments with Stripe Connect: a buyer pays once for items from several sellers, each seller gets their share minus our 10% fee, paid out after a 7-day hold.
    Typecheck: passBuild: passTests: pass
    Time
    11 min
    Changed
    41 files, +6,227 lines
    Stack
    Stripe
    Skill
    v0.1.11
    Run
    Sep 29, 2026

    Result fileAgent log

    What we saw

    Rubric 8/8, scored from the JSON summary. money.test.ts was copied unmodified, and vitest runs its ten tests. PHYSICAL_ESCROW_DAYS = 7 and SERVICE_ESCROW_HOURS = 168 keep the template's names. Transfers run at settlement with source_transaction on manual payouts, and the store is PgPaymentsStore, with the in-memory one for offline tests. .env.example holds the five variables and DATABASE_URL, empty and un-ignored. The final message names the region check, both endpoints with their secrets, and every cron behind CRON_SECRET.

  • Codex CLIcodex-cli 0.159.0

    gpt-6-astra

    Built, checks pass
    Add marketplace payments with Stripe Connect: a buyer pays once for items from several sellers, each seller gets their share minus our 10% fee, paid out after a 7-day hold.
    Typecheck: passBuild: passTests: pass
    Time
    20 min
    Changed
    68 files, +5,250 lines
    Stack
    Stripe
    Skill
    v0.1.11
    Run
    Sep 29, 2026

    Result fileAgent log

    What we saw

    Rubric 8/8, scored from the diff and transcript. The templates were copied with imports supplied and no lock around the lease. money.ts was asserted byte-identical to the skill's. The escrow constants are 7 days and 168 hours, names kept. The ten money tests run under vitest. The final message names both webhook endpoints with their secrets, the four crons behind CRON_SECRET, and the runtime platform-country check. It patched nothing and named five template risks in docs/payments-handover.md instead. Two are candidates for the next fix: a failed transfer lookup in the retry sweep falls through to a re-send, and settlement moves money before writing the leg without adopting from the transfer group on resume. Past Stripe's 24-hour idempotency window, either can pay twice. Doubt: settlement.ts does not appear in the final diff's file list, so its presence is taken from the handover's word.

  • Claude Code2.1.284

    claude-opus-5-5

    Built, checks pass
    Add marketplace payments with Stripe Connect: a buyer pays once for items from several sellers, each seller gets their share minus our 10% fee, paid out after a 7-day hold.
    Typecheck: passBuild: passTests: pass
    Time
    11 min
    Changed
    40 files, +4,673 lines
    Stack
    Stripe
    Skill
    v0.1.10
    Run
    Sep 29, 2026

    Result fileAgent log

    What we saw

    Rubric 8/8, scored from the JSON summary. money.test.ts was copied unchanged and runs its ten tests under vitest. Transfers run at settlement, the 7-day hold is the escrow window, and accounts are created on manual payouts. .env.example lists the five variables plus DATABASE_URL, empty. The final message names the country check, both webhook endpoints with their event sets and secrets, and the crons behind CRON_SECRET. It left the templates unpatched and named two flaws in the handover. Both reproduce against the template: the escrow holds were written only beside a newly created seller leg, so a crash before them skipped them on resume, and a seller not yet onboarded never got them. Fixed in 0.1.11.

Build it with Timerise

How long does it take, and what does it cost?

We quote this module per project. The price depends on what it has to connect to. The path to a number is short and free:

  1. Step 1

    Brief

    Tell us what the module must connect to. Takes minutes, in a chat.

  2. Step 2

    Prototype in 48 hours

    A clickable prototype of your system and a quote, at no cost.

  3. Step 3

    Build and handoff

    One project price. Source code, documentation and IP are yours.

Two ways to get Stripe Connect payments

Build it yourself

Install the skill. Your own agent builds the module.

  • MIT licensed, no strings
  • Runs in Claude Code, Codex CLI and Gemini CLI
  • The same rules our engineers build by
$ npx skills add timerise-ai/stripe-connect-subscriptions
Install the skill

Build it with Timerise

Send a brief. We build Stripe Connect payments into a system you own.

  • Clickable prototype and a quote within 48 hours, free
  • One project price, no subscription, no commission
  • Source code, documentation and IP handed over
3 years of support included.
Start the brief

Generated from the skill's own files at commit d6527ce. Every rule above links to where the repository says it. All skills