Stripe

Choose your setup method

Create and configure a Stripe integration in Payrails

The first few steps are the same for both setup methods.

1. Log in to the Payrails portal.
2. Go to Settings → Integrations.
3. Select Add instance to create a new Stripe integration configuration.
4. Select the workspaces where this integration should be available.

About workspaces
Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.

Step 1: Choose the integration type

Select Payment as integration type and continue to the next step.

Step 2: Choose the provider

Select Stripe and continue to the next step.

Step 3: Configure your Stripe integration

When the configuration screen opens, you'll see two tabs at the top of the Account configuration section:

• Stripe Connect — self-serve onboarding (selected by default)
• Manual — manual credential entry

Pick the path that matches your setup:

• Stripe Connect: continue to Step 3A
• Manual: continue to Step 3B

---

Step 3A: Stripe Connect (self-serve onboarding)

This path uses Stripe's OAuth flow to connect your Stripe account to Payrails. No API keys or webhook secrets to copy.

Integration instance name

An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for each provider based on region, currency, or business needs. Choose a clear, consistent name, as it is used in routing.

In Payrails

• Enter an Instance name for your integration.
• Make sure the Stripe Connect tab is selected.

Select payment methods

Under Payment methods, select the payment methods you want to enable.

Connect your Stripe account

Select Save account. A dialog will open explaining the next step.

Select Go to Stripe and a new window opens to Stripe's authorization page.

In Stripe (popup window)

• Sign in with the Stripe account you want to connect, if you're not already signed in.
• Review the permissions Payrails is requesting and authorize Payrails.
• The popup closes automatically and Payrails imports your Stripe credentials in the background.
• When saving completes, you land on the main window where you can see the success message and later on redirected to integration's details page with the Enabled status.

Your Stripe integration is now ready to process payments.

---

Editing an existing Stripe Connect integration

In edit mode, when you re-open a Stripe Connect integration, the configuration screen identifies the currently connected Stripe account ID and lets you choose between keeping the existing connection or connecting a different Stripe account.

When you select Save account, a dialog offers two options:

• Keep existing — preserve the current connection.
• Connect new account — start a fresh OAuth flow with a different Stripe account.

---

Step 3B: Manual setup

Use this path if you need to enter your Stripe credentials directly.

Switch to the Manual tab

In Payrails, on the configuration screen, select the Manual tab.

Integration instance name

An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for each provider based on region, currency, or business needs. Choose a clear, consistent name, as it is used in routing.

Enter an Instance name for your integration.

Service account (Stripe Connect only)

In Stripe

• Go to Settings → Account details.
• Copy the Service account ID (also called the platform account ID).

In Payrails, Paste the value into the Service account field.

Merchant Stripe account ID

In Stripe

• Go to Settings → Business.
• On the Account details tab, copy the account ID (acct_ followed by a 16-character alphanumeric string).

In Payrails, paste the value into the Merchant Stripe account ID field.

Publishable API key

In Stripe

1. Select Developers from the bottom-left navigation.
2. Select Overview (in the Workbench section of the menu).
3. In Workbench, select Manage API keys.
4. In Developers, under Standard keys, copy the publishable key.

In Payrails, paste the value into the Publishable API key field.

Secret API key

In Stripe

1. In Developers, locate Restricted keys and select Create restricted key.
2. Choose Providing this key to another website.
3. Grant the minimum required permissions:
   • Payment Intents (read/write)
   • Charges (read)
   • Refunds (read/write)
   • Webhooks (read)
4. Name the key and add https://www.payrails.com as the destination URL.
5. Copy the generated API key.

In Payrails, paste the value into the Secret API key field.

HMAC key (webhook signing secret)

In Stripe

1. Go to Developers → Webhooks.
2. Select Add destination.
3. Choose Your account, then Selected events, and enable only the following events:
   • charge.refunded
   • payment_intent.amount_capturable_updated
   • payment_intent.canceled
   • payment_intent.partially_funded
   • payment_intent.payment_failed
   • payment_intent.succeeded
4. Select Webhook endpoint and continue.

In Payrails

• Copy the Notification URL from the Account configuration section.

In Stripe

1. Configure the destination:
   1. Give the destination a descriptive name.
   2. Paste the Payrails Notification URL and
   3. Select Create destination.
2. Copy the Signing secret.

In Payrails

• Paste the Signing secret into the correspondine HMAC key field.

Payment methods

In Payrails

• Select the payment methods that should be enabled.

Enable the integration

In Payrails

• Select Save account to enable the integration.

The Enabled status indicates that the Stripe integration is active.

Your Stripe integration is now ready to process payments.

---

Next steps

1. Run a test payment using a Stripe test card.
2. Verify that:
   • The payment appears in Stripe.
   • The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup in live mode.

→ Continue to: Test a payment