Stripe Payments

SKILL.md

---
name: stripe-payments
description: Manage customers, payments, invoices, subscriptions, checkout sessions, and payouts in Stripe via the Stripe API. Use this skill when users want to process payments, manage subscriptions, handle refunds, create invoices, or automate financial workflows in Stripe.
---

# Stripe Payments

![Stripe Payments](https://raw.githubusercontent.com/ClawLink-HQ/clawlink/main/public/images/brand-logos/stripe.svg)

Manage Stripe customers, payments, invoices, subscriptions, checkout sessions, and payouts via the Stripe API.

This skill uses [ClawLink](https://claw-link.dev/?utm_source=clawhub&utm_medium=referral&utm_content=clawlink-stripe) for hosted connection flows and credentials so you do not need to configure Stripe API access yourself.

### Setup in 3 Steps

| Step 1: Install | Step 2: Pair Account | Step 3: Connect Stripe |
|:---:|:---:|:---:|
| ![Install](https://raw.githubusercontent.com/ClawLink-HQ/clawlink/main/public/images/pairing/initialstep_1.gif) | ![Pair](https://raw.githubusercontent.com/ClawLink-HQ/clawlink/main/public/images/approve_process.gif) | *App-specific connection GIF coming soon* |
| Run the install command in OpenClaw | Sign in and approve the device | Open the dashboard and connect Stripe |

## How It Works

```
┌─────────────────┐     ┌──────────────┐     ┌──────────────────┐
│   OpenClaw      │────▶│   ClawLink   │────▶│   Stripe API      │
│   (User Chat)   │     │   (OAuth)    │     │                  │
└─────────────────┘     └──────────────┘     └──────────────────┘
         │                       │                       │
         │  1. Install Plugin    │                       │
         │  2. Pair Device       │                       │
         │  3. Connect Stripe    │                       │
         │                       │  4. Secure Token     │
         │                       │  5. Proxy Requests   │
         │                       │                       │
         ▼                       ▼                       ▼
   ┌──────────┐           ┌──────────┐           ┌──────────┐
   │  SKILL   │           │ Dashboard│           │  Stripe  │
   │  File    │           │ Auth     │           │  Account │
   └──────────┘           └──────────┘           └──────────┘
```

## Install

Install the verified ClawLink plugin from ClawHub. After the user confirms, complete the full setup so ClawLink tools are visible in the next OpenClaw chat.

```bash
openclaw plugins install clawhub:clawlink-plugin
openclaw config set tools.alsoAllow '["clawlink-plugin"]' --strict-json
openclaw gateway restart
```

Then tell the user: "OpenClaw has been restarted. Send `/new` as a standalone message to start a fresh chat, then ask for Stripe again."

## Quick Start

```bash
# List customers
clawlink_call_tool --tool "stripe_list_customers" --params '{"limit": 10}'

# Get a payment intent
clawlink_call_tool --tool "stripe_get_payment_intent" --params '{"payment_intent_id": "pi_1234567890"}'

# List subscriptions
clawlink_call_tool --tool "stripe_list_subscriptions" --params '{"limit": 10}'
```

## Authentication

All Stripe tool calls are authenticated automatically by ClawLink using the user's connected Stripe account OAuth token.

**No API key is required in chat.** ClawLink stores the API key securely and injects it into every Stripe API request on the user's behalf.

### Getting Connected

1. Install the ClawLink plugin (see Install above).
2. Pair the plugin with `clawlink_begin_pairing` if it is not configured yet.
3. Open https://claw-link.dev/dashboard?add=stripe and connect Stripe.
4. Call `clawlink_list_integrations` to verify the connection is active.

## Connection Management

### List Connections

```bash
clawlink_list_integrations
```

**Response:** Returns all connected integrations. Look for `stripe` in the list.

### Verify Connection

```bash
clawlink_list_tools --integration stripe
```

**Response:** Returns the live tool catalog for Stripe.

### Reconnect

If Stripe tools are missing or the connection shows an error:

1. Direct the user to https://claw-link.dev/dashboard?add=stripe
2. After they confirm, call `clawlink_list_integrations` to verify
3. Then call `clawlink_list_tools --integration stripe`

## Security & Permissions

- Access is scoped to the Stripe account connected during OAuth setup and the permissions granted.
- **All write operations require explicit user confirmation.** Refunds, cancellations, and chargebacks are high-impact — confirm explicitly.
- Never commit payment amounts or fee calculations from memory — always pull from Stripe.
- Test mode and live mode operate on separate data — confirm which mode is in use.

## Tool Reference

### Customers

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_list_customers` | List customers with pagination and filters | Read |
| `stripe_get_customer` | Get customer details including balance and metadata | Read |
| `stripe_create_customer` | Create a new customer record | Write |
| `stripe_update_customer` | Update customer information or metadata | Write |
| `stripe_delete_customer` | Permanently delete a customer | Write |
| `stripe_create_customer_balance_transaction` | Manually adjust a customer's balance | Write |
| `stripe_create_customer_session` | Create a customer session for portal access | Write |
| `stripe_search_customers` | Search customers by email, name, or metadata | Read |

### Payment Intents & Charges

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_list_payment_intents` | List payment intents with status filters | Read |
| `stripe_get_payment_intent` | Get payment intent details and status | Read |
| `stripe_create_payment_intent` | Create a payment intent to collect payment | Write |
| `stripe_confirm_payment_intent` | Confirm a payment intent and initiate payment | Write |
| `stripe_capture_payment_intent` | Capture funds from an uncaptured payment intent | Write |
| `stripe_cancel_payment_intent` | Cancel an uncaptured payment intent | Write |
| `stripe_get_balance` | Get Stripe account balance | Read |
| `stripe_list_balance_transactions` | List balance transactions | Read |
| `stripe_create_charge` | Create a direct charge | Write |
| `stripe_capture_charge` | Capture an uncaptured charge | Write |
| `stripe_create_refund` | Create a full or partial refund | Write |

### Subscriptions

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_list_subscriptions` | List active and past subscriptions | Read |
| `stripe_get_subscription` | Get subscription details and schedule | Read |
| `stripe_create_subscription` | Create a subscription for a customer | Write |
| `stripe_update_subscription` | Update a subscription's plan, quantity, or status | Write |
| `stripe_cancel_subscription` | Cancel a subscription (at period end or immediately) | Write |
| `stripe_pause_subscription` | Pause an active subscription | Write |
| `stripe_resume_subscription` | Resume a paused subscription | Write |
| `stripe_list_subscription_items` | List items on a subscription | Read |
| `stripe_create_subscription_item` | Add an item to an existing subscription | Write |
| `stripe_delete_subscription_item` | Remove an item from a subscription | Write |

### Invoices

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_list_invoices` | List invoices with status and customer filters | Read |
| `stripe_get_invoice` | Get invoice details including line items | Read |
| `stripe_create_invoice` | Create a new draft invoice | Write |
| `stripe_finalize_invoice` | Finalize a draft invoice for sending | Write |
| `stripe_send_invoice` | Send a finalized invoice to the customer | Write |
| `stripe_void_invoice` | Void an invoice | Write |
| `stripe_delete_invoice` | Permanently delete a draft invoice | Write |
| `stripe_create_preview_invoice` | Preview an upcoming invoice | Read |
| `stripe_add_invoice_lines` | Add line items to a draft invoice | Write |
| `stripe_create_invoice_item` | Add a charge or credit to a customer | Write |
| `stripe_list_invoice_items` | List invoice items for a customer | Read |
| `stripe_create_credit_note` | Create a credit note for an invoice | Write |

### Checkout Sessions

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_create_checkout_session` | Create a hosted checkout page | Write |
| `stripe_get_checkout_session` | Get checkout session details | Read |
| `stripe_expire_checkout_session` | Expire an unfinished checkout session | Write |

### Products & Pricing

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_list_products` | List all products | Read |
| `stripe_get_product` | Get product details | Read |
| `stripe_create_product` | Create a new product | Write |
| `stripe_update_product` | Update a product's metadata or status | Write |
| `stripe_delete_product` | Archive a product | Write |
| `stripe_create_price` | Create a price for a product | Write |
| `stripe_list_prices` | List prices for a product | Read |

### Coupons & Discounts

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_create_coupon` | Create a discount coupon | Write |
| `stripe_list_coupons` | List all coupons | Read |
| `stripe_delete_coupon` | Permanently delete a coupon | Write |
| `stripe_create_promotion_code` | Create a customer-redeemable code | Write |

### Billing Portal

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_create_billing_portal_session` | Create a customer portal session | Write |
| `stripe_create_billing_portal_configuration` | Configure the billing portal | Write |

### Disputes & Fraud

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_list_disputes` | List chargebacks and disputes | Read |
| `stripe_get_dispute` | Get dispute details | Read |
| `stripe_close_dispute` | Accept and close a dispute | Write |

### Payouts

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_list_payouts` | List payouts to the bank account | Read |
| `stripe_get_payout` | Get payout details and status | Read |
| `stripe_create_payout` | Create a payout to the bank account | Write |
| `stripe_cancel_payout` | Cancel a pending payout | Write |

### Payment Methods

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_list_payment_methods` | List payment methods attached to a customer | Read |
| `stripe_attach_payment_method` | Attach a payment method to a customer | Write |
| `stripe_detach_payment_method` | Remove a payment method from a customer | Write |
| `stripe_create_payment_method` | Create a payment method from card details | Write |

### Setup Intents

| Tool | Description | Mode |
|------|-------------|------|
| `stripe_create_setup_intent` | Create a setup intent for saving payment details | Write |
| `stripe_confirm_setup_intent` | Confirm a setup intent | Write |
| `stripe_cancel_setup_intent` | Cancel a setup intent | Write |

## Code Examples

### List recent customers

```bash
clawlink_call_tool --tool "stripe_list_customers" \
  --params '{
    "limit": 10,
    "email": "example.com"
  }'
```

### Create a payment intent

```bash
clawlink_call_tool --tool "stripe_create_payment_intent" \
  --params '{
    "amount": 5000,
    "currency": "usd",
    "customer": "cus_1234567890",
    "description": "Order #12345"
  }'
```

### Create a customer

```bash
clawlink_call_tool --tool "stripe_create_customer" \
  --params '{
    "email": "customer@example.com",
    "name": "Jane Doe",
    "metadata": {
      "internal_id": "CUST-001"
    }
  }'
