Connect Stripe

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

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.