Skip to content

SEPA Direct Debit

SEPA Direct Debit is a payment instrument for executing direct debit transactions in euros within the Single Euro Payments Area (SEPA) zone. It simplifies Euro-denominated transactions across the EU.

It enables Creditors to present charges through their Financial Institution based on a Debit Authorization given by the Debtor to the Creditor. Both the Debtor and the Creditor must hold accounts within the SEPA zone.

Payment optionCategoryCountriesCurrenciesFeaturesIntegrations
SEPA DDDirect DebitAustria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary, Iceland, Ireland, Italy, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Spain, Sweden, SwitzerlandEURPartial refund
Refunds
API
Payment Form

How to use SEPA DD

SEPA Direct Debit provides an efficient method for transactions within the European Union.
Here’s a guide to understanding and utilizing this streamlined payment process:

Step 1: Select SEPA Direct Debit during checkout to initiate the payment process.
Step 2: Input your personal details, including full name and address, alongside the IBAN (International Bank Account Number) and provide authorization for the mandate.
Step 3: Receive a prompt notification confirming the successful completion of your payment transaction.

Info

To start accepting payments with SEPA DD, contact your Account Manager.

How it works

Below, you’ll discover a detailed breakdown of the necessary steps for implementing the SEPA Direct Debit payment method:

Step 1: Create the Order
Step 2: Create SEPA Direct Debit Mandate
Step 3: Present SEPA Direct Debit Collection
Step 4: Get SEPA DD Token Details
Step 1: Create the Order

Begin the order request by designating SEPA Direct Debit (“SPDD”) as the preferred payment method (transaction.paymentMethod). Confirm that the transaction amount (transaction.amount) is set to 0. Furthermore, make sure to add the mandate object as specified in the following instructions:

LocationData ElementTypeConditionDescription
Request BodymandatemandateOptionalMandate details information
Request Body.mandatemandateIdStringMandatoryIdentification of the Direct Debit mandate resource.
It refers to Debit Authorisation Number.
Max35Text
Request Body.mandatemandateDescriptionStringMandatoryDescription of the Direct Debit mandate resource’s context.
Max256Text
Request Body.mandatefrequencyStringOptionalRegularity with which instructions are to be created and processed.

“OOFF” – “One-Off” (Direct debit instruction where the debtor’s authorisation is used to initiate one single direct debit transaction)

“RCUR” – “Recurring” (Direct debit instruction where the debtor’s authorisation is used for regular direct debit transactions initiated by the creditor)

Exact4Text
Request Body.mandateserviceType ServiceTypeCodeMandatoryIdentification of the SEPA Direct Debits service related to the specific Direct Debit Mandate.

It can be fulfilled with the following values:
“CORE” when it refers to SEPA DD CORE service;
“BTOB” when it refers to SEPA DD B2B service.

Exact4Text
Step 2: Create SEPA Direct Debit Mandate

After the order creation process is completed and the customer selects the ‘SPDD’ method as their preferred payment option, the subsequent step involves generating a SEPA Direct Debit mandate resource.

A mandate is a document signed by the debtor, authorizing the creditor to collect payments and allowing the debtor’s bank to process these collections.

This selection triggers two distinct options for mandate creation:

Option 1: Create SEPA DD Mandate

This process involves creating a SEPA Direct Debit Mandate, where both Creditor and Debtor Details are required. The customer needs to fill in all Debtor Account Details, provide an IBAN proof document, and their signature. After this, the mandate is finalized and registered.

As a result, the customer now has a SEPA Direct Debit mandate that’s ready for future use in payments using the Present SEPA Direct Debit Collection Operation, initiated by the Merchant.

Having outlined this process, detailed steps on implementing this SEPA Direct Debit Mandate creation will follow:

Endpoints:
EnvironmentURLOperation Method & EndpointOperation Description
PRODapi.sibsgateway.comPOST {version-id}/{id}/mandates/sepaddCreates a SEPA DD mandate resource specified in the request.
TESTstargate-cer.qly.site[1|2].sibs.ptPOST {version-id}/{id}/mandates/sepaddCreates a SEPA DD mandate resource specified in the request.

