Stripe

Stripe

Access the Stripe API with managed OAuth authentication. Manage customers, subscriptions, invoices, products, prices, and process payments.

Quick Start

CLI:

maton stripe customer list -L 5

maton api '/stripe/v1/customers?limit=5'

Python:

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:

npm install -g @maton/cli

Homebrew:

brew install maton-ai/cli/maton

Authentication

CLI:

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
2. Go to maton.ai/settings
3. Copy your API key
4. Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Connection Management

Manage your Stripe OAuth connections at https://api.maton.ai.

List Connections

CLI:

maton connection list stripe --status ACTIVE

maton api -X GET /connections -f app=stripe -f status=ACTIVE

Python:

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:

maton connection create stripe

maton api /connections -f app=stripe

Python:

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

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:

{
  "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

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:

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

GET /stripe/v1/balance

Example:

maton stripe balance

Response:

{
  "object": "balance",
  "available": [
    {
      "amount": 0,
      "currency": "usd",
      "source_types": {"card": 0}
    }
  ],
  "pending": [
    {
      "amount": 5000,
      "currency": "usd",
      "source_types": {"card": 5000}
    }
  ]
}

List Balance Transactions

GET /stripe/v1/balance_transactions?limit=10

Example:

maton stripe balance-transaction list -L 10

---

Customers

List Customers

GET /stripe/v1/customers?limit=10

Example:

maton stripe customer list -L 10

Query Parameters:

Response:

{
  "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

GET /stripe/v1/customers/{customer_id}

Example:

maton stripe customer view {customer_id}

Create Customer

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

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

Example:

maton stripe customer create --email [email protected] --name 'John Doe' --metadata user_id=123

Update Customer

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

name=Jane%20Doe&[email protected]

Example:

maton stripe customer update {customer_id} --name 'Jane Doe' --email [email protected]

Delete Customer

DELETE /stripe/v1/customers/{customer_id}

Example:

maton stripe customer delete {customer_id}

---

Products

List Products

GET /stripe/v1/products?limit=10

Example:

maton stripe product list -L 10

Query Parameters:

Response:

{
  "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

GET /stripe/v1/products/{product_id}

Example:

maton stripe product view {product_id}

Create Product

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

name=Premium%20Plan&description=Premium%20subscription

Example:

maton stripe product create --name 'Premium Plan' --description 'Premium subscription'

Update Product

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

name=Updated%20Plan&active=true

Example:

maton stripe product update {product_id} --name 'Updated Plan' --active true

Delete Product

DELETE /stripe/v1/products/{product_id}

Example:

maton stripe product delete {product_id}

---

Prices

List Prices

GET /stripe/v1/prices?limit=10

Example:

maton stripe price list -L 10

Query Parameters:

Response:

{
  "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

GET /stripe/v1/prices/{price_id}

Example:

maton stripe price view {price_id}

Create Price

POST /stripe/v1/prices
Content-Type: application/x-www-form-urlencoded

product=prod_XXX&unit_amount=1999&currency=usd&recurring[interval]=month

Example:

maton stripe price create --product prod_XXX --unit-amount 1999 --currency usd --recurring-interval month

Update Price

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

active=false

Example:

maton stripe price update {price_id} --active false

---

Subscriptions

List Subscriptions

GET /stripe/v1/subscriptions?limit=10

Example:

maton stripe subscription list -L 10

Query Parameters:

Response:

{
  "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

GET /stripe/v1/subscriptions/{subscription_id}

Example:

maton stripe subscription view {subscription_id}

Create Subscription

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

customer=cus_XXX&items[0][price]=price_XXX

Example:

maton stripe subscription create --customer cus_XXX --price price_XXX

Update Subscription

POST /stripe/v1/subscriptions/{subscription_id}
Content-Type: application/x-www-form-urlencoded

items[0][id]=si_XXX&items[0][price]=price_YYY

Example:

maton stripe subscription update {subscription_id} --items 'id=si_XXX,price=price_YYY'

Cancel Subscription

DELETE /stripe/v1/subscriptions/{subscription_id}

Example:

maton stripe subscription cancel {subscription_id}

---

Invoices

List Invoices

GET /stripe/v1/invoices?limit=10

Example:

maton stripe invoice list -L 10

Query Parameters:

Response:

{
  "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

GET /stripe/v1/invoices/{invoice_id}

Example:

maton stripe invoice view {invoice_id}

Create Invoice

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

customer=cus_XXX

Example:

maton stripe invoice create --customer cus_XXX

Finalize Invoice

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

Example:

maton stripe invoice finalize {invoice_id}

Pay Invoice

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

Example:

maton stripe invoice pay {invoice_id}

Void Invoice

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

Example:

maton stripe invoice void {invoice_id}

---

Charges

List Charges

GET /stripe/v1/charges?limit=10

Example:

maton stripe charge list -L 10

Query Parameters:

Response:

{
  "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

GET /stripe/v1/charges/{charge_id}

Example:

maton stripe charge view {charge_id}

Create Charge

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

amount=2000&currency=usd&source=tok_XXX

Example:

maton stripe charge create --amount 2000 --currency usd --source tok_XXX

---

Payment Intents

List Payment Intents

GET /stripe/v1/payment_intents?limit=10

Example:

maton stripe payment list -L 10

Response:

{
  "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

GET /stripe/v1/payment_intents/{payment_intent_id}

Example:

maton stripe payment view {payment_intent_id}

Create Payment Intent

POST /stripe/v1/payment_intents
Content-Type: application/x-www-form-urlencoded

amount=2000&currency=usd&customer=cus_XXX&payment_method_types[]=card

Example:

maton stripe payment create --amount 2000 --currency usd --customer cus_XXX --payment-method-types card

Confirm Payment Intent

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

Example:

maton stripe payment confirm {payment_intent_id}

Cancel Payment Intent

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

Example:

maton stripe payment cancel {payment_intent_id}

---

Payment Methods

List Payment Methods

GET /stripe/v1/payment_methods?customer=cus_XXX&type=card

Example:

maton stripe payment-method list --customer cus_XXX --type card

Get Payment Method

GET /stripe/v1/payment_methods/{payment_method_id}

Example:

maton stripe payment-method view {payment_method_id}

Attach Payment Method

POST /stripe/v1/payment_methods/{payment_method_id}/attach
Content-Type: application/x-www-form-urlencoded

customer=cus_XXX

Example:

maton stripe payment-method attach {payment_method_id} --customer cus_XXX

Detach Payment Method

POST /stripe/v1/payment_methods/{payment_method_id}/detach

Example:

maton stripe payment-method detach {payment_method_id}

---

Coupons

List Coupons

GET /stripe/v1/coupons?limit=10

Example:

maton stripe coupon list -L 10

Get Coupon

GET /stripe/v1/coupons/{coupon_id}

Example:

maton stripe coupon view {coupon_id}

Create Coupon

POST /stripe/v1/coupons
Content-Type: application/x-www-form-urlencoded

percent_off=25&duration=once

Example:

maton stripe coupon create --percent-off 25 --duration once

Delete Coupon

DELETE /stripe/v1/coupons/{coupon_id}

Example:

maton stripe coupon delete {coupon_id}

---

Refunds

List Refunds

GET /stripe/v1/refunds?limit=10

Example:

maton stripe refund list -L 10

Get Refund

GET /stripe/v1/refunds/{refund_id}

Example:

maton stripe refund view {refund_id}

Create Refund

POST /stripe/v1/refunds
Content-Type: application/x-www-form-urlencoded

charge=ch_XXX&amount=1000

Example:

maton stripe refund create --charge ch_XXX --amount 1000

---

Pagination

Stripe uses cursor-based pagination with starting_after and ending_before:

GET /stripe/v1/customers?limit=10&starting_after=cus_XXX

Example:

maton stripe customer list -L 10 --starting-after cus_XXX

Response includes:

{
  "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

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

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

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

1. Verify the API key is valid by listing connections:

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
• Stripe Dashboard
• Stripe Testing
• Maton Community
• Maton Support