Skill: byungkyu/stripe-api (version 1.0.10)

--- name: stripe description: | Stripe API integration with managed OAuth. This is a write-capable financial integration for customers, subscriptions, invoices, products, prices, and payments. Install only if you need Stripe administration. Connect with the least-privileged Stripe account and OAuth scopes available, verify the intended connection ID before each request, and revoke unused connections promptly. All write operations require explicit user approval showing the exact endpoint, target resource, object IDs, amounts, and test/live mode before execution. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key. metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 homepage: "https://maton.ai" requires: env: - MATON_API_KEY --- # Stripe Access the Stripe API with managed OAuth authentication. Manage customers, subscriptions, invoices, products, prices, and process payments. ## Quick Start **CLI:** ```bash maton stripe customer list -L 5 ``` ```bash maton api '/stripe/v1/customers?limit=5' ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.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://api.maton.ai/stripe/{endpoint-path} ``` The gateway proxies requests to `api.stripe.com` and automatically injects your OAuth token. Only the endpoints documented in the API Reference section below are supported — always use specific endpoint paths from that section rather than constructing arbitrary paths. ## Installation **NPM:** ```bash npm install -g @maton-ai/cli ``` **Homebrew:** ```bash brew install maton-ai/cli/maton ``` ## Authentication **CLI:** ```bash maton login # Opens browser for API key maton login --interactive # Skip browser, paste API key directly maton whoami # Show current auth state ``` **Manual:** 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 4. Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ## Connection Management Manage your Stripe OAuth connections at `https://api.maton.ai`. ### List Connections **CLI:** ```bash maton connection list stripe --status ACTIVE ``` ```bash maton api -X GET /connections -f app=stripe -f status=ACTIVE ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.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 **CLI:** ```bash maton connection create stripe ``` ```bash maton api /connections -f app=stripe ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'stripe'}).encode() req = urllib.request.Request('https://api.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://api.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": "{connection_id}", "status": "ACTIVE", "creation_time": "2026-02-01T06:04:02.431819Z", "last_updated_time": "2026-02-10T22:40:01.061825Z", "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://api.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://api.maton.ai/stripe/v1/customers') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '{connection_id}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` Always include the `Maton-Connection` header to ensure requests go to the intended Stripe account. If you have multiple connections and omit this header, the gateway uses a default connection, which may not be the intended account. Confirm the connected Stripe account before any write or payment action. ## Security & Permissions - Access is scoped to customers, subscriptions, invoices, products, prices, and payments within the connected Stripe account. This is financial data — install only if you need Stripe administration. Connect with least-privileged OAuth scopes and revoke unused connections promptly. - **Default to read-only operations.** Always start by listing or retrieving resources to confirm object IDs, amounts, and account context before proposing any changes. - **All write operations require explicit user approval with specific details.** Before executing any POST, PUT, or DELETE call: 1. Retrieve and display the target resource (customer name/ID, subscription ID, invoice number, product name) so the user can verify. 2. Show the exact endpoint, object IDs, amounts, and whether the account is in test or live mode. 3. Clearly describe the intended effect (e.g., "This will cancel subscription 'sub_123' for customer 'John Doe' (cus_456) — billing will stop immediately"). 4. Wait for explicit user confirmation before proceeding. - **Financial operations are high-impact and may be irreversible.** Processing payments, creating invoices, canceling subscriptions, deleting customers, and modifying prices affect real billing. These actions must include a summary of financial consequences and require confirmation. ## API Reference All Stripe API endpoints follow this pattern: ``` /stripe/v1/{resource} ``` --- ## Balance ### Get Balance ```bash GET /stripe/v1/balance ``` Example: ```bash maton stripe balance ``` **Response:** ```json { "object": "balance", "available": [ { "amount": 0, "currency": "usd", "source_types": {"card": 0} } ], "pending": [ { "amount": 5000, "currency": "usd", "source_types": {"card": 5000} } ] } ``` ### List Balance Transactions ```bash GET /stripe/v1/balance_transactions?limit=10 ``` Example: ```bash maton stripe balance-transaction list -L 10 ``` --- ## Customers ### List Customers ```bash GET /stripe/v1/customers?limit=10 ``` Example: ```bash maton stripe customer list -L 10 ``` **Query Parameters:** | Parameter | Description | |-----------|-------------| | `limit` | Number of results (1-100, default: 10) | | `starting_after` | Cursor for pagination | | `ending_before` | Cursor for reverse pagination | | `email` | Filter by email | | `created` | Filter by creation date | **Response:** ```json { "object": "list", "data": [ { "id": "cus_TxKtN8Irvzx9BQ", "object": "customer", "email": "[REDACTED_SECRET]", "name": null, "balance": 0, "currency": "usd", "created": 1770765579, "metadata": {} } ], "has_more": true, "url": "/v1/customers" } ``` ### Get Customer ```bash GET /stripe/v1/customers/{customer_id} ``` Example: ```bash maton stripe customer view {customer_id} ``` ### Create Customer ```bash POST /stripe/v1/customers Content-Type: application/x-www-form-urlencoded email=[REDACTED_SECRET]&name=John%20Doe&metadata[user_id]=123 ``` Example: ```bash maton stripe customer create --email [REDACTED_SECRET] --name 'John Doe' --metadata user_id=123 ``` ### Update Customer ```bash POST /stripe/v1/customers/{customer_id} Content-Type: application/x-www-form-urlencoded name=Jane%20Doe&email=[REDACTED_SECRET] ``` Example: ```bash maton stripe customer update {customer_id} --name 'Jane Doe' --email [REDACTED_SECRET] ``` ### Delete Customer ```bash DELETE /stripe/v1/customers/{customer_id} ``` Example: ```bash maton stripe customer delete {customer_id} ``` --- ## Products ### List Products ```bash GET /stripe/v1/products?limit=10 ``` Example: ```bash maton stripe product list -L 10 ``` **Query Parameters:** | Parameter | Description | |-----------|-------------| | `active` | Filter by active status | | `type` | Filter by type: `good` or `service` | **Response:** ```json { "object": "list", "data": [ { "id": "prod_TthCLBwTIXuzEw", "object": "product", "active": true, "name": "Premium Plan", "description": "Premium subscription", "type": "service", "created": 1769926024, "metadata": {} } ], "has_more": true } ``` ### Get Product ```bash GET /stripe/v1/products/{product_id} ``` Example: ```bash maton stripe product view {product_id} ``` ### Create Product ```bash POST /stripe/v1/products Content-Type: application/x-www-form-urlencoded name=Premium%20Plan&description=Premium%20subscription ``` Example: ```bash maton stripe product create --name 'Premium Plan' --description 'Premium subscription' ``` ### Update Product ```bash POST /stripe/v1/products/{product_id} Content-Type: application/x-www-form-urlencoded name=Updated%20Plan&active=true ``` Example: ```bash maton stripe product update {product_id} --name 'Updated Plan' --active true ``` ### Delete Product ```bash DELETE /stripe/v1/products/{product_id} ``` Example: ```bash maton stripe product delete {product_id} ``` --- ## Prices ### List Prices ```bash GET /stripe/v1/prices?limit=10 ``` Example: ```bash maton stripe price list -L 10 ``` **Query Parameters:** | Parameter | Description | |-----------|-------------| | `active` | Filter by active status | | `product` | Filter by product ID | | `type` | Filter: `one_time` or `recurring` | | `currency` | Filter by currency | **Response:** ```json { "object": "list", "data": [ { "id": "price_1SvtoVDfFKJhF88gKJv2eSmO", "object": "price", "active": true, "currency": "usd", "product": "prod_TthCLBwTIXuzEw", "unit_amount": 1999, "recurring": { "interval": "month", "interval_count": 1 }, "type": "recurring" } ], "has_more": true } ``` ### Get Price ```bash GET /stripe/v1/prices/{price_id} ``` Example: ```bash maton stripe price view {price_id} ``` ### Create Price ```bash POST /stripe/v1/prices Content-Type: application/x-www-form-urlencoded product=prod_XXX&unit_amount=1999&currency=usd&recurring[interval]=month ``` Example: ```bash maton stripe price create --product prod_XXX --unit-amount 1999 --currency usd --recurring-interval month ``` ### Update Price ```bash POST /stripe/v1/prices/{price_id} Content-Type: application/x-www-form-urlencoded active=false ``` Example: ```bash maton stripe price update {price_id} --active false ``` --- ## Subscriptions ### List Subscriptions ```bash GET /stripe/v1/subscriptions?limit=10 ``` Example: ```bash maton stripe subscription list -L 10 ``` **Query Parameters:** | Parameter | Description | |-----------|-------------| | `customer` | Filter by customer ID | | `price` | Filter by price ID | | `status` | Filter: `active`, `canceled`, `past_due`, etc. | **Response:** ```json { "object": "list", "data": [ { "id": "sub_1SzQDXDfFKJhF88gf72x6tDh", "object": "subscription", "customer": "cus_TxKtN8Irvzx9BQ", "status": "active", "current_period_start": 1770765579, "current_period_end": 1773184779, "items": { "data": [ { "id": "si_TxKtFWxlUW50cR", "price": { "id": "price_1RGbXsDfFKJhF88gMIShAq9m", "unit_amount": 0 }, "quantity": 1 } ] } } ], "has_more": true } ``` ### Get Subscription ```bash GET /stripe/v1/subscriptions/{subscription_id} ``` Example: ```bash maton stripe subscription view {subscription_id} ``` ### Create Subscription ```bash POST /stripe/v1/subscriptions Content-Type: application/x-www-form-urlencoded customer=cus_XXX&items[0][price]=price_XXX ``` Example: ```bash maton stripe subscription create --customer cus_XXX --price price_XXX ``` ### Update Subscription ```bash POST /stripe/v1/subscriptions/{subscription_id} Content-Type: application/x-www-form-urlencoded items[0][id]=si_XXX&items[0][price]=price_YYY ``` Example: ```bash maton stripe subscription update {subscription_id} --items 'id=si_XXX,price=price_YYY' ``` ### Cancel Subscription ```bash DELETE /stripe/v1/subscriptions/{subscription_id} ``` Example: ```bash maton stripe subscription cancel {subscription_id} ``` --- ## Invoices ### List Invoices ```bash GET /stripe/v1/invoices?limit=10 ``` Example: ```bash maton stripe invoice list -L 10 ``` **Query Parameters:** | Parameter | Description | |-----------|-------------| | `customer` | Filter by customer ID | | `subscription` | Filter by subscription ID | | `status` | Filter: `draft`, `open`, `paid`, `void`, `uncollectible` | **Response:** ```json { "object": "list", "data": [ { "id": "in_1SzQDXDfFKJhF88g3nh4u2GS", "object": "invoice", "customer": "cus_TxKtN8Irvzx9BQ", "amount_due": 0, "amount_paid": 0, "currency": "usd", "status": "paid", "subscription": "sub_1SzQDXDfFKJhF88gf72x6tDh", "hosted_invoice_url": "https://invoice.stripe.com/...", "invoice_pdf": "https://pay.stripe.com/invoice/.../pdf" } ], "has_more": true } ``` ### Get Invoice ```bash GET /stripe/v1/invoices/{invoice_id} ``` Example: ```bash maton stripe invoice view {invoice_id} ``` ### Create Invoice ```bash POST /stripe/v1/invoices Content-Type: application/x-www-form-urlencoded customer=cus_XXX ``` Example: ```bash maton stripe invoice create --customer cus_XXX ``` ### Finalize Invoice ```bash POST /stripe/v1/invoices/{invoice_id}/finalize ``` Example: ```bash maton stripe invoice finalize {invoice_id} ``` ### Pay Invoice ```bash POST /stripe/v1/invoices/{invoice_id}/pay ``` Example: ```bash maton stripe invoice pay {invoice_id} ``` ### Void Invoice ```bash POST /stripe/v1/invoices/{invoice_id}/void ``` Example: ```bash maton stripe invoice void {invoice_id} ``` --- ## Charges ### List Charges ```bash GET /stripe/v1/charges?limit=10 ``` Example: ```bash maton stripe charge list -L 10 ``` **Query Parameters:** | Parameter | Description | |-----------|-------------| | `customer` | Filter by customer ID | | `payment_intent` | Filter by payment intent | **Response:** ```json { "object": "list", "data": [ { "id": "ch_3SyXBvDfFKJhF88g1MHtT45f", "object": "charge", "amount": 5000, "currency": "usd", "customer": "cus_TuZ7GIjeZQOQ2m", "paid": true, "status": "succeeded", "payment_method_details": { "card": { "brand": "mastercard", "last4": "0833" }, "type": "card" } } ], "has_more": true } ``` ### Get Charge ```bash GET /stripe/v1/charges/{charge_id} ``` Example: ```bash maton stripe charge view {charge_id} ``` ### Create Charge ```bash POST /stripe/v1/charges Content-Type: application/x-www-form-urlencoded amount=2000&currency=usd&source=tok_XXX ``` Example: ```bash maton stripe charge create --amount 2000 --currency usd --source tok_XXX ``` --- ## Payment Intents ### List Payment Intents ```bash GET /stripe/v1/payment_intents?limit=10 ``` Example: ```bash maton stripe payment list -L 10 ``` **Response:** ```json { "object": "list", "data": [ { "id": "pi_3SyXBvDfFKJhF88g17PeHdpE", "object": "payment_intent", "amount": 5000, "currency": "usd", "customer": "cus_TuZ7GIjeZQOQ2m", "status": "succeeded", "payment_method": "pm_1SyXBpDfFKJhF88gmP3IjC8C" } ], "has_more": true } ``` ### Get Payment Intent ```bash GET /stripe/v1/payment_intents/{payment_intent_id} ``` Example: ```bash maton stripe payment view {payment_intent_id} ``` ### Create Payment Intent ```bash POST /stripe/v1/payment_intents Content-Type: application/x-www-form-urlencoded amount=2000&currency=usd&customer=cus_XXX&payment_method_types[]=card ``` Example: ```bash maton stripe payment create --amount 2000 --currency usd --customer cus_XXX --payment-method-types card ``` ### Confirm Payment Intent ```bash POST /stripe/v1/payment_intents/{payment_intent_id}/confirm ``` Example: ```bash maton stripe payment confirm {payment_intent_id} ``` ### Cancel Payment Intent ```bash POST /stripe/v1/payment_intents/{payment_intent_id}/cancel ``` Example: ```bash maton stripe payment cancel {payment_intent_id} ``` --- ## Payment Methods ### List Payment Methods ```bash GET /stripe/v1/payment_methods?customer=cus_XXX&type=card ``` Example: ```bash maton stripe payment-method list --customer cus_XXX --type card ``` ### Get Payment Method ```bash GET /stripe/v1/payment_methods/{payment_method_id} ``` Example: ```bash maton stripe payment-method view {payment_method_id} ``` ### Attach Payment Method ```bash POST /stripe/v1/payment_methods/{payment_method_id}/attach Content-Type: application/x-www-form-urlencoded customer=cus_XXX ``` Example: ```bash maton stripe payment-method attach {payment_method_id} --customer cus_XXX ``` ### Detach Payment Method ```bash POST /stripe/v1/payment_methods/{payment_method_id}/detach ``` Example: ```bash maton stripe payment-method detach {payment_method_id} ``` --- ## Coupons ### List Coupons ```bash GET /stripe/v1/coupons?limit=10 ``` Example: ```bash maton stripe coupon list -L 10 ``` ### Get Coupon ```bash GET /stripe/v1/coupons/{coupon_id} ``` Example: ```bash maton stripe coupon view {coupon_id} ``` ### Create Coupon ```bash POST /stripe/v1/coupons Content-Type: application/x-www-form-urlencoded percent_off=25&duration=once ``` Example: ```bash maton stripe coupon create --percent-off 25 --duration once ``` ### Delete Coupon ```bash DELETE /stripe/v1/coupons/{coupon_id} ``` Example: ```bash maton stripe coupon delete {coupon_id} ``` --- ## Refunds ### List Refunds ```bash GET /stripe/v1/refunds?limit=10 ``` Example: ```bash maton stripe refund list -L 10 ``` ### Get Refund ```bash GET /stripe/v1/refunds/{refund_id} ``` Example: ```bash maton stripe refund view {refund_id} ``` ### Create Refund ```bash POST /stripe/v1/refunds Content-Type: application/x-www-form-urlencoded charge=ch_XXX&amount=1000 ``` Example: ```bash maton stripe refund create --charge ch_XXX --amount 1000 ``` --- ## Pagination Stripe uses cursor-based pagination with `starting_after` and `ending_before`: ```bash GET /stripe/v1/customers?limit=10&starting_after=cus_XXX ``` Example: ```bash maton stripe customer list -L 10 --starting-after cus_XXX ``` **Response includes:** ```json { "object": "list", "data": [...], "has_more": true, "url": "/v1/customers" } ``` Use the last item's ID as `starting_after` for the next page. ## Code Examples ### JavaScript ```javascript const response = await fetch( 'https://api.maton.ai/stripe/v1/customers?limit=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); console.log(data.data); ``` ### Python ```python import os import requests response = requests.get( 'https://api.maton.ai/stripe/v1/customers', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'limit': 10} ) data = response.json() for customer in data['data']: print(f"{customer['id']}: {customer['email']}") ``` ## Notes - Stripe API uses [REDACTED_SECRET] for POST requests (not JSON) - Amounts are in the smallest currency unit (e.g., cents for USD) - IDs start with prefixes: `cus_` (customers), `prod_` (products), `price_` (prices), `sub_` (subscriptions), `in_` (invoices), `ch_` (charges), `pi_` (payment intents) - Timestamps are Unix timestamps - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets 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 ## Error Handling | Status | Meaning | |--------|---------| | 400 | Bad request or invalid parameters | | 401 | Invalid or missing Maton API key | | 402 | Card declined or payment required | | 404 | Resource not found | | 429 | Rate limited | | 500 | Stripe internal error | ### Troubleshooting: API Key Issues 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://api.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 ``` ### Troubleshooting: Invalid App Name 1. Ensure your URL path starts with `stripe`. For example: - Correct: `https://api.maton.ai/stripe/v1/customers` - Incorrect: `https://api.maton.ai/v1/customers` ## Resources - [Stripe API Reference](https://docs.stripe.com/api) - [Stripe Dashboard](https://dashboard.stripe.com/) - [Stripe Testing](https://docs.stripe.com/testing) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[REDACTED_SECRET])


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)