Stripe Integration

37 pre-built templates across 10 categories

Easy Connect: Click "Connect Platform" → Stripe → paste your API key. That's it. All 37 templates unlock instantly.

Quick Setup

Step 1: Get Your Secret Key

1Log in to your Stripe Dashboard
2Go to Developers → API keys
3Copy your Secret key (starts with sk_live_)

Step 2: Connect in Staffify

1Go to Settings → Integrations
2Click Connect Platform → Stripe
3Paste your secret key and click Test & Connect

Note: Stripe API keys don't expire, so no token refresh is needed. Use sk_test_ keys for testing, sk_live_ for production.

All 37 Templates

Click "Add Action" on your Stripe connection, then browse templates by category.

Customers (5 templates)

Template	Method	Endpoint	Description
Search Customers	GET	/customers	Search customers by email or other attributes
Get Customer by ID	GET	/customers/{{customer_id}}	Retrieve a specific customer
Create Customer	POST	/customers	Create a new customer record
Update Customer	POST	/customers/{{customer_id}}	Update customer details (name, email, metadata)
Delete Customer	DELETE	/customers/{{customer_id}}	Permanently delete a customer

Payments (4 templates)

Template	Method	Endpoint	Description
List Payment Intents	GET	/payment_intents	List all payment intents
Get Payment Intent	GET	/payment_intents/{{payment_intent_id}}	Retrieve a specific payment intent
Create Payment Intent	POST	/payment_intents	Create a new payment intent
Search Payment Intents	GET	/payment_intents/search?query={{query}}	Search payment intents with Stripe Search

Invoices (5 templates)

Template	Method	Endpoint	Description
List Invoices	GET	/invoices	List all invoices
Get Invoice	GET	/invoices/{{invoice_id}}	Retrieve a specific invoice
Create Draft Invoice	POST	/invoices	Create a new draft invoice for a customer
Finalize Invoice	POST	/invoices/{{invoice_id}}/finalize	Finalize a draft invoice so it can be paid
Search Invoices	GET	/invoices/search?query={{query}}	Search invoices with Stripe Search

Subscriptions (4 templates)

Template	Method	Endpoint	Description
List Subscriptions	GET	/subscriptions	List all subscriptions
Get Subscription	GET	/subscriptions/{{subscription_id}}	Retrieve a specific subscription
Create Subscription	POST	/subscriptions	Create a new subscription for a customer
Cancel Subscription	DELETE	/subscriptions/{{subscription_id}}	Cancel a subscription

Products & Prices (4 templates)

Template	Method	Endpoint	Description
List Products	GET	/products	List all products
Get Product	GET	/products/{{product_id}}	Retrieve a specific product
List Prices	GET	/prices	List all prices, optionally filtered by product
Create Price	POST	/prices	Create a new price for a product

Refunds (3 templates)

Template	Method	Endpoint	Description
List Refunds	GET	/refunds	List all refunds
Get Refund	GET	/refunds/{{refund_id}}	Retrieve a specific refund
Create Refund	POST	/refunds	Refund a payment intent or charge

Payment Methods (3 templates)

Template	Method	Endpoint	Description
List Payment Methods	GET	/customers/{{customer_id}}/payment_methods	List payment methods for a customer
Get Payment Method	GET	/payment_methods/{{payment_method_id}}	Retrieve a specific payment method
Detach Payment Method	POST	/payment_methods/{{payment_method_id}}/detach	Detach a payment method from a customer

Charges (4 templates)

Template	Method	Endpoint	Description
List Charges	GET	/charges	List all charges
Get Charge	GET	/charges/{{charge_id}}	Retrieve a specific charge
Search Charges	GET	/charges/search?query={{query}}	Search charges with Stripe Search
Capture Charge	POST	/charges/{{charge_id}}/capture	Capture an uncaptured charge

Balance (2 templates)

Template	Method	Endpoint	Description
Get Balance	GET	/balance	Retrieve your account balance
List Balance Transactions	GET	/balance_transactions	List all balance transactions

Events (3 templates)

Template	Method	Endpoint	Description
List Events	GET	/events	List all events
Get Event	GET	/events/{{event_id}}	Retrieve a specific event
List Events by Type	GET	/events?type={{type}}	List events filtered by type

Common AI Use Cases

Customer Lookup & Account Status

When a customer calls, the AI looks them up by email and reports their subscription status, balance, and recent payments.

Use: Search Customers → List Invoices → List Subscriptions

Process Refund Requests

AI verifies the customer's identity, looks up their payment, and processes a refund when authorized.

Use: Search Customers → List Charges → Create Refund

Tip: Enable identity verification and mark Create Refund as destructive with confirmation required.

Subscription Management

AI checks a customer's current plan and can cancel or update their subscription during the call.

Use: Search Customers → Get Subscription → Cancel Subscription

Invoice & Payment History

AI retrieves recent invoices and payment details for billing inquiries.

Use: Search Invoices or List Balance Transactions

Stripe Search Syntax

The Search templates (Payment Intents, Invoices, Charges) use Stripe's query language:

Example Query	Description
status:"succeeded"	Payment intents with status succeeded
amount>5000	Charges over $50.00 (amounts in cents)
customer:"cus_xxx"	Invoices for a specific customer
created>1672531200	Events after a Unix timestamp

Example: Search Customers Response

{
  "data": [{
    "id": "cus_ABC123",
    "email": "[email protected]",
    "name": "John Smith",
    "balance": 0,
    "subscriptions": {
      "data": [{
        "id": "sub_XYZ789",
        "status": "active",
        "plan": {
          "nickname": "Pro Plan",
          "amount": 4900,
          "interval": "month"
        }
      }]
    }
  }]
}

