Stripe
Connect your Stripe account with a restricted API key so your Python actions can look up and manage customers, payments and subscriptions.
Connect Stripe to let your custom actions,
condition providers and other Python
automations call the Stripe API: find a customer's payments, invoices and subscriptions,
and, if you allow it, refund a payment or cancel a subscription. Octocom stores your key
securely and hands it to your Python code through
get_integration_credentials.
Connecting does not sync data or change anything in Stripe on its own.
Create a restricted key in Stripe
Use a restricted key rather than your secret key. A restricted key can only do what you allow, so you decide exactly what the bot can see and change.
- In the Stripe Dashboard, open Developers -> API keys and select Create restricted key.
- Name it, for example
Octocom. - Set the base permissions below to Read, plus any extra permissions for what you want the bot to do. Leave everything else at None.
- Select Create key and copy the key. It starts with
rk_live_(orrk_test_in a sandbox).
Base permissions
These let the bot look up customers, payments, refunds, invoices and subscriptions, which covers most support questions. They are all read-only.
| Resource | Permission |
|---|---|
| Customers | Read |
| Charges | Read |
| Payment Intents | Read |
| Invoices | Read |
| Subscriptions | Read |
Only Customers: Read is strictly required: Octocom checks the key by listing one customer.
Extra permissions for what the bot should do
You can give the key more permissions if you want the bot to make changes. Add only what your automations need:
| What the bot should do | Permissions |
|---|---|
| Cancel, pause or resume a subscription, change plan, add a discount | Subscriptions: Write, Prices: Read, Coupons: Read, Promotion Codes: Read |
| Issue full or partial refunds (Stripe groups refunds under Charges) | Charges: Write |
| Void, send or credit an invoice | Invoices: Write, Credit Notes: Write |
| Update a customer's email, address or metadata | Customers: Write |
You can change the permissions later by editing the same key in Stripe. The key stays the
same, so there is no need to reconnect in Octocom. If an automation calls something the key
isn't allowed to do, Stripe returns HTTP 403 and its error message names the missing
permission in its internal form: rak_charge_write means Charges: Write. Removing a
discount from a subscription also needs Customers: Write.
Connect it in Octocom
- Open Settings -> Integrations -> Stripe.
- Paste the key and select Connect.
- Octocom saves the key and checks it right away. If the check fails, the message says what to fix: usually a key copied incompletely or a missing Customers: Read permission. Fix it in Stripe and select Test connection.
The key is never shown again after saving; Octocom only shows its first characters and last four, so you can recognise it in Stripe's key list. To replace it, paste a new key into the same window.
You can also ask Copilot to connect Stripe, check the connection or disconnect it.
Use it from Python
The stripe entry contains apiKey and apiBaseUrl (https://api.stripe.com). Send the
key as a Bearer token. Fetch it each time your code runs rather than storing it.
import requests
def stripe_get(stripe, path, params):
response = requests.get(
f"{stripe['apiBaseUrl']}{path}",
headers={"Authorization": f"Bearer {stripe['apiKey']}"},
params=params,
timeout=30,
)
try:
body = response.json()
except ValueError:
body = {}
if not response.ok:
message = body.get("error", {}).get("message", f"HTTP {response.status_code}")
raise RuntimeError(f"Stripe request failed: {message}")
return body
def find_stripe_subscriptions(context, email):
slug = context["conversation"]["businessSlug"]
stripe = get_integration_credentials(context).get(slug, {}).get("stripe")
if not stripe:
raise ValueError("Connect Stripe in Settings -> Integrations first.")
customers = stripe_get(stripe, "/v1/customers", {"email": email, "limit": 10})
subscriptions = []
for customer in customers["data"]:
page = stripe_get(
stripe,
"/v1/subscriptions",
{"customer": customer["id"], "status": "all", "limit": 10},
)
subscriptions.extend(page["data"])
return {"subscriptions": subscriptions}This example reads the business from the conversation. In a recurring job, use your business
slug instead. The email filter on /v1/customers is an exact, case-sensitive match; Stripe's
/v1/customers/search matches more loosely but can lag about a minute behind new customers.
Stripe takes form-encoded request bodies: pass data= rather than json= on POST requests,
for example requests.post(f"{api}/v1/refunds", headers=headers, data={"payment_intent": "pi_..."}).
Amounts are in the currency's smallest unit (cents for USD). Never log the key or request
headers. See the Stripe API reference for the available
endpoints and their parameters.
Disconnect
Open Settings -> Integrations -> Stripe and select Disconnect. Automations that use the connection stop working. The key stays in Stripe; delete or roll it there if you no longer need it.