Connecting Providers
Providers are payment processors that you connect to surstrom.
Supported Providers
Currently supported:
- Stripe — Full support with restricted API keys
Connecting a Stripe Account
Step 1: Create a Restricted API Key
In your Stripe Dashboard:
- Go to Developers → API Keys
- Click Create restricted key → select Building your own integration
- Give the key a neutral name (e.g.
Stripe) - Set the following permissions:
| Name in Stripe Dashboard | Permission | Why it's needed |
|---|---|---|
| Payment Intents | Read + Write | Create, cancel and poll payment status |
| Balance | Read | Read net amount and fee per transaction processed through the platform only |
| View documentation | Read | Fetches your Stripe account profile via GET /v1/account — account name, country, and default currency. Used to display the provider card in the dashboard, determine native currency for payment routing, and pre-fill the statement descriptor |
- Click Create key and copy it (starts with
rk_)
Step 2: Publishable Key
You also need a publishable key for the frontend SDK:
- In Stripe Dashboard → Developers → API Keys
- Copy your Publishable key (starts with
pk_live_)
Step 3: Connect in surstrom
- Go to Dashboard → Connect
- Select Stripe as the provider
- Paste your Publishable Key and Restricted API key
- The system validates the key by fetching your account details
- Click Verify credentials
The system verifies your API key by making a test call to GET /v1/account on Stripe. If the key lacks required permissions, the connection will fail.
Provider Settings
After connecting, configure your provider:
Embed URL (Relay Page)
The URL of the page where you'll install the SDK. This page must:
- Be publicly accessible
- Have the SDK script tag installed
- Allow iframe embedding
Payment Description
Optional text that appears in payment descriptions.
Statement Descriptor Suffix
Up to 10 uppercase characters appended to the statement descriptor. Only A-Z, digits, spaces, dots, hyphens, and underscores allowed. Supports dynamic generation with placeholders like {externalId} or {suffixClient}.
Metadata
Optional key-value pairs attached to payment intents. Supports dynamic generation.
Use your provider's built-in fraud protection tools to secure payments: enable Radar rules, require 3D Secure for all transactions, and set fraud score thresholds. These settings are configured in your Stripe Dashboard, not in surstrom.
Provider Status Indicators
In the sidebar, each provider shows a status icon:
| Icon | Meaning |
|---|---|
| Green check | In pool — actively receiving payments |
| Yellow alert | Ready but not in pool |
| Red alert | Not ready — missing configuration or failed verification |
Updating API Keys
To rotate or update your API key:
- Navigate to the provider's settings page
- Click Update API Key
- Paste your new restricted key
- The system validates and updates the key
When updating your API key, the statement descriptor is automatically synced from your provider account. If you changed your business name in Stripe, it will be reflected after the key update.
Deleting a Provider
- Navigate to the provider's settings page
- Ensure it's not in the pool (remove from pool first)
- Click Delete and confirm
Deleting a provider is permanent. All associated configuration is removed. Active payments in progress will still complete.