Stripe Integration with SmythOS
Want to automate your billing and payment operations? Connect Stripe to SmythOS and empower your agents to create customers, manage payments, and streamline your entire revenue lifecycle.
List of Stripe Components
Quickly compare Stripe components by what they do and their key I/O. Click any component name to jump directly to its detailed guide.
Component | Action | What it Does | Inputs | Key Outputs | Use Case |
---|---|---|---|---|---|
Create Customer | Write | Creates a new customer record in your Stripe account. | required trigger , Body | customerId | Automatically creating a Stripe customer when a new user signs up. |
Get Customer | Read | Retrieves the details of a specific customer by their ID. | required customer_id | customerId , customerEmail | Fetching a customer's details to check their subscription status. |
Prerequisites
Before you begin, please ensure you have the following:
- An active SmythOS account. (Sign up here).
- A Stripe account.
- Your Stripe Secret API Key.
Getting Started With Stripe
The connection between SmythOS and Stripe is configured using a secure API Key.
Step 1: Get Your Stripe API Secret Key
- Log in to your Stripe Dashboard.
- Navigate to the Developers section in the top-right corner.
- In the left menu, click on API Keys.
- You will see your Standard keys. For most integrations, you will use the Secret key.
- Click the Reveal live key or Reveal test key button.
- Copy the secret key (
sk_...
) to your clipboard.
Step 2: Store Your API Key in SmythOS Vault
Your API Secret Key is a highly sensitive credential. Use the SmythOS Vault
to store it securely.
- In your SmythOS dashboard, navigate to the Vault.
- Create a new secret and paste your Stripe API Secret Key as the value. Give it a memorable name, like
stripe_secret_key
. - For more details, see the Vault Documentation.
Step 3: Configure a Stripe Component
- In your SmythOS agent graph, drag and drop any Stripe component.
- Click the component to open its Settings panel.
- In the
API Secret
field, select the secret you saved in the Vault (e.g.,stripe_secret_key
). - Your connection is now configured for that component.
Which Stripe Component Should I Use?
If you need to… | Target | Use this Component | Why this one? |
---|---|---|---|
Create a new billing profile for a user | Customer data (e.g., email, name) | Create Customer | The standard method for creating a new customer object in Stripe before you can charge them. |
Look up a customer's details using their ID | A customer_id | Get Customer | The primary way to retrieve a specific customer's full record from Stripe. |
Component Details
This section provides detailed information for each Stripe component.
Create Customer
Creates a new customer object in your Stripe account.
Component-Specific Settings
- Body: A JSON editor where you define the new customer's details, such as
email
,name
, ordescription
.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
trigger | any | Yes | Any input value can be used to trigger the component's execution. |
Outputs
Field | Type | Description |
---|---|---|
customerId | string | The unique ID of the newly created customer (e.g., cus_... ). |
Response | object | The full, raw JSON response from the Stripe API, containing the complete customer object. |
Headers | object | The HTTP headers from the API response. |
{
"component": "stripe.createCustomer",
"trigger": "true",
"Body": {
"email": "jenny.rosen@example.com",
"name": "Jenny Rosen"
}
}
Get Customer
Retrieves the details of an existing customer by their unique Stripe customer ID.
Inputs
Field | Type | Required | Notes |
---|---|---|---|
customer_id | string | Yes | The unique identifier of the customer to retrieve (e.g., cus_... ). |
Outputs
Field | Type | Description |
---|---|---|
customerId | string | The ID of the retrieved customer. |
customerEmail | string | The email address associated with the customer's profile. |
Response | object | The raw JSON response from the Stripe API, containing the complete customer object. |
Headers | object | The HTTP headers from the API response. |
{
"component": "stripe.getStripeCustomer",
"customer_id": "cus_ABC123XYZ456"
}
Best Practices & Advanced Tips
- Secure Your API Key: Your Stripe Secret Key grants full access to your account's data and operations. Always store it in the SmythOS
Vault
and never expose it. - Use Test Mode: When developing and testing your agents, use your Test API keys from the Stripe Dashboard. Only switch to your Live API keys for your production agents.
- Leverage Metadata: The
metadata
field on many Stripe objects (like Customer) is a powerful tool. Use it to store your application's internal IDs (e.g., your user ID) on the Stripe object. This makes it easy to link a Stripe customer back to a user in your own database. - Handle Errors Gracefully: The Stripe API provides clear error codes and messages. Design your agents to handle common errors, such as a declined card when creating a payment, by parsing the
Response
object.
Troubleshooting Common Issues
-
Error:
401 Unauthorized
- Cause: The API Secret Key is incorrect, has been revoked, or you are using a Test key for a Live request (or vice-versa).
- Solution: Verify that the API Secret in your SmythOS Vault is correct and active. Ensure you are using the correct key (Test vs. Live) for the environment you are targeting.
-
Error:
404 Not Found
- Cause: The ID provided (e.g.,
customer_id
) does not exist. - Solution: Double-check the ID for typos. Ensure the customer record exists in the Stripe environment (Test or Live) that you are querying.
- Cause: The ID provided (e.g.,
-
Error:
400 Bad Request
/ Invalid Parameter- Cause: The JSON
Body
for a create operation is malformed or contains an invalid value for a parameter. - Solution: Carefully check your JSON structure against the official Stripe API documentation. For example, ensure the
email
field is a valid email address.
- Cause: The JSON
What's Next?
You are now ready to build powerful financial and e-commerce automations with the SmythOS Stripe Integration!
Consider these ideas:
-
Build an Agent That...
- Manages the full new user lifecycle. When a user signs up in Firebase Auth, the agent creates a corresponding customer in Stripe and a user profile in your Firestore database.
- Automates invoicing. The agent retrieves a list of monthly active users, generates an invoice for each one using the Stripe API (via a custom API component), and then sends them an email notification using Resend.
- Handles failed payments. When a subscription payment fails (triggered by a Stripe webhook), an agent sends a notification to the customer via SMS using Twilio and creates a follow-up task in Asana for the customer success team.
-
Explore Other Integrations:
- Use Stripe as a trigger. A Stripe webhook can notify your agent of a new purchase, which then grants the user access to a specific course or product.
- Log every new Stripe customer or transaction to a Google Sheet for custom, real-time financial reporting.
Note: Similar to inputs, you can add new outputs by clicking on the
+
button in theOutputs
section. This feature can come in handy when you aim to extract specific values from theResponse
. Please refer here to see a practical example.