SEPA Direct Debit via Stripe

Accept SEPA Direct Debit payments in euro with Stripe as the payment service provider (PSP). The customer gives their IBAN and accepts a SEPA mandate, and Stripe debits their bank account. Payrails offers two SEPA Direct Debit flows through Stripe. The Embedded setting on your Stripe integration picks the flow:

Embedded flow (Embedded on): you collect the IBAN and account holder name in your checkout, and Payrails creates the mandate and the first debit in one call. The customer stays on your checkout, with no redirect. This flow also supports zero-amount mandate setup and merchant-initiated transactions (MIT).
Hosted flow (Embedded off): Payrails returns a redirect to a Stripe Checkout page, where the customer enters their bank details and accepts the mandate.

Supported workflows

Before you begin

Complete these steps before you send your first SEPA Direct Debit payment through Stripe:

Set up a Stripe integration in your workspace. Follow the Stripe integration setup guide if you don’t have one yet.
Turn on SEPA Direct Debit in your Stripe Dashboard payment method settings.
In the Payrails Portal, go to Settings → Integrations, open your Stripe integration, and select SEPA Direct Debit under Payment methods.
To use the embedded flow, turn on Embedded under SEPA Direct Debit. The setting appears after you select the payment method. Leave it off to use the hosted flow. Save the integration.
Add these events to the webhook endpoint of your Stripe account. SEPA Direct Debit payments complete only when Stripe sends the result.
- Embedded flow: payment_intent.processing, payment_intent.succeeded, payment_intent.payment_failed, setup_intent.succeeded and setup_intent.setup_failed.
- Hosted flow: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed and checkout.session.expired.
- Both flows: charge.refunded, which completes refunds.
Add SEPA Direct Debit as a payment option in your workflow.

Request fields for Stripe

The fields you send depend on the flow your Stripe integration uses.

Embedded flow

Send these fields in the authorize request, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to the PSP when you include them.

Field	Status	Description
`amount`	Required	Must be in `EUR`. Send `0.00` to set up a mandate without debiting the account, for example for a free trial.
`paymentComposition[].paymentInstrumentData.payerFields.iban`	Required	The customer’s IBAN, for example `DE89370400440532013000`. Payrails removes spaces, converts it to uppercase, and rejects an invalid IBAN. Not needed when you charge a saved instrument.
`paymentComposition[].paymentInstrumentData.payerFields.accountHolderName`	Required	The account holder’s full name, exactly as it appears on the bank account. Sent to Stripe as the billing name. Not needed when you charge a saved instrument.
`meta.clientContext.ipAddress`	Required	The IP address of the customer who accepts the mandate. Sent to Stripe with the mandate acceptance.
`meta.clientContext.userAgent`	Required	The browser user agent of the customer who accepts the mandate. Sent to Stripe with the mandate acceptance.
`meta.order.billingAddress.email`	Required	Sent to Stripe as the billing email. Send `meta.customer.email` instead if you prefer.
`meta.customer.email`	Optional	Used as the billing email when `meta.order.billingAddress.email` is empty.
`meta.shopperInput.iban`, `meta.shopperInput.accountHolderName`	Optional	Used for the IBAN and account holder name when the payer fields carry no IBAN.
`paymentComposition[].storeInstrument`	Optional	Set to `true` to save the instrument and charge later MIT payments against the mandate. Needed for a zero-amount mandate setup.
`meta.order.billingAddress.street`, `.doorNumber`, `.postalCode`, `.city`, `.country.code`	Optional	Sent to Stripe as the billing address.
`meta.order.description`	Optional	Sent to Stripe as the payment description.
`meta.order.softDescriptor`	Optional	Shown on the customer’s bank statement.

Hosted flow

Field	Status	Description
`amount`	Required	Must be in `EUR` and greater than zero.
`returnInfo.success`	Required	The URL the customer returns to after the Stripe Checkout page.
`returnInfo.cancel`	Optional	The URL the customer returns to when they leave the Stripe Checkout page without paying.
`meta.order.lines`	Required	The items Stripe shows on the Checkout page. Stripe charges the total of these lines, so make them add up to `amount`.
`meta.order.lines[].name`	Required	The item name shown on the Checkout page.
`meta.order.lines[].quantity`	Required	The number of units of the item.
`meta.order.lines[].unitPrice`	Required	The price of one unit, in `EUR`.
`meta.order.lines[].description`	Optional	The item description shown on the Checkout page.