```

### Create a checkout session

```bash
clawlink_call_tool --tool "stripe_create_checkout_session" \
  --params '{
    "mode": "subscription",
    "line_items": [
      {
        "price": "price_1234567890",
        "quantity": 1
      }
    ],
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'
```

### Create a refund

```bash
clawlink_call_tool --tool "stripe_create_refund" \
  --params '{
    "charge": "ch_1234567890",
    "amount": 2500
  }'
```

### Create a subscription

```bash
clawlink_call_tool --tool "stripe_create_subscription" \
  --params '{
    "customer": "cus_1234567890",
    "items": [
      {
        "price": "price_1234567890"
      }
    ],
    "payment_behavior": "default_incomplete"
  }'
```

## Discovery Workflow

1. Call `clawlink_list_integrations` to confirm Stripe is connected.
2. Call `clawlink_list_tools --integration stripe` to see the live catalog.
3. Treat the returned list as the source of truth. Do not guess or assume what tools exist.
4. If the user describes a capability but the exact tool is unclear, call `clawlink_search_tools` with a short query and integration `stripe`.
5. If no Stripe tools appear, direct the user to https://claw-link.dev/dashboard?add=stripe.

## Execution Workflow

```
┌─────────────────────────────────────────────────────────────┐
│  READ OPERATIONS (Safe)                                     │
│  list → get → search → describe                            │
│                                                             │
│  Example: List customers → Get customer → Show details    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  WRITE OPERATIONS (Require Confirmation)                    │
│  describe → preview → confirm → call                      │
│                                                             │
│  Example: Preview refund → User approves → Process refund   │
└─────────────────────────────────────────────────────────────┘
```

1. For unfamiliar tools, ambiguous requests, or any write action, call `clawlink_describe_tool` first.
2. Use the returned guidance, schema, `whenToUse`, `askBefore`, `safeDefaults`, `examples`, and `followups` to shape the call.
3. Prefer read, list, get, and search operations before writes when that reduces ambiguity.
4. For writes or anything marked as requiring confirmation, call `clawlink_preview_tool` first.
5. Execute with `clawlink_call_tool`. Pass confirmation only after the preview matches the user's intent.
6. If the tool call fails, report the real error. Do not invent results or restate the failure as a missing capability unless the live catalog supports that conclusion.

## Notes

- All monetary amounts in Stripe are in the smallest currency unit (cents for USD).
- Payment intents must be confirmed before processing — check the status after creation.
- Subscriptions can have multiple items (prices) — always specify the price ID, not just the product ID.
- Refunds can only be processed on captured charges — uncaptured charges must be cancelled instead.
- Dispute/chargeback responses must be submitted through the Stripe dashboard, not the API.
- Test mode and live mode are completely separate — confirm which environment is in use.

## Error Handling

| Status / Error | Meaning |
|----------------|---------|
| Tool not found | The tool name does not exist in the current catalog. Verify with `clawlink_list_tools --integration stripe`. |
| Missing connection | Stripe is not connected. Direct the user to https://claw-link.dev/dashboard?add=stripe. |
| `customer_not_found` | The customer ID does not exist in the account. |
| `payment_intent_not_found` | The payment intent ID is invalid or was deleted. |
| `charge_not_found` | The charge ID is invalid. |
| `subscription_not_found` | The subscription ID does not exist. |
| `idempotency_conflict` | A request with the same idempotency key was recently made. |
| `card_declined` | The card was declined by the issuer. |
| `insufficient_funds` | The customer's balance is insufficient for the operation. |
| `already_refunded` | The charge has already been fully refunded. |
| Write rejected | User did not confirm a write action. Always confirm before executing writes. |

### Troubleshooting: Tools Not Visible

1. Check that the ClawLink plugin is installed:
   ```bash
   openclaw plugins list
   ```
2. If the plugin is installed but tools are missing, tell the user to send `/new` as a standalone message to reload the catalog.
3. If a fresh chat does not help, run:
   ```bash
   openclaw config set tools.alsoAllow '["clawlink-plugin"]' --strict-json
   openclaw gateway restart
   ```
4. After restart, tell the user to send `/new` again and retry.

### Troubleshooting: Payment Fails

1. Verify the customer exists and has valid payment methods attached.
2. Check the PaymentIntent status — some require additional confirmation steps.
3. Confirm the amount is in the smallest currency unit (cents), not dollars.
4. Ensure the currency matches the payment method type.

## Resources

- [Stripe API Documentation](https://stripe.com/docs/api)
- [Stripe REST API Reference](https://stripe.com/docs/api/charges)
- [Stripe Payment Intents](https://stripe.com/docs/payments/payment-intents)
- [Stripe Subscriptions](https://stripe.com/docs/billing/subscriptions)
- ClawLink: https://claw-link.dev/?utm_source=clawhub&utm_medium=referral&utm_content=clawlink-stripe
- ClawLink Docs: https://docs.claw-link.dev/openclaw
- ClawLink Verification: https://claw-link.dev/verify

---

**Powered by [ClawLink](https://claw-link.dev/?utm_source=clawhub&utm_medium=referral&utm_content=clawlink-stripe)** — an integration hub for OpenClaw

![ClawLink Logo](https://raw.githubusercontent.com/ClawLink-HQ/clawlink/main/public/images/logo/link_logo_black_small.png)