Make certain to incorporate these crucial components as outlined:

LocationData ElementTypeConditionDescription
PathidStringMandatoryUsed to identify the transaction
Header Parameters:
LocationData ElementTypeConditionDescription
Request HeaderContent-TypeStringMandatoryapplication/json
Request HeaderAuthorizationStringMandatoryAuthorization Digest
Request parameters:
LocationData ElementTypeConditionDescription
Request BodyuserAcceptanceIndicatorBooleanMandatoryIndicates if the user has accepted the Terms and Conditions, in order to continue with the payment.
Request Body.infodeviceInfoDeviceInfoMandatoryObject that defines the customer device information.
Request Body.info.deviceInfobrowserAcceptHeaderstringOptionalBrowser Accept Header
Request Body.info.deviceInfobrowserJavaEnabledstringOptionalBrowser Java Enabled
Request Body.info.deviceInfobrowserLanguagestringOptionalbrowser Language
Request Body.info.deviceInfobrowserColorDepthstringOptionalbrowser Color Depth
Request Body.info.deviceInfobrowserScreenHeightstringOptionalbrowser Screen Height
Request Body.info.deviceInfobrowserScreenWidthstringOptionalbrowser Screen Width
Request Body.info.deviceInfobrowserTZstringOptionalBrowser Time Zone
Request Body.info.deviceInfobrowserUserAgentstringOptionalBrowser User Agent
Request Body.info.deviceInfosystemFamilystringOptionalSystem Family
Request Body.info.deviceInfosystemVersionstringOptionalSystem Version
Request Body.info.deviceInfosystemArchitecturestringOptionalSystem Architecture
Request Body.info.deviceInfodeviceManufacturerstringOptionalDevice Manufacturer
Request Body.info.deviceInfodeviceModelstringOptionalDevice Model
Request Body.info.deviceInfodeviceIDstringOptionalDevice Unique Identification
Request Body.info.deviceInfoapplicationNamestringOptionalApplication Name
Request Body.info.deviceInfoapplicationVersionstringOptionalApplication Version
Request Body.info.deviceInfogeoLocalizationstringOptionalGeolocation
Request Body.info.deviceInfoipAddressstringOptionalIP Address
Request BodymandatemandateMandatoryMandate information
Request Body.mandatemandateIdStringMandatoryIdentification of the Direct Debit mandate resource.
It refers to Debit Authorisation Number.

Max35Text
Request Body.mandatemandateDescriptionStringMandatoryDescription of the Direct Debit mandate resource’s context.

Max256Text
Request Body.mandatefrequencyFrequencyTypeCodeMandatoryRegularity with which instructions are to be created and processed.
“OOFF” – “One-Off” (Direct debit instruction where the debtor’s authorisation is used to initiate one single direct debit transaction)

“RCUR” – “Recurring” (Direct debit instruction where the debtor’s authorisation is used for regular direct debit transactions initiated by the creditor)

Exact4Text
Request BodycreditorcreditorMandatoryCreditor Information
Request Body.creditorcreditorIdStringMandatoryIdentification of Creditors, e.g. a SEPA Creditor ID.

Max35Text
Request BodydebtordebtorMandatoryDebtor Information
Request Body.debtorcustomerFullNameStringMandatoryCustomer full name.

Max140Text
Request Body.debtorcustomerEmailStringMandatoryCustomer email.

Max255Text
Request Body.debtorcustomerAddressStringMandatoryCustomer address.

Max140Text
Request Body.debtorcustomerAddressPostalCodeStringMandatoryCustomer address postal code.

Max16Text
Request Body.debtorcustomerAddressCityStringMandatoryCustomer address city.

Max35Text
Request Body.debtorcustomerAddressCountryStringMandatoryCustomer address country.

ISO Alpha2
Request Body.debtordebtorAccountAccount ReferenceMandatoryDebtor Account Information
Request Body.debtor.debtorAccountibanIBANMandatoryInternational Bank Account Number (of Debtor).

