Use APIs to integrate SEPA

The Single Euro Payments Area (SEPA) is a payment-integration initiative of the European Union for simplifying bank transfers denominated in euros between member countries. SEPA helps customers make cashless euro payments to any account located anywhere in the area using a single bank account. To debit from SEPA bank accounts, account holders must accept a mandate authorizing the debtor to debit the account.

SEPA Direct Debit is a PayPal Direct Banking solution that supports you to offer SEPA banks as a payment option to your customers.

Key features of SEPA Direct Debit

Supported transaction types: One-off or recurring payments
Settlement: Instant
Vaulting: Supported
Transaction Currency: EUR only
Supported Countries: Supports bank accounts from 16 countries: Austria, Belgium, Cyprus, Estonia, France, Germany, Greece, Italy, Latvia, Luxembourg, Malta, Netherlands, Portugal, Slovakia, Slovenia, Spain
Refunds: Full, partial, and multiple partial refunds supported
Integration Type: PayPal Orders v2 API

SEPA Direct Debit allows you to access funds immediately if you opt for instant settlements. The delayed settlement option will make funds available within the standard SEPA settlement timeframe of 2-3 days.

How it works

In your checkout flow, you can offer SEPA Direct Debit as a payment choice. Customers choosing to pay with SEPA Direct Debit will provide an IBAN. PayPal validates the IBAN and provides a link to a mandate page. The customer authorizes you and PayPal to debit their SEPA account by agreeing to the mandate. PayPal stores and manages mandates on your behalf. Funds can be debited after the customer accepts the mandate. Mandates can be specified as one-time or recurrent.

The customer is presented with the checkout page.
The customer selects SEPA as the payment method.
The customer provides their IBAN.
The customer is redirected to the PayPal-hosted experience to accept the mandate.
The customer accepts the mandate.
The customer returns to complete checkout.

Know before you code

Mandate management

The mandate acceptance flow displays mandates, obtains customer authorization, and stores it.

Mandates conform to SEPA guidelines and are hosted by PayPal.
Mandates can be specified for one-time or recurrent payments.
Customer acceptance of mandates is stored at PayPal. Currently, it is not possible to view or update mandates once confirmed.
Mandates with no transaction activity in the past 36 months or those that fail risk checks are automatically canceled.

Settlement

Transactions usually take 2-3 business days to settle, but with instant settlement, funds should be available immediately after a transaction is completed. The timeframe and details of the settlement process vary between instant and delayed settlement. Currently, only instant settlement is available, but delayed settlement will be available in future product releases.

Disputes and returns

Customers can dispute any transaction with their bank. Disputes raised within eight weeks of the transaction are automatically honored in alignment with SEPA guidelines. Customers can dispute a transaction as unauthorized after eight weeks, but only up to 13 months.

Eligibility

PayPal Direct Banking Platform's SEPA Direct Debit solution is supported for bank accounts in the following countries


Austria	Belgium	Cyprus	Estonia
France	Germany	Greece	Italy
Latvia	Luxembourg	Malta	Netherlands
Portugal	Slovakia	Slovenia	Spain

EUR is the only supported currency.

Onboarding

Merchants can enable SEPA as a payment method in their PayPal Payment Settings. Merchants who have previously onboarded for PPCP Advanced will experience a simplified one-click onboarding process. For other merchants, onboarding will require answering of short questions about their business information.

Onboarding sellers

You'll need to onboard your sellers to use this product.

Modify your Partner Referral API call to include "SEPA" in the products array for merchant onboarding.
You can also select the "PayPal Complete Payments Full Stack Offering Including SEPA" using the PPCP Onboarding API.
See Onboard sellers before payment for more information.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer ACCESS-TOKEN' \
        -H 'PayPal-Partner-Attribution-ID: BN-CODE' \
        -d '{
          "operations": [
            {
              "operation": "API_INTEGRATION",
              "api_integration_preference": {
                "rest_api_integration": {
                  "integration_method": "PAYPAL",
                  "integration_type": "THIRD_PARTY",
                  "third_party_details": {
                    "features": [
                      "PAYMENT",
                      "REFUND"
                    ]
                  }
                }
              }
            }
          ],
          "products": [
            "PPCP",
            "SEPA"
          ],
          "legal_consents": [
            {
              "type": "SHARE_DATA_CONSENT",
              "granted": true
            }
          ]
        }'

