Skip to main content

​
About Stripe

Stripe is a payments and financial infrastructure platform covering customers, charges, payment intents, invoices, subscriptions, refunds, payouts, products, prices, disputes, balance, and connected accounts. The Serval Stripe integration connects with a single secret API key and gives your workflows access to the full Stripe API - the integration can do exactly what the key you provide is allowed to do. Serval only ever sends the key to one host for this integration: api.stripe.com. Authentication: API key (a Stripe secret key or, recommended, a restricted key). There is no OAuth or sign-in flow. Data sync: On demand only. There is no background sync, no webhooks, and no preinstalled workflows - Serval talks to Stripe only when a workflow runs or a health check executes.

​
What the Stripe integration enables

Anything defined in the Stripe API can be accessed through Serval.

​
Get your credentials

You need one Stripe API key: either a standard secret key (starts with sk_test_ or sk_live_) or - recommended for least privilege - a restricted key (starts with rk_test_ or rk_live_) that grants only the resources your workflows need. Stripe’s official guide is at docs.stripe.com/keys, and details on how keys authenticate are in the Stripe API authentication docs.
1

Log in to the Stripe Dashboard

Go to dashboard.stripe.com and sign in.
2

Open the API keys page

Navigate to Developers, then API keys, or go directly to dashboard.stripe.com/apikeys.
3

Create a key

Click Create secret key (or Create restricted key to limit permissions). Complete the email or SMS verification if prompted, and give the key a recognizable name such as “Serval Integration”.
4

If using a restricted key, grant the minimum permissions

Serval’s four health checks read your account information, customers, charges, and balance transactions, so grant read access covering those resources if you want every check to pass. Add read and write access on any other resources your workflows will touch.
5

Copy the key immediately

Stripe shows the key only once. Copy it before leaving the page.
Stripe keys are environment-specific. A sk_test_ key sees only test data and a sk_live_ key sees only live data. Create the key in the environment your workflows should operate on.
A standard secret key grants full account access. If you only need Serval to read payment data, a restricted key keeps the blast radius small.

​
Connect in Serval

1

Open the Stripe connect form

Add a new Stripe connection from your Serval integrations page, or from an application’s API integration setup.
2

Paste your key into the API Key field

The form has a single field, API Key (a password-type input with the helper text “Your Stripe API key (starts with sk_test_ or sk_live_)”). Paste the full secret or restricted key you created. The field is not marked required, so you will not see an asterisk or a “This field is required” error.
3

Submit the form

Click Connect Stripe (or Submit if you are connecting through the configure dialog). If saving fails, the application setup form shows “Failed to connect service”, while the configure dialog shows “Failed to install integration” (with details appended when available). On success the connection appears as “Stripe”, pointed at api.stripe.com.
4

Check the health check results

Serval does not test or format-check the key when you save - a blank, mistyped, or truncated key saves without error. When you connect from an application’s setup form, Serval automatically queues the enabled health checks right after the connection saves; review their results, or run them yourself with the Run button on the connection’s health check section (see below).
After saving, the key is displayed masked - bullet characters plus its last 4 characters. To rotate it later, click Replace next to the masked value (or the pencil icon on the connection’s settings form) and paste the complete new key into the “Enter new value” box. Saving an update with the key field untouched or blank keeps your existing stored key, so you never need to re-enter the key just to edit the connection. If an update fails, Serval shows “Failed to update integration:” followed by details, “Failed to update configuration”, or “Failed to save configuration. Please try again.”, depending on which form you used.

​
Verifying the connection

The Stripe integration ships four health checks. Run them after connecting and after rotating the key.
If “Get Stripe Account” passes but the list checks fail, your key is valid but restricted: it is missing read access to customers, charges, or balance transactions. Add those read permissions to the restricted key, or treat those specific failures as expected if your workflows never touch those resources.

​
Gotchas and troubleshooting

Neither the form nor Serval validates the key’s presence or format at connect time. A blank, truncated, or wrong-environment key saves successfully and only shows up later as failing health checks. Check the health check results right after connecting - at minimum “Get Stripe Account”.
Click Replace next to the masked value (configure dialog) or the pencil icon (settings form) and paste the complete new key into the “Enter new value” box. Leaving the field untouched or blank when saving an update keeps the previously stored key, so edits to the connection never require re-entering a working key. After rotating, run the health checks to confirm the new key works.
The four health checks read account info, customers, charges, and balance transactions. A restricted key missing read access to any of these reports “Please verify your API key has the required permissions” even if your actual workflows never touch those resources. Either grant the read permissions or treat those specific failures as expected.
Test mode and live mode are separate worlds in Stripe. A sk_test_ key only sees test data; a sk_live_ key only sees live data. If workflows return data from the wrong environment, reconnect with the key for the intended environment.
Serval attaches your Stripe API key only to requests bound for Stripe’s official API host (api.stripe.com). Custom workflow steps must use standard Stripe API calls; a request to any other host will not carry the credential and will fail to authenticate.
Stripe wraps list results in a page that includes a has_more flag, and the next page is requested with starting_after set to the last item’s ID. Workflows that need a complete list must keep paging until has_more is false. Related objects can be included in a response using Stripe’s expand[] query option. See the Stripe API reference for details, and be aware of Stripe’s rate limits when paging through large lists.
Need help? Contact support@serval.com for assistance with your Stripe integration.