Stripe

The Stripe connector polls a Stripe account and surfaces acct_* balances, charges, transfers, payouts, payments, and refunds. It initiates transfers and payouts via v3 PaymentInitiation, and ingests Stripe webhooks for real-time updates.

Prerequisites#

You need a Stripe account and a restricted API key scoped to charges, transfers, payouts, balance, balance transactions, and external accounts. Webhook creation additionally requires webhook_endpoints:write.

Installation#

curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/stripe \
  -H "Content-Type: application/json" \
  -d @config.json

Configuration fields#

The connector uses the official stripe-go/v80 SDK with the apiKey as a Bearer token. The webhook secret is not in the config — Stripe assigns one when the connector creates the endpoint at install, and the platform stores it out-of-band.

Capabilities#

• FETCH_ACCOUNTS — connected accounts plus the platform's own acct_*, paginated via starting_after.
• FETCH_BALANCES — available + pending balance per currency, via GET /v1/balance per connected account.
• FETCH_EXTERNAL_ACCOUNTS — external bank accounts and debit cards per connected account.
• FETCH_PAYMENTS — charges, refunds, transfers, payouts, and balance transactions, unified into PSPPayment.
• CREATE_TRANSFER — POST /v1/transfers between platform-controlled accounts.
• CREATE_PAYOUT — POST /v1/payouts to an attached external account.
• CREATE_WEBHOOKS — provisions a WebhookEndpoint at install for the events the connector consumes.
• TRANSLATE_WEBHOOKS — converts charge.*, payout.*, transfer.*, balance.available, etc. to Connectivity events.

CREATE_BANK_ACCOUNT is not implemented — Stripe expects account holders to attach externals via the dashboard or Stripe-issued links.

Account model#

Every Connectivity internal account is one Stripe acct_* (a connected account or the platform's own root). The reference is the Stripe account ID, except for the platform's own which uses the legacy literal root for backwards compatibility; name is the display name; defaultAsset is the default_currency for single-currency accounts, null on multi-currency. EXTERNAL accounts come from each connected account's external bank accounts and debit cards. See Accounts for the cross-connector model.

Asset model#

Stripe returns lowercase ISO 4217 (usd, eur, jpy), formatted to UMN at standard precision (USD/2, EUR/2, JPY/0). Amounts are already in minor units — no scaling.

Status mapping#

Refunds land as separate PAY-IN rows against the original payment's account, linked via com.stripe.spec/refund_of.

Metadata keys#

Under com.stripe.spec/:

• Account: type (standard, express, custom), country, default_currency, details_submitted, payouts_enabled, charges_enabled.
• Payment: payment_method, payment_method_type (card, sepa_debit, us_bank_account, …), application_fee_amount, transfer_group, refund_of (when applicable).
• External account: routing_number, last4, bank_name, fingerprint.

Workflow tree#

FetchAccounts (periodic)
  ├── FetchBalances (FromPayload — no extra API call beyond /v1/balance per account)
  ├── FetchPayments (periodic) — Charges → Refunds → Transfers → Payouts → Balance Transactions
  └── FetchExternalAccounts (periodic) — per connected account

CreateWebhooks (one-shot at install)

Pagination and recovery#

Cursor-based via starting_after per resource. The connector persists the latest cursor per stream in platform-managed State; restarts resume from the last committed cursor (Stripe's at-least-once event semantics aside). The engine dedupes by PSPPayment.Reference.

Known gaps#

• Bank-account creation is not implemented; account holders attach externals via the Stripe dashboard or Financial Connections.
• Reverse transfer / reverse payout is not wired; refunds appear as separate PAY-IN rows linked via metadata.
• Multi-currency accounts: balance per (account, currency). Stripe doesn't expose a "default asset" on multi-currency accounts, so defaultAsset is null in that case.