Max34Text (IBAN ISO13616)
Request Body.debtor.debtorAccountdebtorAgentBICFIOptionalIdentification of Creditor (BIC SWIFT).

Max11Text

ISO9362 format
Request Body.debtor.debtorAccountconfirmationFileBinary FileMandatoryAccount confirmation document (proof of account ownership – certificate file).

1MB Binary File
Request Body.debtor.debtorAccountfileContentTypeStringMandatoryFile content type
Possible values:
application.jpeg
application.png
application.pdf
Request Body.debtorcustomerSignatureStringMandatoryCustomer signature details
Request Body.debtor.customerSignaturelocalStringMandatoryCustomer signature local.

Max35Text
Request Body.debtor.customerSignaturedateISODateMandatoryCustomer signature date

ISODate
Request Body.debtor.customerSignatureimageBinary FileMandatoryCustomer signature image.

1MB Binary File
Request Body.debtor.customerSignaturefileContentTypeStringMandatoryImage content type
Possible values:
application.jpeg
application.tiff
application.png
application.gif

Here’s an example of how to Create the Mandate:

{
    "mandate": {
        "mandateId": "mandateID",
        "mandateDescription": "mandateDescription",
        "frequency": "OOFF",
        "serviceType": "CORE"
    },
    "creditor": {
        "creditorId": "NL89ZZZOP4GBH51AL8LS3DY1QG"
    },
    "debtor": {
        "customerFullName": "Testing Customer Name",
        "customerEmail": "email@provider.com",
        "customerAddress": "Full Address testing",
        "customerAddressPostalCode": "1011AA",
        "customerAddressCity": "TestCity",
        "customerAddressCountry": "NL",
        "debtorAccount": {
            "iban": "NL27TUUk48tlEvz9tk6o9Q6Mxaiyz",
            "confirmationFile": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD/4gxYSUNDX1BST0ZJTEUAAQEAAAxITGlubwIQAABtbnRyUkdCIFhZWiAHzgACAAkABgAxAABhY3NwTVNGVAAAAABJRUMgc1JHQgAAAAAAAAAAAAAAAAAA9tYAAQAAAADTLUhQICAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABFjcHJ0AAABUAAAADNkZXNjAAABhAAAAGx3dHB0AAAB8AAAABRia3B0AAACBAAAABRyWFlaAAACGAAAABRnWFlaAAACLAAAABRiWFlaAAACQAAAABRkbW5kAAACVAAAAHBkbWRkAAACxAAAAIh2dWVkAAADTAAAAIZ2aWV3AAAD1AAAACRsdW1pAAAD
+IlnWeJf4QbwKgtIlfEDb1GjbkJawN1uXWHnqZHsti+BfRKB51NDZaccTKMSx74mWseY2fmGVEV81BaSwOtRXnq8TXFeSFBMcwVPB+Zd06OpovGo4MVrApcXKVfMdwFDms0Ratq2qI20PUvA71iJd9TIMeoETUYKPHUcZcjiJSnWXMcxOeIy84aM5lW9epghC1YxcWrsm1Lc5lKfvNE6l/3caDsTMT5l7cp1LN6xFNxWTzUc24qvxHI80x8be2WKWxs+ZmlGDPuZaPeYGMYzcXVX6qYvXce6OcEtXrjEbz/9k=",
            "fileContentType": "application.jpeg"
        }
    }
}
Option 2: Create SEPA DD Mandate with Authentication (designed for iDeal clients)

This process involves requesting the creation of a SEPA DD Mandate with Authentication, supporting the Customer’s account verification and authentication through an iDEAL payment processing (followed by an iDEAL Payment Refund). This facilitates the completion of the mandate details, particularly the debtor account details.

As a result, the Customer will have a SEPA DD mandate created and ready for future use in payments using the Present SEPA DD Collection Operation, initiated by the Merchant.

To initiate this operation, the API Get SEPA DD Payment Link must be executed.

How to Get SEPA Direct Debit Payment Link

