# Stripe (read-only)

Read invoices and payments from your Stripe account.

URL: https://docs.qaldy.com/connectors/stripe/

- **Status:** [[Available]]
- **Shelf:** Commerce and payments
- **How you connect:** API key
- **Regions:** global (not available to Kazakhstan-only workspaces)
- **The service’s own API reference:** https://docs.stripe.com/api

Apps read invoices, charges and customers from your Stripe account with a **restricted key**. Stripe
is reached through the HTTP API connector with a preset: the gate calls only `api.stripe.com/v1` and
only with `GET`, so an app can read and cannot charge, refund or change anything. The key is sealed
to the gate and apps never see it.

> **Status: Available through the HTTP API preset.** The preset follows Stripe's API reference
> (checked 2026-10-16). It has not been run against a live Stripe account.

## Connect it

1. In the Stripe Dashboard, open **Developers → API keys → Create restricted key**
   ([dashboard.stripe.com/apikeys](https://dashboard.stripe.com/apikeys)).
2. Set every permission to **Read**, and only for what the apps read (Invoices, Charges, Customers…).
   Also give it **Balance: Read**: Test connection calls `GET /v1/balance`. Never use a secret key
   (`sk_…`) here: it can do everything.
3. Copy the key. It starts with `rk_live_` (or `rk_test_` for test mode).
4. Qaldy → **Connectors** → Stripe → **Connect Stripe** → paste the key → **Seal and connect**.

A restricted key is the real fence (Stripe refuses what it doesn't allow); the gate's `GET`-only
rule is the second.

## What the gate allows

| | |
|---|---|
| Host | `api.stripe.com`, base path `/v1` (pinned, every resolved address public) |
| Methods | `GET` |
| Paths | everything under `/v1` that the key may read |
| Key | `Authorization: Bearer <key>`, added by the gate |

## Use it from an app

```json
{ "id": "http", "actions": ["request"], "scope": "conn_k3v9…" }
```

```ts
const api = ctx.connectors.http('conn_k3v9…')
const open = await api.get<{ data: Array<{ id: string; amount_due: number }> }>('/invoices', {
  query: { status: 'open', limit: 20 },
})
```

Stripe amounts are in minor units (cents, tiyn).

## When it breaks

| You see | Why | Do |
|---|---|---|
| Test says "Reached Stripe, but it answered 403" | The key can't read Balance | Add Balance: Read, or ignore the test: the permissions the apps need are what counts |
| `401` | The key was rolled or mistyped | Replace the key |
| Blocked: `method_not_allowed` | The app tried to write | The preset is read-only by design; use your own HTTP API connection with a narrower scope if a write is truly needed |

Native Stripe actions (`ctx.connectors.stripe.listInvoices`) are not served by the gate; apps use the
HTTP connector as above.