stripe-api（Stripe API 文档）

Stripe

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

Quick Start

# List customers
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.

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:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

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

List Connections

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

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

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

Customers

List Customers

GET /stripe/v1/customers?limit=10

Query Parameters:

Response:

{
  "object": "list",
  "data": [
    {
      "id": "cus_TxKtN8Irvzx9BQ",
      "object": "customer",
      "email": "customer@example.com",
      "name": null,
      "balance": 0,
      "currency": "usd",
      "created": 1770765579,
      "metadata": {}
    }
  ],
  "has_more": true,
  "url": "/v1/customers"
}

Get Customer

GET /stripe/v1/customers/{customer_id}

Create Customer

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

email=customer@example.com&name=John%20Doe&metadata[user_id]=123

Update Customer

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

name=Jane%20Doe&email=jane@example.com

Delete Customer

DELETE /stripe/v1/customers/{customer_id}

Products

List Products

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

Create Product

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

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

Update Product

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

name=Updated%20Plan&active=true

Delete Product

DELETE /stripe/v1/products/{product_id}

Prices

List Prices

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

Create Price

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

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

Subscriptions

List Subscriptions

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

Create Subscription

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

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

Cancel Subscription

DELETE /stripe/v1/subscriptions/{subscription_id}

Invoices

List Invoices

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

Create Invoice

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

customer=cus_XXX

Finalize Invoice

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

Pay Invoice

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

Void Invoice

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

Charges

List Charges

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

Create Charge

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

amount=2000&currency=usd&source=tok_XXX

Payment Intents

List Payment Intents

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

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

Confirm Payment Intent

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

Cancel Payment Intent

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

Payment Methods

List Payment Methods

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

Get Payment Method

GET /stripe/v1/payment_methods/{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

Detach Payment Method

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

Coupons

List Coupons

GET /stripe/v1/coupons?limit=10

Get Coupon

GET /stripe/v1/coupons/{coupon_id}

Create Coupon

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

percent_off=25&duration=once

Delete Coupon

DELETE /stripe/v1/coupons/{coupon_id}

Refunds

List Refunds

GET /stripe/v1/refunds?limit=10

Get Refund

GET /stripe/v1/refunds/{refund_id}

Create Refund

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:

GET /stripe/v1/customers?limit=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