It is necessary to retrieve the SEPA Direct Debit payment link as it is integral for executing the transaction.
Further details regarding this process are outlined below:

Endpoints:
EnvironmentURLOperation Method & EndpointOperation Description
PRODapi.sibsgateway.comPOST {version-id}/payments/{id}/sepa/payment-linkPerform the transaction and redirect user to Payment Host.
TESTstargate-cer.qly.site[1|2].sibs.ptPOST {version-id}/payments/{id}/sepa/payment-linkPerform the transaction and redirect user to Payment Host.

Ensure the inclusion of these vital elements as specified:

LocationData ElementTypeConditionDescription
PathidStringMandatoryUsed to identify the transaction
Header parameters:
LocationData ElementTypeConditionDescription
Request HeaderContent-TypeStringMandatoryapplication/json
Request HeaderAuthorizationStringMandatoryAuthorization Digest
Request parameters:
LocationData ElementTypeConditionDescription
Request BodyuserAcceptanceIndicatorBooleanMandatoryIndicates if the user has accepted the Terms and Conditions, in order to continue with the payment.
Request BodygatewayIdStringMandatoryPayment Channel identifier for the channel the Customer is going to use for their payment.
Possible values are:
‘ideal’ – iDEAL;
Request BodyinfoInfoMandatoryObject that defines the transaction additional information.
Request Body.infodeviceInfoDeviceInfoOptionalObject that defines the customer device information.
Request Body.info.deviceInfobrowserAcceptHeaderstringOptionalBrowser Accept Header
Request Body.info.deviceInfobrowserJavaEnabledstringOptionalBrowser Java Enabled
Request Body.info.deviceInfobrowserLanguagestringOptionalbrowser Language
Request Body.info.deviceInfobrowserColorDepthstringOptionalbrowser Color Depth
Request Body.info.deviceInfobrowserScreenHeightstringOptionalbrowser Screen Height
Request Body.info.deviceInfobrowserScreenWidthstringOptionalbrowser Screen Width
Request Body.info.deviceInfobrowserTZstringOptionalBrowser Time Zone
Request Body.info.deviceInfobrowserUserAgentstringOptionalBrowser User Agent
Request Body.info.deviceInfosystemFamilystringOptionalSystem Family
Request Body.info.deviceInfosystemVersionstringOptionalSystem Version
Request Body.info.deviceInfosystemArchitecturestringOptionalSystem Architecture
Request Body.info.deviceInfodeviceManufacturerstringOptionalDevice Manufacturer
Request Body.info.deviceInfodeviceModelstringOptionalDevice Model
Request Body.info.deviceInfodeviceIDstringOptionalDevice Unique Identification
Request Body.info.deviceInfoapplicationNamestringOptionalApplication Name
Request Body.info.deviceInfoapplicationVersionstringOptionalApplication Version
Request Body.info.deviceInfogeoLocalizationstringOptionalGeolocation
Request Body.info.deviceInfoipAddressstringOptionalIP Address
Request BodymerchantMerchantOptionalMerchant Data
Request Body.merchantmerchantURLstringMandatoryMerchant Shop URL for redirect.
Request Body.merchantappToAppURLstringOptionalCustom app URL for customer redirect back to the app, which triggered the payment.
Request Body.infoaccountInfoAccountInfoOptionalAccount related data.
Applicable when gatewayId is ‘ideal’.
Request Body.info.accountInfoholderNameStringOptionalAccount Holder Name. UTF-8 Format. Max100Text
Request Body.info.accountInfocustomerCountryStringOptionalCustomer Country Code. Alpha2
Request BodytransactionalScopeStringMandatoryIdentification of specific transactional scope of Payment Link request.

Possible values:
‘SPDD’ (SEPA Direct Debits)

Exact4Text
Request BodymandatemandateConditionalOnly present when transactionalScope is ‘SPDD’ (SEPA Direct Debits)

Mandate information
Request Body.mandatemandateIdStringMandatoryIdentification of the Direct Debit mandate resource.
It refers to Debit Authorisation Number.

