BlueSnap.comAPI BasicsPayment APIEmbedded PaymentsReporting & ToolsSupport GuidesTest
API Reference

SEPA Direct Debit

Learn how to process SEPA Direct Debit payments with the BlueSnap APIs.
For more information on topics like subscriptions and refunds, visit our support guides.

SEPA (Single Euro Payments Area) Direct Debit is a popular European banking payment method that simplifies cross-border shopping in the Euro. It is an online payment method where money is electronically withdrawn from the shopper’s bank account and then deposited into the merchant’s bank account.

This guide covers the following topics:

Supported markets

Supported currencies

Euro (EUR)
##Supported shopper countries

  • Austria
  • Belgium
  • Cyprus
  • Estonia
  • Finland
  • France
  • Germany
  • Greece
  • Ireland
  • Italy
  • Latvia
  • Lithuania
  • Luxembourg
  • Malta
  • Monaco
  • Netherlands
  • Portugal
  • San Marino
  • Slovakia
  • Slovenia
  • Spain

SEPA Direct Debit transaction processing


Step1

1. Shopper selects SEPA DD and provides IBAN and account holder information.

Step2

2. Shopper accepts mandate authorizing their account to be debited and submits payment.

Step3

3. Merchant sends transaction details to BlueSnap (an invoice in pending status is created).

Step4

4. Shopper gets redirected to post-checkout page and gets notification of upcoming debit.

Step5


5. Within 6 days, shopper's account is debited (invoice status updates to approved).

Step6

6. Shopper gets notification of successful account debit.

Implementing SEPA Direct Debit

📘

Before you begin:

Contact Merchant Support to have SEPA Direct Debit enabled for your account.

After SEPA is enabled, confirm that SEPA Direct Debit is set to Show in your Merchant Portal by going to Checkout Page > Payment Methods.

Implementing SEPA Direct Debit consists of these steps:

Step 1: Collect a mandate acceptance from your shopper

A SEPA Direct Debit mandate is an agreement accepted by the shopper during checkout, authorizing you (through BlueSnap) to pull the funds from their bank account.

Below is an example of the standardized mandate that you must display, where Jane's Shop is your business' name. To get the text in another language, you can download the text from the European Payments Council or use the Get Mandate Text API.

By signing this mandate form, you authorise (A) Jane's Shop to send instructions to your bank to debit your account and (B) your bank to debit your account in accordance with the instructions from Jane's Shop. As part of your rights, you are entitled to a refund from your bank under the terms and conditions of your agreement with your bank. A refund must be claimed within 8 weeks starting from the date on which your account was debited.

Back to Top

Step 2: Send the transaction for processing

Once you have the shopper's authorization, it's time to send their information to BlueSnap via the Payment API or Extended Payment API. Click the desired tab to learn how.


###Processing transactions with the Payment API
You can send a Create SEPA DD Transaction request to begin processing the transaction for a one-time charge, or you can send a create or update vaulted shopper request to attach the payment details a shopper. You can also process subscriptions with SEPA Direct Debit (see Subscriptions).

Below is a simple Create SEPA DD Transaction request with a new shopper.

curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \ 
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "sepaDirectDebitTransaction": {
      "iban": "DE09100100101234567893"
  },
  "payerInfo": {
      "firstName": "John",
      "lastName": "Doe"
  },
  "amount": 9.65,
  "currency": "EUR",
  "authorizedByShopper": true
}'

If successful, the response HTTP status code is 200 OK and it contains the following properties (among others). The values are used in the next step when you display the confirmation message and send a pre-notification email informing the shopper of the upcoming debit.

  • mandateId: Unique identifier for the shopper's mandate acceptance
  • mandateDate: Date of the shopper's mandate acceptance
  • preNotificationText: Text (in English) for the pre-notification email
  • preNotificationTranslationRef: Endpoint to get the pre-notification text in another language*.

*Specify language by its two-letter ISO 639-1 code using the language query string parameter. Omitting the parameter gets the text in all supported languages. 

{
    "transactionId": "1011183521",
    "amount": 9.65,
    "currency": "EUR",
    "payerInfo": { 
        "firstName": "John",
        "lastName": "Doe"
    },
    "vaultedShopperId": 21781957,
    "sepaDirectDebitTransaction": {
        "ibanFirstFour": "DE09",
        "ibanLastFour": "7893",
        "mandateId": "Ooo153451",
        "mandateDate": "21-Jul-17",
        "preNotificationText": "The amount of 9.65 EUR will be collected using SEPA Direct Debit with Mandate Ooo153451 from your bank account IBAN DE09XXXXXX7891 in the next few days. Please ensure sufficient funds in your account.",
        "preNotificationTranslationRef": "https://sandbox.bluesnap.com/services/2/translations/sepa/prenotification?transactionid=1011183521"
    },
    "processingInfo": {
        "processingStatus": "PENDING"
    } 
}


###Processing transactions with the Extended Payment API
You can send a Create Order and New Shopper or Create Order with Existing Shopper request to begin processing the transaction. You can also create/update a shopper before you send the transaction for processing.

