Integrations

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.

  1. In the Stripe Dashboard, open Developers -> API keys and select Create restricted key.
  2. Name it, for example Octocom.
  3. Set the base permissions below to Read, plus any extra permissions for what you want the bot to do. Leave everything else at None.
  4. Select Create key and copy the key. It starts with rk_live_ (or rk_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.

ResourcePermission
CustomersRead
ChargesRead
Payment IntentsRead
InvoicesRead
SubscriptionsRead

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 doPermissions
Cancel, pause or resume a subscription, change plan, add a discountSubscriptions: 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 invoiceInvoices: Write, Credit Notes: Write
Update a customer's email, address or metadataCustomers: 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

  1. Open Settings -> Integrations -> Stripe.
  2. Paste the key and select Connect.
  3. 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.

On this page