Stripe

​
Stripe

Stripe powers online and in-person payment processing and financial solutions for businesses of all sizes.

​
Overview

Stripe is a comprehensive payments platform that handles everything from payment processing to financial reporting. This guide will walk you through connecting your Hypermode agent to Stripe, enabling automated payment operations, customer management, and financial data analysis.

​
Prerequisites

Before connecting Stripe to Hypermode, you’ll need:
  1. A Stripe account (individual or business)
  2. Stripe API credentials (publishable and secret keys)
  3. A Hypermode workspace

​
Setting up Stripe

​
Create your Stripe account

If you haven’t already, sign up for a Stripe account. You can start with a test account to experiment safely.

​
Access your API keys

Navigate to your Stripe dashboard to find your API credentials:
  1. Go to Developers → API keys in your Stripe dashboard
  2. You’ll see both test and live API keys
  3. Start with test keys for development
Stripe API keys
Stripe provides separate test and live environments. Always start with test keys during development to avoid processing real payments accidentally.
For enhanced security, create a restricted API token with only the permissions your agent needs:
  1. Go to Developers → API keys
  2. Click Create restricted key
  3. Select specific permissions based on your use case
Create restricted key Recommended permissions for most agents:
  • Customers: Read and Write
  • Payment Intents: Read and Write
  • Charges: Read
  • Invoices: Read and Write
  • Products: Read and Write
  • Subscriptions: Read and Write
Only grant the minimum permissions your agent actually needs. This follows the principle of least privilege and enhances security.

​
Creating your Stripe agent

Create new agent

​
Create a new agent

From the Hypermode Agents console, create a new agent:
  1. Click the Create new Agent button from the agents view or select Create new >> Create new agent from the threads view.
  2. Enter a name for your agent.
  3. Click the Create Agent button.
Create new agent modal

​
Agent profile

You can view and edit agent details in the agent profile. The agent profile includes the agent name, description, and instructions. You can also view your threads with this agent as well as manage the agent’s tasks and knowledge. Agent profile

​
Agent instructions

You can edit the agent instructions in the agent profile. Editing the agent’s instructions is useful for personalizing your agent and customizing how your agent will work with you and your team. Create agent modal

​
Connecting to Stripe

​
Add the Stripe connection

Select the Agents tab in the left navigation bar, then click your StripeSleuth agent. Select the “Connections” tab.
  1. Select the Connection tab
  2. Select “Connect” next to Stripe in the list of available connections
Add Stripe connection

​
Configure credentials

Enter your Stripe credentials:
  • API Key: Your Stripe secret key (starts with sk_test_ for test mode or sk_live_ for live mode)
Stripe connection modal
Keep your secret API key secure! This key provides full access to your Stripe account and should never be exposed in client-side code or shared publicly.We recommend using a Stripe Sandbox environment for development and testing.

​
Create a new thread with your agent

Create agent thread From the threads view, select “Create new” then select your “Stripe Sleuth” agent from the list of agents.

​
Test basic connectivity

Start a new thread and test the connection with a simple query: 
Can you check my Stripe account balance?
You should see a Stripe tool call in the chat history, confirming the connection works: Test connection

​
Test permissions

Verify your API key has the necessary permissions: 
Can you list my recent customers and products?
If you see permission errors, you may need to update your API key permissions or use a different key. Test permissions

​
Setting up your Stripe environment

Unlike databases, Stripe doesn’t require schema setup. However, you’ll want to configure products, pricing, and webhook endpoints for a complete integration.

​
Create test products

Set up some test products to work with: 
Can you create a test product called "Premium Subscription" with a monthly price of $29.99?

​
Update agent instructions

Enhance your agent’s understanding by updating its instructions with your business context: 
You are connected to a Stripe account for [Your Business Name]. Our main products include:

1. **Premium Subscription** - $29.99/month recurring
2. **Basic Plan** - $9.99/month recurring
3. **One-time Setup** - $99 one-time payment

When processing payments, always:
- Verify customer information
- Use appropriate product IDs
- Handle errors gracefully
- Provide clear confirmation messages

For subscription management, monitor for failed payments and proactively communicate with customers about billing issues.

​
Testing payment operations

