# Stripe

Source module: `app/connectors/stripe_conn.py`. Kind: **facts** only. Display name: "Stripe".

This is the **data connector** that reads a customer's own Stripe account for refund/credit facts. It is unrelated to CommitLayer's own subscription billing (`app/billing/stripe_billing.py`), which uses the platform's Stripe account and separate keys.

## Purpose

Reads refunds, credit notes and subscription cancellations so that the `refund_or_credit_within`, `refund_posted_within` and subscription-related signals can be evaluated against claims from help-desk vendors.

Since 0.9.5 it also reads **outbound payments** from the account's financial accounts (Treasury v1 and Money Management v2, the API behind Global Payouts and `stripe pay`), so that a transfer an agent sends can be verified under the `stripe_b2b_transfer` library contract: did it exist, go to the intended recipient, once, for the amount asked, reach `posted`, and stay there.

## Auth and scopes

| Item | Value |
|---|---|
| Method | Restricted API key, sent as `Authorization: Bearer`, against `https://api.stripe.com` |
| Credentials stored (encrypted) | `api_key`; optional `base_url` |
| Least-privilege permissions for the restricted key | **Refunds: read**, **Credit notes: read**, **Subscriptions: read**, **Customers: read** (needed only to expand the customer on refunds/credit notes for email hashing), **Charges: read** (implied by expanding `charge.customer` on refunds). To verify transfers an agent sends, add **Financial accounts: read** and **Outbound payments: read** (Treasury), and **Money Management Outbound Payments: read** (v2). Everything else: none. A key without the transfer permissions still syncs refunds; the connection's health message says what to grant. |
| Connection test | `GET /v1/refunds?limit=1` |
| Non-secret config | none |

## Fields pulled and why

| Endpoint | Fields | Used for |
|---|---|---|
| `GET /v1/refunds?created[gt]=since&expand[]=data.charge.customer` | `id`, `amount`, `currency`, `created`, `charge.customer.id`, `charge.customer.email` | Refund facts, subject id, hashed email, watermark |
| `GET /v1/credit_notes?created[gt]=since&expand[]=data.customer` | `id`, `amount`, `currency`, `created`, `customer.id`, `customer.email` | Credit facts, subject id, hashed email |
| `GET /v1/subscriptions?created[gt]=since` | `id`, `status`, `canceled_at`, `customer` | Subscription-cancellation facts |
| `GET /v1/treasury/financial_accounts` then `GET /v1/treasury/outbound_payments?financial_account=&created[gt]=since-35d` | `id`, `amount`, `currency`, `status`, `status_transitions`, `customer` / `destination_payment_method`, `financial_account`, `created`, `returned_details.code` | Outbound-payment facts (Treasury v1) |
| `GET /v2/money_management/outbound_payments?created_gt=since-35d` (header `Stripe-Version: 2026-04-22.preview`, pages followed by `next_page_url`) | `id`, `amount.value/currency`, `status`, `status_transitions`, `to.recipient` / `to.payout_method`, `from.financial_account`, `created`, `status_details.returned.reason` | Outbound-payment facts (Money Management v2) |

Amounts are converted from minor units (`amount / 100`). Outbound payments are re-read 35 days behind the watermark on every sync, because a payment changes status after it is created (`posted`, `returned`) and the facts for those statuses are keyed on the payment; the re-read is idempotent.

## What is hashed / never stored

- Customer email (from the expanded customer object) → `customer_hid` (HMAC-SHA256, per-tenant key); the email is discarded.
- Card details, payment method data, customer names, addresses, invoice line items, charge descriptions and metadata are never requested or stored.
- The restricted key is stored only as ciphertext.

## Incremental sync and watermark

- All three lists use `created[gt] = <watermark epoch>` (0 on first sync), page size 100, cursor via `starting_after = <last id>` while `has_more`.
- Watermark = maximum refund `created` (credit notes and subscriptions do not advance it).
- Upserts are idempotent.

## Rate-limit handling

Shared `HttpClient` (Retry-After, exponential backoff on `429`/`5xx`, 6 attempts, immediate `reauth` failure on `401`/`403`).

## Fact types produced

Subject id is the Stripe customer: `stripe_customer_{customer_id}`.

| `fact_type` | Subject kind | When | Attributes | `raw_ref` |
|---|---|---|---|---|
| `refund` | `customer` | Each refund | `amount` (major units), `currency`, `customer_hid` | `stripe:refund:{refund_id}` |
| `credit` | `customer` | Each credit note | `amount`, `currency`, `customer_hid` | `stripe:credit_note:{credit_note_id}` |
| `subscription_change` | `subscription` | Each listed subscription with `canceled_at` set | `status`, `change: "canceled"` | `stripe:subscription:{subscription_id}:canceled` |
| `outbound_payment_created` | `recipient` | Each outbound payment, at `created`; attributes refresh on every sync | `amount`, `currency`, `payment_id`, `status`, `financial_account` | `stripe:outbound_payment:{id}` |
| `outbound_payment_posted` | `recipient` | Status `posted`, at `status_transitions.posted_at` | `amount`, `currency`, `payment_id` | `stripe:outbound_payment:{id}:posted` |
| `outbound_payment_returned` | `recipient` | Status `returned`, at `returned_at` | `amount`, `currency`, `payment_id`, `reason` | `stripe:outbound_payment:{id}:returned` |
| `outbound_payment_failed` | `recipient` | Status `failed` or `canceled`, at `failed_at` / `canceled_at` | `amount`, `currency`, `payment_id`, `status` | `stripe:outbound_payment:{id}:{status}` |

Outbound-payment facts use the subject `stripe_recipient_{id}`, where the id is the recipient as Stripe names it: `to.recipient` (an `acct_…`) or `to.payout_method` on v2, the `customer` or `destination_payment_method` on v1. An agent that records a `stripe_b2b_transfer` action uses the same subject (the `--json` output of `stripe pay` carries it), or pushes a `links` entry from the profile handle it was told to pay to that id.

## Claims produced

None.

## Subject id format

`stripe_customer_{cus_…}`. Because help-desk claims name a conversation or ticket, Stripe facts only become relevant to a claim through a **subject link** between the conversation subject and the Stripe customer subject. The link is made by matching `customer_hid` (hashed email) between the two sources; the library function `app.connectors.base.resolve_identities` performs this, and a scheduled identity-resolution pass is a planned addition (see ARCHITECTURE.md §4). Until then, links can be supplied via a CSV facts upload whose `subject_id` equals the conversation subject.

## Known limitations

- Subscription cancellations are discovered through `created[gt]`, i.e. only subscriptions **created** after the watermark are listed; cancellations of older subscriptions are missed. This is a known gap.
- Refunds without an expandable charge/customer (e.g. some Checkout or PaymentIntent flows) produce a subject id with an empty customer id and cannot be linked.
- No `customer_hid` on subscription facts (customer is referenced by id only).
- Partial refunds and full refunds are not distinguished in the fact type; `amount` is available in attributes.
- Disputes/chargebacks are not read.
- A recipient Stripe has never paid has no record at all, so an agent's claim to have paid it, when nothing was created, answers UNKNOWN (`identity_unmatched`, "subject not found") rather than FAIL; once any payment to that recipient exists, a missing one is a FAIL. The v2 list is read under a pinned preview API version (`V2_VERSION` in the module); Stripe may move it.
- Financial-account balances are not read: Stripe's `posted` status is its own statement that funds left the account, and a balance snapshot taken at sync time cannot be aligned with the action's moment.