Set up your sandbox account

Before accepting SEPA on your website, verify that your sandbox business account supports it.

Merchants can use the PayPal Developer Dashboard to set up their sandbox accounts to accept SEPA. Partner account integration involves creating a sandbox business account through sandbox.paypal.com. If SEPA is disabled for the account, complete the sandbox onboarding steps to enable it.

Log in to the PayPal Developer Dashboard and go to your sandbox account.
Go to Apps & Credentials.
Ensure you are in the PayPal sandbox environment by selecting Sandbox at the top.
Select or create an app.
Scroll down and check if SEPA is enabled. If not, select the SEPA checkbox.

If you created a sandbox business account through sandbox.paypal.com and SEPA is disabled, complete the sandbox onboarding steps to enable it.

When your integration is ready to go live, review the Go Live section for additional SEPA onboarding steps.

Integration guidelines

Fully customize the SEPA direct debit payment experience and cater to business needs using,
- Orders API - SEPA Direct Debit
  - An order represents a payment between two or more parties. Use Orders API to:
    - Create an order
    - Confirm payment source
      - Collect the customer's authorization for the SEPA Direct Debit payment method.
    - Capture the order
- Payments API Refund
  - Use the Payments API to refund captured payments.
- Webhooks Management API
  - A webhook is an event notification.
  - Use the Webhooks Management API to configure a webhook listener for your application and subscribe to transaction events.
Each transaction must have a unique transaction reference (order ID, invoice ID, and so on) as the value of soft_descriptor.
Use the request parameter experience_context.locale to set the locale for your customer.
Provide validated customer addresses, as PayPal performs only minimal validation. Invalid addresses may impact transaction settlement.
Collect the customer's first and last name, separated by a space. Incomplete names will result in an INVALID_PARAM_SYNTAX error.

1. Create an order

To create an order, copy and modify the following code.

Sample request

API endpoint used: Create Order

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer ACCESS-TOKEN' \
        -d '{
          "intent": "CAPTURE",
          "purchase_units": [
            {
              "amount": {
                "currency_code": "EUR",
                "value": "100.00"
              },
              "payee": {
                "email_address": "[email protected]"
              }
            }
          ]
        }'

Modify the code

After copying the code, modify the following:

Replace ACCESS-TOKEN with your access token.
Set intent to CAPTURE.
[Optiona] Add a platform_fees array within the purchase_units to specify fees for the order.

To help prevent unauthorized disputes, use the soft_descriptor in the Orders API so payers can recognize the transaction on their statements.

Step result

A successful request results in the following:

An HTTP 201 Created status code.
A JSON response body containing the order ID. You'll use this ID to capture the order.

2. Confirm payment source

Confirm the order by providing the SEPA payment source using IBAN details.

Limited-release API endpoint used: Confirm Payment Source

curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders/6EN97188M64374140/confirm-payment-source' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer ACCESS-TOKEN' \
        --data '{
          "payment_source": {
            "bank": {
              "sepa_debit": {
                "iban": "FR7618106000321234566666610",
                "account_holder_name": "John Doe",
                "billing_address": {
                  "address_line_1": "23 Rue du Roi de Sicile",
                  "admin_area_1": "Paris",
                  "admin_area_2": "Paris",
                  "postal_code": "75004",
                  "country_code": "FR"
                },
                "attributes": {
                  "mandate": {
                    "type": "ONE_OFF"
                  },
                  "customer": {
                    "merchant_customer_id": "[email protected]"
                  }
                },
                "experience_context": {
                  "locale": "en-FR",
                  "return_url": "https://example.com/returnUrl",
                  "cancel_url": "https://example.com/cancelUrl"
                }
              }
            }
          }
        }'

Step result

A successful request results in the following:

An HTTP 201 Created status code.
A JSON response body containing the order status, payment_source as bank.sepa_debit, and payer-action URL in links.
Use the payer-action URL to redirect the customer for mandate approval.

