Stripe

The @tooly/stripe package provides AI-ready tools for Stripe payment processing. Handle customers, payments, and invoices with AI assistance to streamline your billing operations.

Installation

npm install @tooly/stripe

Quick Start

import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { createAITools } from '@tooly/stripe'

const tools = createAITools(process.env.STRIPE_SECRET_KEY!)

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Create a customer for John Doe and process a $25 payment',
    },
  ],
  tools,
})

console.log(result.text)

Setup

1. Get Your Stripe API Keys

Go to Stripe Dashboard
Create a new secret API key
Copy the key for use in your application

2. Environment Variables

Store your API key securely:

STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key_here

3. Initialize the Tools

import { createAITools } from '@tooly/stripe'

const tools = createAITools(process.env.STRIPE_SECRET_KEY!)

Available Tools

The Stripe package provides the following AI tools:

createCustomer

Creates a new customer in Stripe with the specified details.

Parameters:

email (string, optional): Customer's email address
name (string, optional): Customer's full name or business name
phone (string, optional): Customer's phone number
description (string, optional): An arbitrary description for the customer
address (object, optional): Customer's address information
metadata (object, optional): Set of key-value pairs for storing additional information

Example:

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Create a customer for Jane Smith with email jane@example.com',
    },
  ],
  tools,
})

getCustomer

Retrieves an existing customer from Stripe.

Parameters:

id (string, required): ID of the customer to retrieve

Example:

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Get details for customer cus_1234567890',
    },
  ],
  tools,
})

listCustomers

Lists customers in Stripe with optional filtering.

Parameters:

limit (number, optional): Number of customers to return (1-100, default 10)
starting_after (string, optional): Customer ID for pagination cursor
ending_before (string, optional): Customer ID for pagination cursor
email (string, optional): Filter customers by email address

Example:

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Show me the first 20 customers',
    },
  ],
  tools,
})

createPaymentIntent

Creates a payment intent to process a payment.

Parameters:

amount (number, required): Amount in smallest currency unit (e.g., cents for USD)
currency (string, optional): Three-letter ISO currency code (default: 'usd')
customer (string, optional): ID of the customer this payment is for
payment_method (string, optional): ID of the payment method to use
description (string, optional): Description of the payment
receipt_email (string, optional): Email address to send receipt to
metadata (object, optional): Additional information to store
automatic_payment_methods (object, optional): Configuration for automatic payment methods

Example:

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Create a $50 payment intent for customer cus_1234567890',
    },
  ],
  tools,
})

getPaymentIntent

Retrieves details of a payment intent.

Parameters:

id (string, required): ID of the payment intent to retrieve

Example:

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Get status of payment intent pi_1234567890',
    },
  ],
  tools,
})

createInvoice

Creates an invoice for a customer.

Parameters:

customer (string, required): ID of the customer to invoice
description (string, optional): Description for the invoice
metadata (object, optional): Additional information to store
auto_advance (boolean, optional): Whether to automatically finalize the invoice (default: true)

Example:

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Create an invoice for customer cus_1234567890 for consulting services',
    },
  ],
  tools,
})

getInvoice

Retrieves details of an invoice.

Parameters:

id (string, required): ID of the invoice to retrieve

Example:

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Get details of invoice in_1234567890',
    },
  ],
  tools,
})

Advanced Usage

OpenAI Integration

import OpenAI from 'openai'
import { createOpenAIFunctions } from '@tooly/stripe'

const openai = new OpenAI()
const { functions, callHandler } = createOpenAIFunctions(process.env.STRIPE_SECRET_KEY!)

const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Create a customer and process payment' }],
  functions,
})

// Handle function calls
for (const choice of response.choices) {
  if (choice.message.function_call) {
    const result = await callHandler(choice.message.function_call)
    console.log(result)
  }
}

Anthropic Integration

import Anthropic from '@anthropic-ai/sdk'
import { createAnthropicTools } from '@tooly/stripe'

const anthropic = new Anthropic()
const { tools, callHandler } = createAnthropicTools(process.env.STRIPE_SECRET_KEY!)

const response = await anthropic.messages.create({
  model: 'claude-3-sonnet-20240229',
  max_tokens: 1000,
  messages: [{ role: 'user', content: 'Help me process a payment' }],
  tools,
})

// Handle tool calls in the response
for (const content of response.content) {
  if (content.type === 'tool_use') {
    const result = await callHandler(content)
    console.log(result)
  }
}

Direct Usage

import { StripeTools } from '@tooly/stripe'

const stripe = new StripeTools(process.env.STRIPE_SECRET_KEY!)

// Create a customer
const customer = await stripe.execute('createCustomer', {
  email: 'john@example.com',
  name: 'John Doe',
})

// Create a payment intent
const paymentIntent = await stripe.execute('createPaymentIntent', {
  amount: 2500, // $25.00 in cents
  currency: 'usd',
  customer: customer.id,
  description: 'Subscription payment',
})

console.log('Payment Intent:', paymentIntent)

Error Handling

All Stripe tools include comprehensive error handling:

try {
  const result = await generateText({
    model: openai('gpt-4.1-nano'),
    messages: [
      {
        role: 'user',
        content: 'Create a payment intent with invalid data',
      },
    ],
    tools,
  })
} catch (error) {
  console.error('Stripe operation failed:', error.message)
}

Security Best Practices

Use Test Keys in Development: Always use test keys (sk_test_...) during development
Secure API Keys: Never expose secret keys in client-side code or version control
Environment Variables: Store API keys in environment variables
Webhook Validation: When using webhooks, always validate the webhook signature

Common Use Cases

E-commerce Checkout

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Process checkout for John Doe (john@example.com) for $99.99 product purchase',
    },
  ],
  tools,
})

Subscription Billing

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Create monthly subscription invoice for customer cus_1234567890',
    },
  ],
  tools,
})

Customer Management

const result = await generateText({
  model: openai('gpt-4.1-nano'),
  messages: [
    {
      role: 'user',
      content: 'Find all customers with email domain @company.com and show their payment history',
    },
  ],
  tools,
})

Troubleshooting

API Key Issues

If you encounter authentication errors:

Verify your API key is correct
Ensure you're using the right key for your environment (test vs live)
Check that the key has necessary permissions

Rate Limiting

Stripe has rate limits. If you hit them:

Implement exponential backoff
Consider caching frequently accessed data
Monitor your API usage in the Stripe Dashboard

Webhook Configuration

For real-time updates:

Set up webhook endpoints in your Stripe Dashboard
Configure endpoint URLs to receive events
Verify webhook signatures for security

On this page