Stripe

---
name: stripe
description: |
  Stripe API integration with managed OAuth. Manage customers, subscriptions, invoices, products, prices, and payments.
  Use this skill when users want to process payments, manage billing, or handle subscriptions with Stripe.
  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

```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 OAuth token.

## 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 OAuth 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": "c3c82a73-4c86-4c73-8ebd-1f325212fde6",
    "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://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', 'c3c82a73-4c86-4c73-8ebd-1f325212fde6')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

All Stripe API endpoints follow this pattern:

```
/stripe/v1/{resource}
```

---

## Balance

### Get Balance

```bash
GET /stripe/v1/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
```

---

## Customers

### List Customers

```bash
GET /stripe/v1/customers?limit=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": "[email protected]",
      "name": null,
      "balance": 0,
      "currency": "usd",
      "created": 1770765579,
      "metadata": {}
    }
  ],
  "has_more": true,
  "url": "/v1/customers"
}
```

### Get Customer

```bash
GET /stripe/v1/customers/{customer_id}
```

### Create Customer

```bash
POST /stripe/v1/customers
Content-Type: application/x-www-form-urlencoded

[email protected]&name=John%20Doe&metadata[user_id]=123
```

### Update Customer

```bash
POST /stripe/v1/customers/{customer_id}
Content-Type: application/x-www-form-urlencoded

name=Jane%20Doe&[email protected]
```

### Delete Customer

```bash
DELETE /stripe/v1/customers/{customer_id}
```

---

## Products

### List Products

```bash
GET /stripe/v1/products?limit=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}
```

### Create Product

```bash
POST /stripe/v1/products
Content-Type: application/x-www-form-urlencoded

name=Premium%20Plan&description=Premium%20subscription&type=service
```

### Update Product

```bash
POST /stripe/v1/products/{product_id}
Content-Type: application/x-www-form-urlencoded

name=Updated%20Plan&active=true
```

### Delete Product

```bash
DELETE /stripe/v1/products/{product_id}
```

---

## Prices

### List Prices

```bash
GET /stripe/v1/prices?limit=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}
```

### 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
```

### Update Price

```bash
POST /stripe/v1/prices/{price_id}
Content-Type: application/x-www-form-urlencoded

active=false
```

---