Stripe

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

---

## Subscriptions

### List Subscriptions

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

### Create Subscription

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

customer=cus_XXX&items[0][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
```

### Cancel Subscription

```bash
DELETE /stripe/v1/subscriptions/{subscription_id}
```

---

## Invoices

### List Invoices

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

### Create Invoice

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

customer=cus_XXX
```

### Finalize Invoice

```bash
POST /stripe/v1/invoices/{invoice_id}/finalize
```

### Pay Invoice

```bash
POST /stripe/v1/invoices/{invoice_id}/pay
```

### Void Invoice

```bash
POST /stripe/v1/invoices/{invoice_id}/void
```

---

## Charges

### List Charges

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

### Create Charge

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

amount=2000&currency=usd&source=tok_XXX
```

---

## Payment Intents

### List Payment Intents

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

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

### Confirm Payment Intent

```bash
POST /stripe/v1/payment_intents/{payment_intent_id}/confirm
```

### Cancel Payment Intent

```bash
POST /stripe/v1/payment_intents/{payment_intent_id}/cancel
```

---

## Payment Methods

### List Payment Methods

```bash
GET /stripe/v1/payment_methods?cu

[Truncated for public library preview]