Max35Text
Request Body.mandatemandateDescriptionStringMandatoryDescription of the Direct Debit mandate resource’s context.

Max256Text
Request Body.mandatefrequencyFrequencyTypeCodeMandatoryRegularity with which instructions are to be created and processed.
“OOFF” – “One-Off” (Direct debit instruction where the debtor’s authorisation is used to initiate one single direct debit transaction)

“RCUR” – “Recurring” (Direct debit instruction where the debtor’s authorisation is used for regular direct debit transactions initiated by the creditor)

Exact4Text
Request BodycreditorcreditorMandatoryCreditor Information
Request Body.creditorcreditorIdStringMandatoryIdentification of Creditors, e.g. a SEPA Creditor ID.

Max35Text
Request BodydebtordebtorMandatoryDebtor Information
Request Body.debtorcustomerFullNameStringMandatoryCustomer full name.

Max140Text
Request Body.debtorcustomerEmailStringMandatoryCustomer email.

Max255Text
Request Body.debtorcustomerAddressStringMandatoryCustomer address.

Max140Text
Request Body.debtorcustomerAddressPostalCodeStringMandatoryCustomer address postal code.

Max16Text
Request Body.debtorcustomerAddressCityStringMandatoryCustomer address city.

Max35Text
Request Body.debtorcustomerAddressCountryStringMandatoryCustomer address country.

ISO Alpha2
Request BodyterminalCodeIntegerMandatoryTerminal Code

MaxInclusive value=”999999999″

Here’s an example of how to Create the Mandate with iDeal:

{
    "terminalCode": {{TerminalIDPPRO}},
    "gatewayId": "ideal",
    "info": {
        "deviceInfo": {
            "browserAcceptHeader": "application/json, text/plain, */*",
            "browserJavaEnabled": "false",
            "browserLanguage": "en",
            "browserColorDepth": "24",
            "browserScreenHeight": "1080",
            "browserScreenWidth": "1920",
            "browserTZ": "-60",
            "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
            "geoLocalization": "Lat: 38.7350528 | Long: -9.2143616",
            "systemFamily": "Windows",
            "systemVersion": "Windows",
            "deviceID": "498bfd4c3a3645b38667a7037b616c18",
            "applicationName": "Chrome",
            "applicationVersion": "106"
        },
        "customerInfo": [
            {
                "key": "customerName",
                "value": "Test Name"
            },
            {
                "key": "customerEmail",
                "value": "email@provider.com"
            }
        ],
        "accountInfo": {
            "holderName": "User",
            "customerCountry": "NL"
        }
    },
    "mandate": {
        "mandateId": "mandateID",
        "mandateDescription": "mandateDescription",
        "frequency": "OOFF",
        "serviceType": "CORE"
    },
    "creditor": {
        "creditorId": "NL89ZZZOP4GBH51AL8LS3DY1QG"
    },
    "debtor": {
        "customerFullName": "Testing Customer Name",
        "customerEmail": "email@provider.com",
        "customerAddress": "Full Address testing",
        "customerAddressPostalCode": "1011AA",
        "customerAddressCity": "TestCity",
        "customerAddressCountry": "NL"
    },
    "merchant": {
        "merchantURL": "https://egadget2.azurewebsites.net/#/returns?id={{transactionId}}"
    },
    "transactionalScope": "SPDD"
}

Thereafter, you can perform a “Get Status” operation to check the status.
As a result you will receive a TokenValue that will be used on the next steps.

The Authorization HTTP header is set to the Bearer token as it was used in the initial Checkout.

GET {transactionID}/status
Request URL:
https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
Request Headers:
Authorization: ‘Bearer <AuthToken>’ 
X-IBM-Client-Id: ‘<ClientId>’ 
Content-Type: application/json

Following this, it’s essential to promptly redirect the user to the Payment Host.

Step 3: Present SEPA Direct Debit Collection

The SEPA DD Collection operation entails retrieving the information stored during the creation of the mandate between the Creditor and Debtor.

The interface to be accessed by the Merchant to enable the execution of the Present SEPA Direct Debit Collection operation via the SIBS Payment Gateway, utilizing the API Frontend.