​
Test 1: Create a customer

Test customer creation capability: 
Can you create a new customer with email bob.loblaw@example.com and name "Bob Loblaw"?
Create customer

​
Test 2: Process a test payment

Try processing a payment using Stripe’s test card numbers: 
Can you create a payment intent for $50 for customer bob.loblaw@example.com?
In test mode, use Stripe’s test card numbers like 4242424242424242 for successful payments or 4000000000000002 for declined cards.
Process payment

​
Test 3: Handle subscriptions

Test subscription management: 
Can you create a monthly subscription for Bob Loblaw using the Premium Subscription product?
Create subscription

​
What you can do

With your Stripe connection established, your agent can:
  • Process payments with various payment methods
  • Manage customers and their payment information
  • Handle subscriptions including creation, updates, and cancellations
  • Process refunds and handle disputes
  • Generate invoices and manage billing
  • Analyze financial data and generate reports
  • Manage products and pricing dynamically
  • Integrate with other tools like CRM systems, email marketing, and accounting software

​
Best practices

  1. Security first: Always use restricted API keys with minimal required permissions
  2. Test thoroughly: Use Stripe’s test environment before going live
  3. Error handling: Implement robust error handling for payment failures
  4. Compliance: Ensure PCI compliance and follow data protection regulations
  5. Monitoring: Set up alerts for failed payments and unusual activity

​
Advanced operations

​
Payment processing workflows

Your agent can handle complex payment scenarios: 
Process a payment for a customer, and if it fails, try their backup payment method, then send them an email notification

​
Subscription management

Automate subscription lifecycle management: 
Check for subscriptions that failed payment in the last 24 hours and send dunning emails to those customers

​
Financial reporting

Generate comprehensive financial reports: 
Create a monthly revenue report showing breakdown by product, including refunds and net revenue

​
Dispute handling

Manage chargebacks and disputes: 
List all open disputes and provide evidence suggestions for each case

​
Integration examples

​
E-commerce automation

When a customer places an order, create a payment intent, and if successful, fulfill the order and send a confirmation email

​
SaaS billing management

Monitor subscription statuses and automatically downgrade accounts when payments fail after the grace period

​
Troubleshooting

​
Common connection issues

  1. Invalid API key: Verify your key is correct and has proper permissions
  2. Test vs Live mode: Ensure your API key matches the intended environment
  3. Rate limiting: Stripe has rate limits; your agent will handle these automatically
  4. Insufficient permissions: Update your restricted key permissions as needed

​
Payment failures

  1. Declined cards: Use appropriate test card numbers in test mode
  2. Authentication required: Handle 3D Secure authentication flows
  3. Insufficient funds: Test with appropriate test card numbers
  4. Invalid parameters: Verify all required fields are provided correctly

​
Webhook issues

  1. Endpoint verification: Ensure your webhook endpoint is accessible
  2. Event handling: Verify you’re listening for the correct event types
  3. Signature verification: Implement proper webhook signature verification

​
Security considerations

Never expose your Stripe secret keys in client-side code, logs, or public repositories. Always use environment variables or secure key management systems.
  1. API key rotation: Regularly rotate your API keys
  2. Webhook signatures: Always verify webhook signatures to ensure authenticity
  3. PCI compliance: Follow PCI requirements when handling card data
  4. Audit logs: Monitor your Stripe dashboard for unusual activity
  5. Two-factor authentication: Enable 2FA on your Stripe account

​
Learn more

Combine Stripe with other Hypermode connections to create powerful business workflows. For example, use Slack to notify your team of large payments, GitHub to track payment-related code changes, or your CRM to update customer information after successful payments.

​
Compliance and regulations

​
PCI compliance

When handling payment card data:
  • Use Stripe’s secure payment forms
  • Never store card details directly
  • Implement proper access controls
  • Regularly monitor for vulnerabilities

​
Data protection

  • Follow GDPR requirements for customer data
  • Implement proper data retention policies
  • Provide mechanisms for data deletion
  • Ensure proper consent management

​
Financial regulations

  • Comply with local financial regulations
  • Implement proper record keeping
  • Ensure accurate tax reporting
  • Handle dispute resolution appropriately