3. Approve one-time mandate

Redirect the customer to the payer-action URL obtained in the Confirm payment source API response to get the mandate approved.

Step result

Upon successful mandate approval, the customer is redirected to the return_url provided in the confirm-payment-source request under experience_context. After successful mandate approval, you can capture the order.

4. Capture an order

Set up your server to call the Capture Order API:

Use the Capture Order v2 API endpoint with intent as CAPTURE.
Platform integrations must include the PayPal-Partner-Attribution-Id header for reporting and tracking.

curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders/6EN97188M64374140/capture' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer ACCESS-TOKEN' \
        --header 'PayPal-Partner-Attribution-Id: BN-CODE' \
        --data '{}'

Step result

A successful request results in the following:

An HTTP 201 Created status code.

Regulatory guidelines

SEPA Return Reason Codes - PDF

SEPA regulations require you to notify your customer upon successful debit for one-time and recurring transactions. This notification should be displayed on purchase confirmation pages and in associated emails. Informing your customers can reduce returns.
Merchants must allow buyers to dispute a SEPA Direct Debit for up to eight weeks from the transaction date without question, with disputes automatically honored.
You may opt to communicate mandate information to your customer during or after mandate authorization.

Any failures to the mandate acceptance (including non-acceptance by the buyer, system errors, or timeouts) will take the customer to the cancel_url provided in the confirm-payment-source request under experience_context. At the cancel URL, a new mandate URL must be requested using the confirm-payment-source API.

Go live

Test integration

Test your SEPA integration in the PayPal sandbox and production environment to ensure your app works correctly.

Sandbox

Use your sandbox login information during checkout to complete a payment using SEPA. Then, log into the sandbox site sandbox.paypal.com to see that the money has moved into your account.

Open your test page with a supported web browser on any supported device.
Use test IBANs for SEPA-supported countries to test the transaction flows: Generate IBAN
Tap the SEPA button to open the SEPA payment experience.
Make a payment using the SEPA payment method.
If you have an additional confirmation page on your merchant website, continue to confirm the payment.
Log in to your merchant account and continue to your confirmation page to confirm that the money you used for payment showed up in the account.

SEPA reports

SEPA transactions, fees, and returns data are included in relevant PayPal reports.

SEPA transactions are shown as Direct Debit in the Payment Source column of STL, TRR, and Activity Download reports.
For SEPA returns, the Decline Code column indicates the SEPA return code (see the SEPA Return Reason Codessection).

SEPA Return reason codes

SEPA Return reason codes - PDF

SEPA risks

The SEPA Direct Debit scheme doesn't guarantee funds, as your customer or their bank can initiate disputes.

Disputes raised within eight weeks of the transaction are automatically honored per SEPA guidelines.
All returns, including those for disputes and insufficient funds, may incur a return fee charged by the customer's bank and passed on to you.
Some banks may refuse to honor electronic mandates and return MD01.
With instant settlement, settled funds may be debited from your account if the customer has insufficient funds. This debit typically occurs 1-2 days after the transaction.
The SEPA Direct Debit scheme allows returns on any transaction, even those you've already refunded. The scheme doesn't link refunds to the original transaction and permits disputes on the original transaction.

SEPA Direct Debit is a PayPal Direct Banking solution that supports you to offer SEPA banks as a payment option to your customers.

Key features of SEPA Direct Debit

Supported transaction types: One-off or recurring payments
Settlement: Instant
Vaulting: Supported
Transaction Currency: EUR only
Supported Countries: Supports bank accounts from 16 countries: Austria, Belgium, Cyprus, Estonia, France, Germany, Greece, Italy, Latvia, Luxembourg, Malta, Netherlands, Portugal, Slovakia, Slovenia, Spain
Refunds: Full, partial, and multiple partial refunds supported
Integration Type: PayPal Orders v2 API

How it works

The customer is presented with the checkout page.
The customer selects SEPA as the payment method.
The customer provides their IBAN.
The customer is redirected to the PayPal-hosted experience to accept the mandate.
The customer accepts the mandate.
The customer returns to complete checkout.