Below is a Create Order and New Shopper request and response. 

curl -v -X POST https://sandbox.bluesnap.com/services/2/batch/order-placement \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
<batch-order xmlns="http://ws.plimus.com">
  <shopper>
    <web-info>
      <ip>62.219.121.253</ip>
      <remote-host>www.merchant.com</remote-host>
      <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
    </web-info>
    <shopper-info>
      <store-id>16883</store-id>
      <locale>en</locale>
      <shopper-contact-info>
        <title>Mr.</title>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>[email protected]</email>
        <company-name>JohnDoeAndSons</company-name>
        <address1>138 Market St</address1>
        <city>Toulouse</city>
        <zip>75654</zip>
        <country>FR</country>
        <phone>14135556789</phone>
        <fax>14135556788</fax>
      </shopper-contact-info>
      <payment-info>
      <sepa-direct-debits-info>
        <sepa-direct-debit-info>
            <billing-contact-info>
              <first-name>John</first-name>
              <last-name>Doe</last-name>
              <address1>138 Market St</address1>
              <city>Toulouse</city>
              <zip>75654</zip>
              <country>FR</country>
            </billing-contact-info>
          <sepa-direct-debit>
            <iban>DE09100100101234567893</iban>
          </sepa-direct-debit>
        </sepa-direct-debit-info>
      </sepa-direct-debits-info>
      </payment-info>
    </shopper-info>
  </shopper>
  <order>
    <ordering-shopper>
      <web-info>
        <ip>62.219.121.253</ip>
        <remote-host>www.merchant.com</remote-host>
        <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
      </web-info>
   <authorized-by-shopper>true</authorized-by-shopper>
    </ordering-shopper>
    <cart>
      <cart-item>
        <sku>
          <sku-id>2268801</sku-id>
        </sku>
        <quantity>1</quantity>
      </cart-item>
    </cart>
    <expected-total-price>
      <amount>9.32</amount>
      <currency>EUR</currency>
    </expected-total-price>
  </order>
</batch-order>'

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-order xmlns="http://ws.plimus.com">
  <shopper>
    <shopper-info>
      <shopper-id>22551857</shopper-id>
      <shopper-contact-info>
        <title>Mr.</title>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>jdoe&#x40;email.com</email>
        <company-name>JohnDoeAndSons</company-name>
        <address1>138 Market St</address1>
        <city>Toulouse</city>
        <zip>75654</zip>
        <country>fr</country>
        <phone>14135556789</phone>
        <fax>14135556788</fax>
      </shopper-contact-info>
      <shipping-contact-info/>
      <invoice-contacts-info>
        <invoice-contact-info>
          <default>true</default>
          <title>Mr.</title>
          <first-name>John</first-name>
          <last-name>Doe</last-name>
          <email>jdoe&#x40;email.com</email>
          <company-name>JohnDoeAndSons</company-name>
          <address1>138 Market St</address1>
          <city>Toulouse</city>
          <zip>75654</zip>
          <country>fr</country>
          <phone>14135556789</phone>
          <fax>14135556788</fax>
        </invoice-contact-info>
      </invoice-contacts-info>
      <payment-info>
        <credit-cards-info/>
        <ecps-info/>
        <sepa-direct-debits-info>
          <sepa-direct-debit-info>
            <billing-contact-info>
              <first-name>John</first-name>
              <last-name>Doe</last-name>
              <address1>138 Market St</address1>
              <city>Toulouse</city>
              <zip>75654</zip>
              <country>fr</country>
            </billing-contact-info>
            <sepa-direct-debit>
              <iban-first-four>DE09</iban-first-four>
              <iban-last-four>7893</iban-last-four>
            </sepa-direct-debit>
          </sepa-direct-debit-info>
        </sepa-direct-debits-info>
        <balance/>
      </payment-info>
      <store-id>16883</store-id>
      <shopper-currency>EUR</shopper-currency>
      <locale>en</locale>
    </shopper-info>
  </shopper>
  <order>
    <order-id>9220791</order-id>
    <ordering-shopper>
      <shopper-id>22551857</shopper-id>
    </ordering-shopper>
    <cart>
      <charged-currency>EUR</charged-currency>
      <cart-item>
        <sku>
          <sku-id>2268801</sku-id>
          <sku-name>Test1 Product</sku-name>
        </sku>
        <quantity>1</quantity>
        <item-sub-total>7.76</item-sub-total>
      </cart-item>
      <tax>1.55</tax>
      <tax-rate>20</tax-rate>
      <total-cart-cost>9.32</total-cart-cost>
    </cart>
    <post-sale-info>
      <invoices>
        <invoice>
          <invoice-id>1016357681</invoice-id>
          <url>https://sandbox.bluesnap.com/jsp/show_invoice.jsp?ref=6BE3ACE51A62416AAFA7C60BE9D65C07</url>
          <financial-transactions>
            <financial-transaction>
              <status>Pending</status>
              <date-due>24-Apr-18</date-due>
              <date-created>24-Apr-18</date-created>
              <amount>9.32</amount>
              <tax>1.55</tax>
              <tax-rate>20</tax-rate>
              <currency>EUR</currency>
              <soft-descriptor>BlueSnap Documentati</soft-descriptor>
              <payment-method>SEPA Direct Debit</payment-method>
              <target-balance>PLIMUS_ACCOUNT</target-balance>
              <paypal-transaction-data/>
              <sepa-direct-debit>
                <iban-first-four>DE09</iban-first-four>
                <iban-last-four>7893</iban-last-four>
                <mandate-id>Blu156897</mandate-id>
                <mandate-date>24-Apr-18</mandate-date>
                <pre-notification-text>The amount of 9.32 EUR will be collected using SEPA Direct Debit with Mandate Blu156897 from your bank account IBAN DE09XXXXXX7893 in the next few days. Please ensure sufficient funds in your account.</pre-notification-text>
                <pre-notification-translation-ref>https://sandbox.bluesnap.com:443/services/2/translations/sepa/prenotification?transactionid=1016357681</pre-notification-translation-ref>
              </sepa-direct-debit>
              <invoice-contact-info>
                <title>Mr.</title>
                <first-name>John</first-name>
                <last-name>Doe</last-name>
                <email>jdoe&#x40;email.com</email>
                <company-name>JohnDoeAndSons</company-name>
                <address1>138 Market St</address1>
                <city>Toulouse</city>
                <zip>75654</zip>
                <country>fr</country>
                <phone>14135556789</phone>
                <fax>14135556788</fax>
              </invoice-contact-info>
              <skus>
                <sku>
                  <sku-id>2268801</sku-id>
                  <sku-name>Test1 Product</sku-name>
                </sku>
              </skus>
            </financial-transaction>
          </financial-transactions>
        </invoice>
      </invoices>
    </post-sale-info>
    <fulfillment>
      <license-keys/>
    </fulfillment>
  </order>
