# Connect Stripe

> Watch failed payments, disputes, subscriptions, payouts and your balance with a read-only restricted key. A declined card reaches your Mac's notch with the amount, the customer and the bank's reason.

Source: https://coisland.app/docs/connect-stripe/

## What you need

- **You need:** Restricted key, Read, from Developers › API keys (https://dashboard.stripe.com/apikeys)
- **The form asks:** Restricted key
- **You can watch:** Failed payments, New disputes, Subscriptions, Failed payouts, Low balance
- **Access:** GET requests only, with a restricted key whose permissions are Read; a secret key is refused

CoIsland calls Stripe's API straight from your Mac: there is no CoIsland server. The key stays in your login Keychain and every request is a `GET`. CoIsland refuses a secret key (`sk_`): it can do anything in your account, including refunds and payouts.

This is your own Stripe account, watched from the notch. It has nothing to do with how CoIsland itself is sold.

## Create a restricted key

1. In the Stripe Dashboard, open **Developers › API keys** (`dashboard.stripe.com/apikeys`). For a sandbox, switch to it first: its keys start with `rk_test_`.
2. Click **Create restricted key**, and name it `CoIsland`.
3. Set **Read** on what you will watch, and leave everything else at **None**:

| Permission | Monitor kind |
|---|---|
| Charges (Charges and Refunds) | Failed payments |
| Disputes | New disputes |
| Subscriptions | Subscriptions |
| Payouts | Failed payouts |
| Balance | Low balance |

4. Click **Create key**, complete the two-step verification, and copy the key. A live key you created is shown only once.

Only the account owner and team members with the Administrator, Super Administrator or Developer role can create API keys. Other roles (Analyst, View only, Support) cannot: ask one of them for a restricted key with the permissions above.

## Connect Stripe in CoIsland

1. Open **Settings › Connectors**, click **+**, and choose **Stripe**.
2. Paste the key, then click **Test connector**. It makes one small request per permission and says the mode (Live or Test) and what the key reads, for example `Live mode · Reads Charges, Disputes, Subscriptions · No access to Payouts, Balance`.
3. Click **Add Connector**. The mode is kept in `connectors.json`, the key in your login Keychain.

## Watch Stripe: the five monitor kinds

| Kind | What alerts | What CoIsland calls |
|---|---|---|
| Failed payments | A charge that failed within the lookback (24 hours unless you choose) | `GET /v1/charges/search` for `status:"failed"` |
| New disputes | A dispute opened within the lookback (3 days) | `GET /v1/disputes?created[gte]=…` |
| Subscriptions | A subscription started, or canceled (now or at the period's end), within the lookback (24 hours) | `GET /v1/subscriptions?status=all&created[gte]=…` and `GET /v1/subscriptions/search` for `canceled_at` |
| Failed payouts | A payout created within the lookback (7 days) that failed | `GET /v1/payouts?status=failed&created[gte]=…` |
| Low balance | A currency's available balance under the amount you set | `GET /v1/balance` |

```text
lookback:24h
lookback:3d
change:canceled lookback:24h
lookback:7d
below:500 currency:usd
```

- Each item alerts once. A subscription can alert when it starts and again when it is canceled.
- A low balance alerts once when it drops, and again only after it has recovered.
- Search is not available to businesses in India: there, Failed payments and cancellations fail with Stripe's reason.

Clicking a row in the notch opens the alert in CoIsland: a failed payment shows the bank's decline, the network's answer and the card; a dispute the date to respond by; a cancellation the customer's feedback and comment. **Open in Stripe** goes to the payment, payout or subscription in the Dashboard.

## Requests and Stripe's read allowance

Each check is one request, or two for Subscriptions. Stripe allows an average of 500 reads per transaction over 30 days, and at least 10,000 a month. Monitors check every 15 minutes unless you choose (payouts and balance every hour): about 3,000 reads a month each. On a quiet account, keep to a few monitors or check less often.

## Troubleshooting Stripe connector errors

- **"This is a secret key…"** Create a restricted key instead (above).
- **"Stripe refused the key…"** The key is mistyped, expired or rolled. Create a new one.
- **"The restricted key cannot read Subscriptions…"** Edit the key in Stripe and set that permission to Read. Stripe's own words follow.
- **"Rate limited."** Stripe asked to slow down; CoIsland waits, then retries.