The customer enters their IBAN, name and email on the Stripe Checkout page, so you don’t send bank details in the hosted flow.

Authorize a SEPA Direct Debit payment

Call authorize a payment with sepaDirectDebit as the paymentMethodCode.

Embedded flow

Send the IBAN and account holder name as payer fields, and the customer’s IP address and user agent for the mandate. Set storeInstrument to true to charge later payments against the same mandate.

Authorize request

{
  "amount": {
    "value": "25.00",
    "currency": "EUR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "sepaDirectDebit",
      "amount": {
        "value": "25.00",
        "currency": "EUR"
      },
      "storeInstrument": true,
      "paymentInstrumentData": {
        "payerFields": {
          "iban": "DE89370400440532013000",
          "accountHolderName": "Lena Schmidt"
        }
      }
    }
  ],
  "meta": {
    "clientContext": {
      "ipAddress": "203.0.113.24",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36"
    },
    "order": {
      "billingAddress": {
        "email": "lena.schmidt@example.com",
        "country": {
          "code": "DE"
        }
      }
    }
  }
}

The response is pending, with no redirect. Stripe settles the debit over several business days, and Payrails updates the payment when Stripe sends the result. To charge a later MIT payment, send the paymentInstrumentId saved by the first payment and set meta.order.processingType. Leave out the payer fields and meta.clientContext, because the payment reuses the existing mandate.

MIT authorize request

{
  "amount": {
    "value": "25.00",
    "currency": "EUR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "sepaDirectDebit",
      "paymentInstrumentId": "18635e5c-06b9-4180-9885-6f84e246d1ef",
      "amount": {
        "value": "25.00",
        "currency": "EUR"
      }
    }
  ],
  "meta": {
    "order": {
      "processingType": "Subscription"
    }
  }
}

Hosted flow

Send the order lines and a success URL. The response includes the redirect to the Stripe Checkout page.

Authorize request

{
  "amount": {
    "value": "25.00",
    "currency": "EUR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "sepaDirectDebit",
      "amount": {
        "value": "25.00",
        "currency": "EUR"
      }
    }
  ],
  "meta": {
    "order": {
      "lines": [
        {
          "name": "Monthly plan",
          "quantity": 1,
          "unitPrice": {
            "value": "25.00",
            "currency": "EUR"
          }
        }
      ]
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "cancel": "https://example.com/cancel"
  }
}

After the customer accepts the mandate on the Stripe Checkout page, they return to your success URL and the payment stays pending until the debit settles. In both flows, confirm the result through webhook notifications or the execution status before you fulfill the order.

How Stripe handles SEPA Direct Debit

Stripe accepts SEPA Direct Debit only in EUR. Payrails rejects other currencies before calling Stripe.
Stripe captures SEPA Direct Debit payments automatically. When the debit settles, Payrails marks the payment as captured.
In the embedded flow, Payrails sends the mandate acceptance to Stripe with the customer’s IP address and user agent, and sets the mandate up for reuse. MIT payments charge the saved Stripe payment method against that mandate.
A zero-amount payment in the embedded flow sets up the mandate without debiting the account, and completes in the authorize response. Send it as a customer-initiated payment with storeInstrument set to true.
Payrails doesn’t store the IBAN. Stripe returns only the last four digits, which Payrails keeps with the payment instrument.
If the bank rejects the debit, Payrails marks the payment as failed with the reason Stripe reports.
Refunds work after the debit settles. Refund the full amount or part of it. The refund completes when Stripe sends the charge.refunded event.

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

SEPA Direct Debit via Stripe

Supported workflows

Before you begin

Request fields for Stripe

Embedded flow

Hosted flow

Authorize a SEPA Direct Debit payment

Embedded flow

Hosted flow

How Stripe handles SEPA Direct Debit

​Supported workflows

​Before you begin

​Request fields for Stripe

​Embedded flow

​Hosted flow

​Authorize a SEPA Direct Debit payment

​Embedded flow

​Hosted flow

​How Stripe handles SEPA Direct Debit

Supported workflows

Before you begin

Request fields for Stripe

Embedded flow

Hosted flow

Authorize a SEPA Direct Debit payment

Embedded flow

Hosted flow

How Stripe handles SEPA Direct Debit