#api-integration#financial

Stripe

Stripe API integration with managed OAuth. This is a write-capable financial integration for customers, subscriptions, invoices, products, prices, and payments. Install only if you need Stripe administration. Connect with the least-privileged Stripe account and OAuth scopes available, verify the intended connection ID before each request, and revoke unused connections promptly. All write operations require explicit user approval showing the exact endpoint, target resource, object IDs, amounts, and test/live mode before execution. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key.

Install

openclaw skills install @byungkyu/stripe-api

Stripe

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

Quick Start

CLI:

bash

maton stripe customer list -L 5

bash

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

Python:

bash

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

text

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:

bash

npm install -g @maton-ai/cli

Homebrew:

bash

brew install maton-ai/cli/maton

Authentication

CLI:

bash

maton login                          # Opens browser for API key
maton login --interactive            # Skip browser, paste API key directly
maton whoami                         # Show current auth state

Manual:

Sign in or create an account at maton.ai
Go to maton.ai/settings
Copy your API key
Set your API key as MATON_API_KEY:

bash

export MATON_API_KEY="YOUR_API_KEY"

Connection Management

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

List Connections

CLI:

bash

maton connection list stripe --status ACTIVE

bash

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

Python:

bash

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:

bash

maton connection create stripe

bash

maton api /connections -f app=stripe

Python:

bash

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

bash

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:

json

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

bash

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:

bash

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:

text

/stripe/v1/{resource}

Balance

Get Balance

bash

GET /stripe/v1/balance

Example:

bash

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

Example:

bash

maton stripe balance-transaction list -L 10

Customers

List Customers

bash

GET /stripe/v1/customers?limit=10

Example:

bash

maton stripe customer list -L 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": "customer@example.com",
      "name": null,
      "balance": 0,
      "currency": "usd",
      "created": 1770765579,
      "metadata": {}
    }
  ],
  "has_more": true,
  "url": "/v1/customers"
}

Get Customer

bash

GET /stripe/v1/customers/{customer_id}

Example:

bash

maton stripe customer view {customer_id}

Create Customer

bash

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

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

Example:

bash

maton stripe customer create --email customer@example.com --name 'John Doe' --metadata user_id=123

Update Customer

bash

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

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

Example:

bash

maton stripe customer update {customer_id} --name 'Jane Doe' --email jane@example.com

Delete Customer

bash

DELETE /stripe/v1/customers/{customer_id}

Example:

bash

maton stripe customer delete {customer_id}

Products

List Products

bash

GET /stripe/v1/products?limit=10

Example:

bash

maton stripe product list -L 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}

Example:

bash

maton stripe product view {product_id}

Create Product

bash

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

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

Example:

bash

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

Update Product

bash

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

name=Updated%20Plan&active=true

Example:

bash

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

Delete Product

bash

DELETE /stripe/v1/products/{product_id}

Example:

bash

maton stripe product delete {product_id}

Prices

List Prices

bash

GET /stripe/v1/prices?limit=10

Example:

bash

maton stripe price list -L 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}

Example:

bash

maton stripe price view {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

Example:

bash

maton stripe price create --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

Example:

bash

maton stripe price update {price_id} --active false

Subscriptions

List Subscriptions

bash

GET /stripe/v1/subscriptions?limit=10

Example:

bash

maton stripe subscription list -L 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}

Example:

bash

maton stripe subscription view {subscription_id}

Create Subscription

bash

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

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

Example:

bash

maton stripe subscription create --customer cus_XXX --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

Example:

bash

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

Cancel Subscription

bash

DELETE /stripe/v1/subscriptions/{subscription_id}

Example:

bash

maton stripe subscription cancel {subscription_id}

Invoices

List Invoices

bash

GET /stripe/v1/invoices?limit=10

Example:

bash

maton stripe invoice list -L 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}

Example:

bash

maton stripe invoice view {invoice_id}

Create Invoice

bash

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

customer=cus_XXX

Example:

bash

maton stripe invoice create --customer cus_XXX

Finalize Invoice

bash

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

Example:

bash

maton stripe invoice finalize {invoice_id}

Pay Invoice

bash

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

Example:

bash

maton stripe invoice pay {invoice_id}

Void Invoice

bash

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

Example:

bash

maton stripe invoice void {invoice_id}

Charges

List Charges

bash

GET /stripe/v1/charges?limit=10

Example:

bash

maton stripe charge list -L 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}

Example:

bash

maton stripe charge view {charge_id}

Create Charge

bash

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

amount=2000&currency=usd&source=tok_XXX

Example:

bash

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

Payment Intents

List Payment Intents

bash

GET /stripe/v1/payment_intents?limit=10

Example:

bash

maton stripe payment list -L 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}

Example:

bash

maton stripe payment view {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

Example:

bash

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

Confirm Payment Intent

bash

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

Example:

bash

maton stripe payment confirm {payment_intent_id}

Cancel Payment Intent

bash

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

Example:

bash

maton stripe payment cancel {payment_intent_id}

Payment Methods

List Payment Methods

bash

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

Example:

bash

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

Get Payment Method

bash

GET /stripe/v1/payment_methods/{payment_method_id}

Example:

bash

maton stripe payment-method view {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

Example:

bash

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

Detach Payment Method

bash

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

Example:

bash

maton stripe payment-method detach {payment_method_id}

Coupons

List Coupons

bash

GET /stripe/v1/coupons?limit=10

Example:

bash

maton stripe coupon list -L 10

Get Coupon

bash

GET /stripe/v1/coupons/{coupon_id}

Example:

bash

maton stripe coupon view {coupon_id}

Create Coupon

bash

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

percent_off=25&duration=once

Example:

bash

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

Delete Coupon

bash

DELETE /stripe/v1/coupons/{coupon_id}

Example:

bash

maton stripe coupon delete {coupon_id}

Refunds

List Refunds

bash

GET /stripe/v1/refunds?limit=10

Example:

bash

maton stripe refund list -L 10

Get Refund

bash

GET /stripe/v1/refunds/{refund_id}

Example:

bash

maton stripe refund view {refund_id}

Create Refund

bash

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

charge=ch_XXX&amount=1000

Example:

bash

maton stripe refund create --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

Example:

bash

maton stripe customer list -L 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://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

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

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

Check that the MATON_API_KEY environment variable is set:

bash

echo $MATON_API_KEY

Verify the API key is valid by listing connections:

bash

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

Ensure your URL path starts with stripe. For example:

Correct: https://api.maton.ai/stripe/v1/customers
Incorrect: https://api.maton.ai/v1/customers