Endpoint Details

Create Customer

Parameter	Type	Required	Description
email	string	Recommended	Customer email address
name	string	No	Customer full name
phone	string	No	Customer phone number
description	string	No	Internal description or notes
metadata	object	No	Key-value pairs for custom data

{
  "email": "[email protected]",
  "name": "John Smith",
  "phone": "+15551234567",
  "metadata": {
    "source": "phone_call",
    "staffify_call_id": "call_abc123"
  }
}

Create Payment Intent

Parameter	Type	Required	Description
amount	integer	Yes	Amount in cents (e.g., 5000 = $50.00)
currency	string	Yes	Three-letter ISO currency code (e.g., "usd")
customer	string	Recommended	Stripe customer ID (cus_xxx)
description	string	No	Description of the payment
metadata	object	No	Custom key-value pairs

{
  "amount": 5000,
  "currency": "usd",
  "customer": "cus_ABC123",
  "description": "Invoice #1234 payment"
}

Create Invoice

Parameter	Type	Required	Description
customer	string	Yes	Stripe customer ID
collection_method	string	No	"charge_automatically" or "send_invoice"
description	string	No	Invoice memo/description
days_until_due	integer	No	Days until due (for send_invoice method)
metadata	object	No	Custom key-value pairs

{
  "customer": "cus_ABC123",
  "collection_method": "send_invoice",
  "days_until_due": 30,
  "description": "March 2026 services"
}

Create Subscription

Parameter	Type	Required	Description
customer	string	Yes	Stripe customer ID
items	array	Yes	Array of {price: "price_xxx"} objects
trial_period_days	integer	No	Number of trial days
metadata	object	No	Custom key-value pairs

{
  "customer": "cus_ABC123",
  "items": [
    {"price": "price_XYZ789"}
  ]
}

Create Refund

Parameter	Type	Required	Description
payment_intent	string	Yes*	Payment intent ID to refund (*or charge)
charge	string	Yes*	Charge ID to refund (*or payment_intent)
amount	integer	No	Partial refund amount in cents (omit for full refund)
reason	string	No	"duplicate", "fraudulent", or "requested_by_customer"
metadata	object	No	Custom key-value pairs

{
  "payment_intent": "pi_DEF456",
  "amount": 2500,
  "reason": "requested_by_customer"
}

Response Examples

Get Customer Response

{
  "id": "cus_ABC123",
  "object": "customer",
  "email": "[email protected]",
  "name": "John Smith",
  "phone": "+15551234567",
  "balance": 0,
  "created": 1709312400,
  "currency": "usd",
  "default_source": null,
  "metadata": {
    "source": "phone_call"
  }
}

List Invoices Response

{
  "object": "list",
  "data": [{
    "id": "in_GHI789",
    "object": "invoice",
    "customer": "cus_ABC123",
    "amount_due": 4900,
    "amount_paid": 4900,
    "currency": "usd",
    "status": "paid",
    "created": 1709312400,
    "period_start": 1706720400,
    "period_end": 1709312400
  }],
  "has_more": false
}

Create Refund Response

{
  "id": "re_JKL012",
  "object": "refund",
  "amount": 2500,
  "currency": "usd",
  "payment_intent": "pi_DEF456",
  "reason": "requested_by_customer",
  "status": "succeeded",
  "created": 1709398800
}

Example Conversation

Here's how your AI agent uses Stripe during a real phone call:

Caller: “Hi, I'd like to request a refund for my last payment. My email is [email protected].”

→ Executes: search_customers with email=“[email protected]”

→ Found: John Smith (cus_ABC123), Pro Plan subscription active

AI Agent: “I found your account, John. Let me verify your identity first. Can you confirm the last 4 digits of the card on file?”

Caller: “4242.”

→ Identity verified via last-4-digits match

AI Agent: “Verified. Let me pull up your recent charges.”

→ Executes: list_charges with customer=“cus_ABC123”

→ Found: $49.00 charge on Feb 28 (pi_DEF456), $49.00 on Jan 28

AI Agent: “I see your most recent charge of $49.00 on February 28th. Would you like a full or partial refund?”

Caller: “Full refund please.”

→ Executes: create_refund with payment_intent=“pi_DEF456”, reason=“requested_by_customer”

→ Refund re_JKL012 created, status: succeeded

AI Agent: “Done! Your $49.00 refund has been processed. It should appear on your statement within 5-10 business days. Is there anything else I can help with?”

Stripe-Specific Notes

Amounts in cents: All monetary amounts in Stripe are in the smallest currency unit. $50.00 = 5000, $1.50 = 150. The AI handles this conversion automatically when talking to customers.

Form-encoded bodies: Stripe uses application/x-www-form-urlencoded for request bodies, not JSON. Staffify handles the encoding automatically when using templates.

Idempotency keys: For create operations, Staffify automatically generates an Idempotency-Key header to prevent duplicate charges if a request is retried.

Test vs Live: Use sk_test_ keys during setup to test safely. Switch to sk_live_ for production. Test keys never process real charges.

Error Reference

Status Code	Meaning	Common Cause
400 Bad Request	Invalid request parameters	Missing required field or invalid value (e.g., negative amount)
401 Unauthorized	Invalid API key	Check that your secret key is correct and active
402 Card Declined	Payment cannot be processed	Customer's card was declined. AI will inform the caller.
404 Not Found	Resource not found	The customer, charge, or invoice ID does not exist
429 Rate Limited	Too many requests	Stripe rate limits: 100 reads/sec, 100 writes/sec per key

Last updated: March 2026

Back to Integrations Guide