Stripe

📘

Who should use this guide

This guide is intended for merchants who:

• Use Payrails as a payment orchestrator
• Use Stripe Payments (with or without Stripe Connect)
• Are approved to process raw card data

We use a server-to-server integration with Stripe, so your account must be enabled to process raw card data. If this isn’t enabled, payments won’t work in production. Please contact your Stripe account manager or support team to activate it.

How to request access to raw card data processing

1. Contact Stripe Support and provide:

   1. A brief description of the card data management systems and services used in your application.

      We are starting a collaboration with Payrails as a payment orchestrator. While activating our Stripe account, we encountered the following error:

      "Sending credit card numbers directly to the Stripe API is generally unsafe. To continue processing, use Stripe.js, the Stripe mobile bindings, or Stripe Elements. For more information, see the Stripe Dashboard. If you are qualified to handle card data directly, see Stripe Support."

      Could you enable raw card data processing for our account so we can proceed with production?

   2. The Payrails PCI compliance document.

2. Email your Stripe Account Manager, copying Payrails Support, for assistance in enabling this feature.

---

Create and configure a Stripe integration in Payrails

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 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

📋

What you’ll need from Stripe

Before you begin, make sure you have access to:

• (Optional) Service / platform account ID (Stripe Connect only)
• Stripe account ID
• Publishable API key
• Restricted secret API key
• Webhook signing secret

Log in to your Stripe dashboard to complete this step.

Integration instance name

In Payrails

• Enter an Instance name for your integration.

---

Service account (Stripe Connect only)

🔗

Skip this section if you process payments directly on your own Stripe account.

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

🔒

Use a restricted API key to limit access scope and reduce blast radius if the key is compromised.

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)

🔔

Payrails uses Stripe webhooks to receive asynchronous payment status updates.

⚠️

Create the webhook in the same mode (test or live) as your Payrails integration.

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