Know before you code

Mandate management

The mandate acceptance flow displays mandates, obtains customer authorization, and stores it.

Mandates conform to SEPA guidelines and are hosted by PayPal.
Mandates can be specified for one-time or recurrent payments.
Customer acceptance of mandates is stored at PayPal. Currently, it is not possible to view or update mandates once confirmed.
Mandates with no transaction activity in the past 36 months or those that fail risk checks are automatically canceled.

Settlement

Disputes and returns

Eligibility

PayPal Direct Banking Platform's SEPA Direct Debit solution is supported for bank accounts in the following countries


Austria	Belgium	Cyprus	Estonia
France	Germany	Greece	Italy
Latvia	Luxembourg	Malta	Netherlands
Portugal	Slovakia	Slovenia	Spain

EUR is the only supported currency.

Onboarding

Onboarding sellers

You'll need to onboard your sellers to use this product.

Modify your Partner Referral API call to include "SEPA" in the products array for merchant onboarding.
You can also select the "PayPal Complete Payments Full Stack Offering Including SEPA" using the PPCP Onboarding API.
See Onboard sellers before payment for more information.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer ACCESS-TOKEN' \
        -H 'PayPal-Partner-Attribution-ID: BN-CODE' \
        -d '{
          "operations": [
            {
              "operation": "API_INTEGRATION",
              "api_integration_preference": {
                "rest_api_integration": {
                  "integration_method": "PAYPAL",
                  "integration_type": "THIRD_PARTY",
                  "third_party_details": {
                    "features": [
                      "PAYMENT",
                      "REFUND"
                    ]
                  }
                }
              }
            }
          ],
          "products": [
            "PPCP",
            "SEPA"
          ],
          "legal_consents": [
            {
              "type": "SHARE_DATA_CONSENT",
              "granted": true
            }
          ]
        }'

Set up your sandbox account

Before accepting SEPA on your website, verify that your sandbox business account supports it.

Log in to the PayPal Developer Dashboard and go to your sandbox account.
Go to Apps & Credentials.
Ensure you are in the PayPal sandbox environment by selecting Sandbox at the top.
Select or create an app.
Scroll down and check if SEPA is enabled. If not, select the SEPA checkbox.

If you created a sandbox business account through sandbox.paypal.com and SEPA is disabled, complete the sandbox onboarding steps to enable it.

When your integration is ready to go live, review the Go Live section for additional SEPA onboarding steps.

Integration guidelines

Fully customize the SEPA direct debit payment experience and cater to business needs using,
- Orders API - SEPA Direct Debit
  - An order represents a payment between two or more parties. Use Orders API to:
    - Create an order
    - Confirm payment source
      - Collect the customer's authorization for the SEPA Direct Debit payment method.
    - Capture the order
- Payments API Refund
  - Use the Payments API to refund captured payments.
- Webhooks Management API
  - A webhook is an event notification.
  - Use the Webhooks Management API to configure a webhook listener for your application and subscribe to transaction events.
Each transaction must have a unique transaction reference (order ID, invoice ID, and so on) as the value of soft_descriptor.
Use the request parameter experience_context.locale to set the locale for your customer.
Provide validated customer addresses, as PayPal performs only minimal validation. Invalid addresses may impact transaction settlement.
Collect the customer's first and last name, separated by a space. Incomplete names will result in an INVALID_PARAM_SYNTAX error.

1. Create an order

To create an order, copy and modify the following code.

Sample request

API endpoint used: Create Order

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer ACCESS-TOKEN' \
        -d '{
          "intent": "CAPTURE",
          "purchase_units": [
            {
              "amount": {
                "currency_code": "EUR",
                "value": "100.00"
              },
              "payee": {
                "email_address": "[email protected]"
              }
            }
          ]
        }'

Modify the code

After copying the code, modify the following:

Replace ACCESS-TOKEN with your access token.
Set intent to CAPTURE.
[Optiona] Add a platform_fees array within the purchase_units to specify fees for the order.

