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 option | Category | Countries | Currencies | Features | Integrations |
---|---|---|---|---|---|
SEPA DD | Direct Debit | Austria, 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, Switzerland | EUR | Partial 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.
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:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Request Body | mandate | mandate | Optional | Mandate details information |
Request Body.mandate | mandateId | String | Mandatory | Identification of the Direct Debit mandate resource. It refers to Debit Authorisation Number. Max35Text |
Request Body.mandate | mandateDescription | String | Mandatory | Description of the Direct Debit mandate resource’s context. Max256Text |
Request Body.mandate | frequency | String | Optional | Regularity 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.mandate | serviceType | ServiceTypeCode | Mandatory | Identification 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
- Option 2: Create SEPA DD Mandate with Authentication (designed for iDeal clients)
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:
Environment | URL | Operation Method & Endpoint | Operation Description |
---|---|---|---|
PROD | api.sibsgateway.com | POST {version-id}/{id}/mandates/sepadd | Creates a SEPA DD mandate resource specified in the request. |
TEST | stargate-cer.qly.site[1|2].sibs.pt | POST {version-id}/{id}/mandates/sepadd | Creates a SEPA DD mandate resource specified in the request. |
Make certain to incorporate these crucial components as outlined:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Path | id | String | Mandatory | Used to identify the transaction |
Header Parameters:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Request Header | Content-Type | String | Mandatory | application/json |
Request Header | Authorization | String | Mandatory | Authorization Digest |
Request parameters:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Request Body | userAcceptanceIndicator | Boolean | Mandatory | Indicates if the user has accepted the Terms and Conditions, in order to continue with the payment. |
Request Body.info | deviceInfo | DeviceInfo | Mandatory | Object that defines the customer device information. |
Request Body.info.deviceInfo | browserAcceptHeader | string | Optional | Browser Accept Header |
Request Body.info.deviceInfo | browserJavaEnabled | string | Optional | Browser Java Enabled |
Request Body.info.deviceInfo | browserLanguage | string | Optional | browser Language |
Request Body.info.deviceInfo | browserColorDepth | string | Optional | browser Color Depth |
Request Body.info.deviceInfo | browserScreenHeight | string | Optional | browser Screen Height |
Request Body.info.deviceInfo | browserScreenWidth | string | Optional | browser Screen Width |
Request Body.info.deviceInfo | browserTZ | string | Optional | Browser Time Zone |
Request Body.info.deviceInfo | browserUserAgent | string | Optional | Browser User Agent |
Request Body.info.deviceInfo | systemFamily | string | Optional | System Family |
Request Body.info.deviceInfo | systemVersion | string | Optional | System Version |
Request Body.info.deviceInfo | systemArchitecture | string | Optional | System Architecture |
Request Body.info.deviceInfo | deviceManufacturer | string | Optional | Device Manufacturer |
Request Body.info.deviceInfo | deviceModel | string | Optional | Device Model |
Request Body.info.deviceInfo | deviceID | string | Optional | Device Unique Identification |
Request Body.info.deviceInfo | applicationName | string | Optional | Application Name |
Request Body.info.deviceInfo | applicationVersion | string | Optional | Application Version |
Request Body.info.deviceInfo | geoLocalization | string | Optional | Geolocation |
Request Body.info.deviceInfo | ipAddress | string | Optional | IP Address |
Request Body | mandate | mandate | Mandatory | Mandate information |
Request Body.mandate | mandateId | String | Mandatory | Identification of the Direct Debit mandate resource. It refers to Debit Authorisation Number. Max35Text |
Request Body.mandate | mandateDescription | String | Mandatory | Description of the Direct Debit mandate resource’s context. Max256Text |
Request Body.mandate | frequency | FrequencyTypeCode | Mandatory | Regularity 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 | creditor | creditor | Mandatory | Creditor Information |
Request Body.creditor | creditorId | String | Mandatory | Identification of Creditors, e.g. a SEPA Creditor ID. Max35Text |
Request Body | debtor | debtor | Mandatory | Debtor Information |
Request Body.debtor | customerFullName | String | Mandatory | Customer full name. Max140Text |
Request Body.debtor | customerEmail | String | Mandatory | Customer email. Max255Text |
Request Body.debtor | customerAddress | String | Mandatory | Customer address. Max140Text |
Request Body.debtor | customerAddressPostalCode | String | Mandatory | Customer address postal code. Max16Text |
Request Body.debtor | customerAddressCity | String | Mandatory | Customer address city. Max35Text |
Request Body.debtor | customerAddressCountry | String | Mandatory | Customer address country. ISO Alpha2 |
Request Body.debtor | debtorAccount | Account Reference | Mandatory | Debtor Account Information |
Request Body.debtor.debtorAccount | iban | IBAN | Mandatory | International Bank Account Number (of Debtor). Max34Text (IBAN ISO13616) |
Request Body.debtor.debtorAccount | debtorAgent | BICFI | Optional | Identification of Creditor (BIC SWIFT). Max11Text ISO9362 format |
Request Body.debtor.debtorAccount | confirmationFile | Binary File | Mandatory | Account confirmation document (proof of account ownership – certificate file). 1MB Binary File |
Request Body.debtor.debtorAccount | fileContentType | String | Mandatory | File content type Possible values: application.jpeg application.png application.pdf |
Request Body.debtor | customerSignature | String | Mandatory | Customer signature details |
Request Body.debtor.customerSignature | local | String | Mandatory | Customer signature local. Max35Text |
Request Body.debtor.customerSignature | date | ISODate | Mandatory | Customer signature date ISODate |
Request Body.debtor.customerSignature | image | Binary File | Mandatory | Customer signature image. 1MB Binary File |
Request Body.debtor.customerSignature | fileContentType | String | Mandatory | Image 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:
Environment | URL | Operation Method & Endpoint | Operation Description |
---|---|---|---|
PROD | api.sibsgateway.com | POST {version-id}/payments/{id}/sepa/payment-link | Perform the transaction and redirect user to Payment Host. |
TEST | stargate-cer.qly.site[1|2].sibs.pt | POST {version-id}/payments/{id}/sepa/payment-link | Perform the transaction and redirect user to Payment Host. |
Ensure the inclusion of these vital elements as specified:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Path | id | String | Mandatory | Used to identify the transaction |
Header parameters:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Request Header | Content-Type | String | Mandatory | application/json |
Request Header | Authorization | String | Mandatory | Authorization Digest |
Request parameters:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Request Body | userAcceptanceIndicator | Boolean | Mandatory | Indicates if the user has accepted the Terms and Conditions, in order to continue with the payment. |
Request Body | gatewayId | String | Mandatory | Payment Channel identifier for the channel the Customer is going to use for their payment. Possible values are: ‘ideal’ – iDEAL; |
Request Body | info | Info | Mandatory | Object that defines the transaction additional information. |
Request Body.info | deviceInfo | DeviceInfo | Optional | Object that defines the customer device information. |
Request Body.info.deviceInfo | browserAcceptHeader | string | Optional | Browser Accept Header |
Request Body.info.deviceInfo | browserJavaEnabled | string | Optional | Browser Java Enabled |
Request Body.info.deviceInfo | browserLanguage | string | Optional | browser Language |
Request Body.info.deviceInfo | browserColorDepth | string | Optional | browser Color Depth |
Request Body.info.deviceInfo | browserScreenHeight | string | Optional | browser Screen Height |
Request Body.info.deviceInfo | browserScreenWidth | string | Optional | browser Screen Width |
Request Body.info.deviceInfo | browserTZ | string | Optional | Browser Time Zone |
Request Body.info.deviceInfo | browserUserAgent | string | Optional | Browser User Agent |
Request Body.info.deviceInfo | systemFamily | string | Optional | System Family |
Request Body.info.deviceInfo | systemVersion | string | Optional | System Version |
Request Body.info.deviceInfo | systemArchitecture | string | Optional | System Architecture |
Request Body.info.deviceInfo | deviceManufacturer | string | Optional | Device Manufacturer |
Request Body.info.deviceInfo | deviceModel | string | Optional | Device Model |
Request Body.info.deviceInfo | deviceID | string | Optional | Device Unique Identification |
Request Body.info.deviceInfo | applicationName | string | Optional | Application Name |
Request Body.info.deviceInfo | applicationVersion | string | Optional | Application Version |
Request Body.info.deviceInfo | geoLocalization | string | Optional | Geolocation |
Request Body.info.deviceInfo | ipAddress | string | Optional | IP Address |
Request Body | merchant | Merchant | Optional | Merchant Data |
Request Body.merchant | merchantURL | string | Mandatory | Merchant Shop URL for redirect. |
Request Body.merchant | appToAppURL | string | Optional | Custom app URL for customer redirect back to the app, which triggered the payment. |
Request Body.info | accountInfo | AccountInfo | Optional | Account related data. Applicable when gatewayId is ‘ideal’. |
Request Body.info.accountInfo | holderName | String | Optional | Account Holder Name. UTF-8 Format. Max100Text |
Request Body.info.accountInfo | customerCountry | String | Optional | Customer Country Code. Alpha2 |
Request Body | transactionalScope | String | Mandatory | Identification of specific transactional scope of Payment Link request. Possible values: ‘SPDD’ (SEPA Direct Debits) Exact4Text |
Request Body | mandate | mandate | Conditional | Only present when transactionalScope is ‘SPDD’ (SEPA Direct Debits) Mandate information |
Request Body.mandate | mandateId | String | Mandatory | Identification of the Direct Debit mandate resource. It refers to Debit Authorisation Number. Max35Text |
Request Body.mandate | mandateDescription | String | Mandatory | Description of the Direct Debit mandate resource’s context. Max256Text |
Request Body.mandate | frequency | FrequencyTypeCode | Mandatory | Regularity 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 | creditor | creditor | Mandatory | Creditor Information |
Request Body.creditor | creditorId | String | Mandatory | Identification of Creditors, e.g. a SEPA Creditor ID. Max35Text |
Request Body | debtor | debtor | Mandatory | Debtor Information |
Request Body.debtor | customerFullName | String | Mandatory | Customer full name. Max140Text |
Request Body.debtor | customerEmail | String | Mandatory | Customer email. Max255Text |
Request Body.debtor | customerAddress | String | Mandatory | Customer address. Max140Text |
Request Body.debtor | customerAddressPostalCode | String | Mandatory | Customer address postal code. Max16Text |
Request Body.debtor | customerAddressCity | String | Mandatory | Customer address city. Max35Text |
Request Body.debtor | customerAddressCountry | String | Mandatory | Customer address country. ISO Alpha2 |
Request Body | terminalCode | Integer | Mandatory | Terminal 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:
Environment | URL | Operation Method & Endpoint | Operation Description |
---|---|---|---|
PROD | api.sibsgateway.com | POST {version-id}/mandates/{token-id}/sepadd/collect | Requests the data registered by the mandate creation using SEPA DD Collection method. |
TEST | stargate-cer.qly.site[1|2].sibs.pt | POST {version-id}/mandates/{token-id}/sepadd/collect | Requests the data registered by the mandate creation using SEPA DD Collection method. |
Be sure to include these essential elements as instructed:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Path | token-id | String | Conditional | Mandate Identifier |
Header parameters:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Request Header | Content-Type | String | Mandatory | application/json |
Request Header | authorization | String | Mandatory | Bearer Token. Based on OAuth2 authentication performed in a pre-step. |
Request Header | x-ibm-client-id | String | Mandatory | Token that identifies a client organization. It is provided during onboarding process and must be used in every call. |
Request parameters:
Location | Data Element | Type | Condition | Description |
---|---|---|---|---|
Request Body | info | Info | Mandatory | Object that defines the transaction additional information. |
Request Body.info | customData | customData | Mandatory | Key Value tuple array. |
Request Body.info.customData | key | string | Optional | |
Request Body.info.customData | value | string | Optional | |
Request Body | merchant | merchant | Mandatory | Object that defines a Merchant. |
Request Body.merchant | terminalId | string | Mandatory | Merchant Terminal Identification. Maximum length is 10. |
Request Body.merchant | merchantTransactionId | string | Mandatory | Unique Id used by the Merchant. Maximum length is 35. |
Request Body.merchant | transactionDescription | string | Optional | Merchant Transaction Short Description. Maximum length is 256. |
Request Body | mandate | mandate | Mandatory | Detailed data regarding the existing mandate between creditor and debtor. |
Request Body.mandate | tokenId | string | Mandatory | Token value related to the Mandate Identifier. Maximum length is 35. |
Request Body.mandate | amount | amount | Mandatory | Parameter with the value and currency of the transaction. |
Request Body.mandate.amount | value | number (double) | Mandatory | Amount to be collected. |
Request Body.mandate.amount | currency | currencyCode | Mandatory | Currency used in the transaction. ISO 4217 Alpha-3 Code. |
Request Body.mandate | dueDate | string | Mandatory | Due 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 |
---|---|
INTT | Initiated |
PDNG | Pending |
ACTV | Active |
INCT | Inactive |
SSPN | Suspended |
EXPR | Expired |
CNCL | Cancelled |
RJCT | Rejected |
RFSD | Refused |