Introduction
# 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¤cy=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¤cy=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¤cy=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?customer=cus_XXX&type=card ```
### Get Payment Method
```bash GET /stripe/v1/payment_methods/{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 ```
### Detach Payment Method
```bash POST /stripe/v1/payment_methods/{payment_method_id}/detach ```
---
## Coupons
### List Coupons
```bash GET /stripe/v1/coupons?limit=10 ```
### Get Coupon
```bash GET /stripe/v1/coupons/{coupon_id} ```
### Create Coupon
```bash POST /stripe/v1/coupons Content-Type: application/x-www-form-urlencoded
percent_off=25&duration=once ```
### Delete Coupon
```bash DELETE /stripe/v1/coupons/{coupon_id} ```
---
## Refunds
### List Refunds
```bash GET /stripe/v1/refunds?limit=10 ```
### Get Refund
```bash GET /stripe/v1/refunds/{refund_id} ```
### Create Refund
```bash POST /stripe/v1/refunds Content-Type: application/x-www-form-urlencoded
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 ```
**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://gateway.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://gateway.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 `application/x-www-form-urlencoded` 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://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 ```
### Troubleshooting: Invalid App Name
1. Ensure your URL path starts with `stripe`. For example:
- Correct: `https://gateway.maton.ai/stripe/v1/customers` - Incorrect: `https://gateway.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:[email protected])