To help prevent unauthorized disputes, use the soft_descriptor in the Orders API so payers can recognize the transaction on their statements.

Step result

A successful request results in the following:

An HTTP 201 Created status code.
A JSON response body containing the order ID. You'll use this ID to capture the order.

2. Confirm payment source

Confirm the order by providing the SEPA payment source using IBAN details.

Limited-release API endpoint used: Confirm Payment Source

curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders/6EN97188M64374140/confirm-payment-source' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer ACCESS-TOKEN' \
        --data '{
          "payment_source": {
            "bank": {
              "sepa_debit": {
                "iban": "FR7618106000321234566666610",
                "account_holder_name": "John Doe",
                "billing_address": {
                  "address_line_1": "23 Rue du Roi de Sicile",
                  "admin_area_1": "Paris",
                  "admin_area_2": "Paris",
                  "postal_code": "75004",
                  "country_code": "FR"
                },
                "attributes": {
                  "mandate": {
                    "type": "ONE_OFF"
                  },
                  "customer": {
                    "merchant_customer_id": "[email protected]"
                  }
                },
                "experience_context": {
                  "locale": "en-FR",
                  "return_url": "https://example.com/returnUrl",
                  "cancel_url": "https://example.com/cancelUrl"
                }
              }
            }
          }
        }'

Step result

A successful request results in the following:

An HTTP 201 Created status code.
A JSON response body containing the order status, payment_source as bank.sepa_debit, and payer-action URL in links.
Use the payer-action URL to redirect the customer for mandate approval.

3. Approve one-time mandate

Redirect the customer to the payer-action URL obtained in the Confirm payment source API response to get the mandate approved.

Step result

4. Capture an order

Set up your server to call the Capture Order API:

Use the Capture Order v2 API endpoint with intent as CAPTURE.
Platform integrations must include the PayPal-Partner-Attribution-Id header for reporting and tracking.

curl -v -X POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders/6EN97188M64374140/capture' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer ACCESS-TOKEN' \
        --header 'PayPal-Partner-Attribution-Id: BN-CODE' \
        --data '{}'

Step result

A successful request results in the following:

An HTTP 201 Created status code.

Regulatory guidelines

SEPA Return Reason Codes - PDF

SEPA regulations require you to notify your customer upon successful debit for one-time and recurring transactions. This notification should be displayed on purchase confirmation pages and in associated emails. Informing your customers can reduce returns.
Merchants must allow buyers to dispute a SEPA Direct Debit for up to eight weeks from the transaction date without question, with disputes automatically honored.
You may opt to communicate mandate information to your customer during or after mandate authorization.

Open your test page with a supported web browser on any supported device.
Use test IBANs for SEPA-supported countries to test the transaction flows: Generate IBAN
Tap the SEPA button to open the SEPA payment experience.
Make a payment using the SEPA payment method.
If you have an additional confirmation page on your merchant website, continue to confirm the payment.
Log in to your merchant account and continue to your confirmation page to confirm that the money you used for payment showed up in the account.

SEPA reports

SEPA transactions, fees, and returns data are included in relevant PayPal reports.

SEPA transactions are shown as Direct Debit in the Payment Source column of STL, TRR, and Activity Download reports.
For SEPA returns, the Decline Code column indicates the SEPA return code (see the SEPA Return Reason Codessection).

SEPA Return reason codes

SEPA Return reason codes - PDF

SEPA risks

The SEPA Direct Debit scheme doesn't guarantee funds, as your customer or their bank can initiate disputes.

Disputes raised within eight weeks of the transaction are automatically honored per SEPA guidelines.
All returns, including those for disputes and insufficient funds, may incur a return fee charged by the customer's bank and passed on to you.
Some banks may refuse to honor electronic mandates and return MD01.
With instant settlement, settled funds may be debited from your account if the customer has insufficient funds. This debit typically occurs 1-2 days after the transaction.
The SEPA Direct Debit scheme allows returns on any transaction, even those you've already refunded. The scheme doesn't link refunds to the original transaction and permits disputes on the original transaction.

Use APIs to integrate SEPA

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Use APIs to integrate SEPA

On this page

On this page