When Present SEPA DD Collection is initiated, it retrieves the information recorded during the mandate’s creation involving the Creditor and Debtor. The resulting response indicates the transaction’s status.

Endpoints:
EnvironmentURLOperation Method & EndpointOperation Description
PRODapi.sibsgateway.comPOST {version-id}/mandates/{token-id}/sepadd/collectRequests the data registered by the mandate creation using SEPA DD Collection method.
TESTstargate-cer.qly.site[1|2].sibs.ptPOST {version-id}/mandates/{token-id}/sepadd/collectRequests the data registered by the mandate creation using SEPA DD Collection method.

Be sure to include these essential elements as instructed:

LocationData ElementTypeConditionDescription
Pathtoken-idStringConditionalMandate Identifier
Header parameters:
LocationData ElementTypeConditionDescription
Request HeaderContent-TypeStringMandatoryapplication/json
Request HeaderauthorizationStringMandatoryBearer Token. Based on OAuth2 authentication performed in a pre-step.
Request Headerx-ibm-client-idStringMandatoryToken that identifies a client organization. It is provided during onboarding process and must be used in every call.
Request parameters:
LocationData ElementTypeConditionDescription
Request BodyinfoInfoMandatoryObject that defines the transaction additional information.
Request Body.infocustomDatacustomDataMandatoryKey Value tuple array.
Request Body.info.customDatakeystringOptional
Request Body.info.customDatavaluestringOptional
Request BodymerchantmerchantMandatoryObject that defines a Merchant.
Request Body.merchantterminalIdstringMandatoryMerchant Terminal Identification.

Maximum length is 10.
Request Body.merchantmerchantTransactionIdstringMandatoryUnique Id used by the Merchant.

Maximum length is 35.
Request Body.merchanttransactionDescriptionstringOptionalMerchant Transaction Short Description.

Maximum length is 256.
Request BodymandatemandateMandatoryDetailed data regarding the existing mandate between creditor and debtor.
Request Body.mandatetokenIdstringMandatoryToken value related to the Mandate Identifier.

Maximum length is 35.
Request Body.mandateamountamountMandatoryParameter with the value and currency of the transaction.
Request Body.mandate.amountvaluenumber (double)MandatoryAmount to be collected.
Request Body.mandate.amountcurrencycurrencyCodeMandatoryCurrency used in the transaction.

ISO 4217 Alpha-3 Code.
Request Body.mandatedueDatestringMandatoryDue Date for collection.

Date.

Here’s an example of how to do the Mandate Collection:

{
    "merchant": {
        "terminalId": "{{TerminalIDPPRO}}",
        "channel": "web",
        "merchantTransactionId": "7235666",
        "transactionDescription": "transaction short description",
        "shopURL": "https://mytest.e-shop.pl/"
    },
    "mandate": {
        "tokenId": "{{tokenId}}",
        "amount": {
            "value": 1,
            "currency": "EUR"
        },
        "dueDate": "{{dueDate}}"
    },
    "customer": {
        "customerInfo": [
            {
            "key": "customerName",
            "value": "Test Name"
            },
            {
            "key": "customerEmail",
            "value": "email@provider.com"
            }
        ]
    }
}

An indication of a successful technical response includes an HTTP-200 status and a ‘returnStatus.statusCode’ of “000” within the SEPA DD Collection Response.

Step 4: Get SEPA DD Token Details

Additionally, you should perform a “Get Token Details” operation as informed below, to check mandate information at any time:

GET version-id/token/details
Request Headers:
Authorization: ‘Bearer <AuthToken>’ 
X-IBM-Client-Id: ‘<ClientId>’ 
Content-Type: application/json 

An indication of a successful SEPA DD Collection response includes an HTTP-200 status. It also contains token “status” that could have different values as shown in the table below.

Token “status”Token “status” short description
INTTInitiated
PDNGPending
ACTVActive
INCTInactive
SSPNSuspended
EXPRExpired
CNCLCancelled
RJCTRejected
RFSDRefused