</batch-order>

If successful, the response HTTP status code is 200 OK and it contains the following properties (among others). The values are used in the next step when you display the confirmation message and send an email informing the shopper of the upcoming debit (i.e., pre-notification email).

  • mandate-id: Unique identifier for the shopper's mandate acceptance.
  • mandate-date: Date of the shopper's mandate acceptance.
  • pre-notification-text: Text (in English) for pre-notification email informing shopper of upcoming debit.
  • pre-notification-translation-ref: Endpoint to get pre-notification text in another language*.

*Specify language by its two letter ISO 639-1 code using language query string parameter. Omitting parameter gets text in all supported languages.


Back to Top

Step 3: Display a confirmation message & send a pre-notification email

After receiving a successful response from BlueSnap, display a confirmation message to your shopper that shows the mandate ID and mandate date.

In addition, the European Payments Council requires that you send your shopper a pre-notification email - an email informing them each time their account is going to be debited. Pre-notification emails must include the following information:

  • Mandate ID
  • Mandate date
  • Pre-notification text

Below is an example of the standardized text that you must display in the email (the text is provided by the preNotificationText property from the API response). To get the text in another language, you can use the Get Pre-Notification Text API (the preNotificationTranslationRef property from the API response provides you with the endpoint).

The amount of 25 EUR will be collected using SEPA Direct Debit with Mandate Ape151899 from your bank account IBAN DE09XXXXXX7893 in the next few days. Please ensure sufficient funds in your account.

📘

Timeline for sending pre-notification email

For one-time and initial subscription charges: The pre-notification email should be sent after the shopper completes checkout and after you receive a successful response from BlueSnap.

For recurring subscription charges: The pre-notification email should be sent at least 5 days before the next charge date.

Step 4: Confirm the transaction was successful & send a receipt email

Within 5 to 6 business days, the shopper's account is debited (invoice status updates to approved) and BlueSnap sends a Charge webhook with sepaMandateId and sepaMandateDate parameters, notifying you of the successful transaction. At this time, you need to send the receipt email to the shopper that displays the mandate ID and mandate date.

Note: It is recommended to deliver the product only after the approval has been received.

👍

Staying informed of status changes

Webhooks
The Charge webhook (for one-time and initial subscription charges) and Recurring webhook (for recurring subscription charges) notify you when the shopper's account has been debited for the transaction. Make sure you have webhooks enabled in your account settings.

Direct Debit report
Using the Reporting API, you can pull the Direct Debit report to view the invoice status.

Payment API: Retrieve SEPA DD Transaction request
The Retrieve SEPA DD Transaction response includes a processingStatus property. The value indicates the current transaction status.

Extended Payment API: Retrieve Order
The Retrieve Order response includes a status property that indicates the current transaction status.

Sandbox testing

You may use the following IBANs to test various scenarios.

IBANBICTransaction Status Result
DE09100100101234567893PBNKDEFFXXXfrom pending to success
DE09100100101234567892PBNKDEFFXXXfrom pending to fail
DE09100100101234567894PBNKDEFFXXXfrom pending to success to refunded

📘

Notes:

  • After the initial transaction request, you will see the status change within a few minutes.
  • BIC is optional in the API request.


Back to Top