Skip to main content
Who should use this guideThis guide is intended for merchants who:
  • Use Payrails as a payment orchestrator
  • Use Stripe Payments and want to onboard their Stripe account using a one-click flow that automatically imports their credentials.

​
Create and configure a Stripe integration in Payrails

Following are the initial steps to setup stripe:
  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 workspacesWorkspaces 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.
Payrails integrations page with Add instance flow for Stripe

​
Step 1: Choose the integration type

Select Payment as integration type and continue to the next step. Payrails integration type selection with Payment selected

​
Step 2: Choose the provider

Select Stripe and continue to the next step. Payrails provider selection with Stripe selected

​
Connect with the Stripe tab

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 tab is selected.

​
Select payment methods

Under Payment methods, select the payment methods you want to enable. A screenshot showing the Stripe payment methods selection in Payrails.

​
Connect your Stripe account

Select Save account. A dialog will open explaining the next step. Payrails dialog prompting to continue Stripe connection Select Go to Stripe and a new window opens to Stripe’s authorization page. Stripe authorization window for connecting account to Payrails 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.
Payrails success message after Stripe account connection Your Stripe integration is now ready to process payments.

​
Editing an existing Stripe 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.
Payrails Stripe edit dialog with keep existing or connect new account options

​
Configure Stripe settings

Some Stripe integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting.

​
Statement descriptor suffix

Statement Descriptor (Suffix) controls how Payrails sends the soft descriptor from meta.order.softDescriptor in your payment request. For more about meta fields, refer to Meta fields. Turn this on if your Stripe account has a shortened descriptor set. The setting has no effect on payments without a soft descriptor.

​
Embedded SEPA Direct Debit

By default, customers paying with SEPA Direct Debit go to a page hosted by Stripe to confirm the mandate. Turn on Embedded under SEPA Direct Debit in Payment methods to complete the payment on your own checkout page instead. Payrails saves the mandate for future debits.
Embedded SEPA Direct Debit only works if your checkout collects everything Stripe needs. Payrails rejects the payment when any of these is missing:
  • The customer’s IBAN, collected in your checkout
  • An email address in meta.order.billingAddress.email or meta.customer.email
  • The customer’s IP address and user agent in meta.clientContext.ipAddress and meta.clientContext.userAgent
  • An amount in EUR greater than zero

​
Stripe Connect

When you connect with the Stripe tab, Payrails turns on Stripe Connect for the integration and processes payments on your connected Stripe account. You don’t need an API key, and the setting doesn’t appear in the form.

​
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
Last modified on September 28, 2026