Stripe: скилл для управления платежами и клиентами

--- name: stripe description: | Stripe API integration with managed OAuth. Manage customers, subscriptions, payments, invoices, and products. Use this skill when users want to interact with Stripe for billing and payments. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" --- # Stripe Access the Stripe API with managed OAuth authentication. Manage customers, subscriptions, payments, invoices, and products. ## Quick Start ```bash # List customers python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/stripe/v1/customers?limit=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/stripe/{native-api-path} ``` Replace `{native-api-path}` with the actual Stripe API endpoint path. The gateway proxies requests to `api.stripe.com` and automatically injects your API credentials. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your Stripe connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=stripe&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'stripe'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "stripe", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Stripe connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/stripe/v1/customers') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## API Reference ### Customers #### List Customers ```bash GET /stripe/v1/customers?limit=10 ``` #### Get Customer ```bash GET /stripe/v1/customers/{customerId} ``` #### Create Customer ```bash POST /stripe/v1/customers Content-Type: application/x-www-form-urlencoded email=customer@example.com&name=John%20Doe&description=New%20customer ``` #### Update Customer ```bash POST /stripe/v1/customers/{customerId} Content-Type: application/x-www-form-urlencoded email=newemail@example.com ``` ### Products #### List Products ```bash GET /stripe/v1/products?limit=10&active=true ``` #### Create Product ```bash POST /stripe/v1/products Content-Type: application/x-www-form-urlencoded name=Premium%20Plan&description=Monthly%20subscription ``` ### Prices #### List Prices ```bash GET /stripe/v1/prices?limit=10&active=true ``` #### Create Price ```bash POST /stripe/v1/prices Content-Type: application/x-www-form-urlencoded unit_amount=1999&currency=usd&product=prod_XXX&recurring[interval]=month ``` ### Subscriptions #### List Subscriptions ```bash GET /stripe/v1/subscriptions?limit=10&status=active ``` #### Get Subscription ```bash GET /stripe/v1/subscriptions/{subscriptionId} ``` #### Create Subscription ```bash POST /stripe/v1/subscriptions Content-Type: application/x-www-form-urlencoded customer=cus_XXX&items[0][price]=price_XXX ``` #### Cancel Subscription ```bash DELETE /stripe/v1/subscriptions/{subscriptionId} ``` ### Invoices #### List Invoices ```bash GET /stripe/v1/invoices?limit=10&customer=cus_XXX ``` #### Get Invoice ```bash GET /stripe/v1/invoices/{invoiceId} ``` ### Charges #### List Charges ```bash GET /stripe/v1/charges?limit=10 ``` ### Payment Intents #### Create Payment Intent ```bash POST /stripe/v1/payment_intents Content-Type: application/x-www-form-urlencoded amount=1999&currency=usd&customer=cus_XXX ``` ### Balance #### Get Balance ```bash GET /stripe/v1/balance ``` ### Events #### List Events ```bash GET /stripe/v1/events?limit=10&type=customer.created ``` ## Code Examples ### JavaScript ```javascript const response = await fetch('https://gateway.maton.ai/stripe/v1/customers?limit=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } }); ``` ### Python ```python import os import requests response = requests.get( 'https://gateway.maton.ai/stripe/v1/customers', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'limit': 10} ) ``` ## Notes - Stripe API uses form-urlencoded data for POST requests - IDs are prefixed: `cus_` (customer), `sub_` (subscription), `prod_` (product), `price_` (price), `in_` (invoice), `pi_` (payment intent) - Amounts are in cents (1999 = $19.99) - Use `expand[]` parameter to include related objects - List endpoints support pagination with `starting_after` and `ending_before` - Delete returns `{id, deleted: true}` on success - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`items[]`, `expand[]`) to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping. ## Error Handling | Status | Meaning | |--------|---------| | 400 | Missing Stripe connection | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Stripe API | ### Troubleshooting: Invalid API Key **When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:** 1. Check that the `MATON_API_KEY` environment variable is set: ```bash echo $MATON_API_KEY ``` 2. Verify the API key is valid by listing connections: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Resources - [Stripe API Overview](https://docs.stripe.com/api) - [Customers](https://docs.stripe.com/api/customers) - [Products](https://docs.stripe.com/api/products) - [Prices](https://docs.stripe.com/api/prices) - [Subscriptions](https://docs.stripe.com/api/subscriptions) - [Invoices](https://docs.stripe.com/api/invoices) - [Payment Intents](https://docs.stripe.com/api/payment_intents) - [LLM Reference](https://docs.stripe.com/llms.txt)