SEPA Direct Debit

Introduction

SEPA (Single Euro Payments Area) Direct Debit is a bank transfer-based payment method designed for the European market. It allows merchants to collect payments directly from customers’ bank accounts across SEPA member countries. By leveraging standardized payment processes, SEPA ensures efficient, cross-border transactions that feel as seamless as domestic payments.

SEPA Direct Debit supports one-off payments and recurring transactions, such as subscriptions. Customers authorize merchants to debit their accounts through a mandate, which serves as a legally binding agreement and guarantees regulatory compliance. This payment method is available in all SEPA-member countries and supports payments in EUR, offering a convenient solution for both businesses and customers.

Workflows and Transaction Types

SmartPay Integration Flow for Merchants

Merchants integrating SEPA Direct Debit should follow these steps:

Integration Prerequisites: Set up the testing and production environments, ensure compliance with SEPA regulations, and acquire API credentials.
Create Checkout API: Use this API to create checkout sessions that include SEPA as a payment option. The API ensures seamless collection of mandate details during the transaction.
Checkout Web SDK: Leverage the Web SDK to implement SEPA Direct Debit in web applications, including secure data collection for mandate creation.
Android SDK and iOS SDK: Integrate SEPA payment flows into mobile apps with built-in support for mandate collection and buttons.

Customer-Initiated Transactions (CIT)

Guest Payments: Customers can complete one-time payments without saving their bank account details.
Registered Users: Customers can securely save their bank details for future transactions.

Merchant-Initiated Transactions (MIT)

Subscriptions: Merchants can set up recurring billing schedules based on the mandate agreement. Payments are automatically initiated based on the subscription plan.
Stored Payment Options (SPO): Bank details are securely stored under the mandate, enabling seamless future payments.

Mandate Management

Merchants must handle mandates efficiently using SmartPay's SEPA Mandate Management API which supports creating and updating mandates, retrieving mandate details and cancelling mandates when services are terminated.

SEPA DD Stored Payment Options

SmartPay supports SEPA Direct Debit (SEPA DD) as a payment method for merchants who need to process recurring or one-time direct debit payments. SEPA DD transactions require a mandate agreement from the customer, which must be stored and referenced within SmartPay’s Stored Payment Options (SPO) system. This allows merchants to handle SEPA payments efficiently while maintaining compliance with SEPA regulations.

info

When managing SEPA DD payment details, additional mandate-related data is included in the request and response payloads. The "additionalData" placement varies between API responses but is consistent across create and update operations.

For new SEPA DD payment options added via the Add SPO endpoint, the "additionalData" field appears within "paymentOptionData", which is nested within "processedData". The "additionalData" field within the "paymentOptionData" object contains supplementary details related to SEPA Direct Debit mandates. These fields store critical mandate information such as creditor details, mandate references, and status, which are required for SEPA Direct Debit transactions.

When an existing SEPA DD payment option is updated via Update SPO endpoint, the "additionalData" field moves to the root level of "processedData".

info

This structural difference ensures that mandate modifications can be handled separately from the core payment option details.

In the context of SEPA Direct Debit, this update allows merchants to make changes to mandate-related details associated with the payment option. In the previous example for Add Stored Payment Option, SEPA DD "additionalData" was stored within "paymentOptionData" when adding a stored payment option. This is because at this stage, the payment option is being registered within the system along with its associated attributes, including mandate information. However, when updating an SPO, the "additionalData" field is now stored under "processedData" instead of "paymentOptionData". The update process primarily modifies attributes related to the SPO rather than redefining the entire payment option.

SPO Operation	Location of "additionalData"
Add SPO	`processedData.paymentOptionData.additionalData`
Update SPO	`processedData.additionalData`

important

Understanding this distinction is crucial for proper integration, ensuring that SEPA mandates are stored correctly when adding a new SPO and updated separately when modifying an existing one.

{
  "name": "SEPA Direct Debit B2B",
  "code": "SEPADDB2B", //Or "SEPADDCORE"
  "carrierNumber": "DE******",
  "reference": "U861vQBGPgSn8iPeNfGH5",
  "isDefault": false,
  "isExpired": false,
  "expiresSoon": false,
  "expiryDate": "12/2999",
  "additionalData": [
    {
      "name": "dd.creditorName",
      "value": "J.P. Morgan Mobility Payments Solutions"
    },
    {
      "name": "dd.creditorIdentifier",
      "value": "LU11ZZZ0000000000000001491"
    },
    {
      "name": "dd.creditorAddressCity",
      "value": "Munich"
    },
    {
      "name": "dd.creditorAddressCountryCode",
      "value": "DE"
    },
    {
      "name": "dd.creditorAddressNumber",
      "value": "456"
    },
    {
      "name": "dd.creditorAddressLine1",
      "value": "Leopoldstr."
    },
    {
      "name": "dd.creditorPostCode",
      "value": "80807"
    },
    {
      "name": "dd.mandateStatus",
      "value": "ACTIVE"
    },
    {
      "name": "dd.mandateReference",
      "value": "HM3BY4H***V4F5SQDXYZD5"
    },
    {
      "name": "dd.mandateDateOfSignature",
      "value": "2021-02-23"
    },
    {
      "name": "dd.mandateId",
      "value": "224e1e25-12d5-4015-8d18-64383a14d50e"
    },
    {
      "name": "dd.mandateVersionTag",
      "value": "0001"
    },
    {
      "name": "dd.debtorBankName",
      "value": "Banca Frencesa new"
    },
    {
      "name": "dd.debtorBankBic",
      "value": "PSSTFRPPNEW"
    }
  ]
}

SEPA DD Additional Data Parameters

important

Our APIs provide responses containing a variety of parameters that may change depending on the endpoint you're trying to reach. Each payment option can have distinct fields, and understanding these variations is essential for proper integration.

Name	Description	Type	Max Length
additionalData	A list of "name" and "value" pairs.	Array	-
- dd.creditorName	Name of the creditor created in the mandate.	String	70
- dd.creditorIdentifier	Creditor ID created in the mandate.	String	35
- dd.creditorAddressCity	City in creditor address created in the mandate.	String	35
- dd.creditorAddressCountryCode	Country code of the creditor's address.	String	2
- dd.creditorAddressNumber	Address number of the creditor's address.	String	10
- dd.creditorAddressLine1	Address line 1 of the creditor's address.	String	60
- dd.creditorPostCode	Postcode of the creditor's address.	String	10
- dd.merchantName	Name of the merchant in the mandate.	String	30
- dd.mandateStatus	Possible values: CREATED: Mandate created and not activated. ACTIVE: Mandate active and can be used for payments. CLOSED: Mandate is either canceled, used or expired.	String	-
- dd.mandateReference	Reference number for the mandate.	String	35
- dd.mandateDateOfSignature	Date of signature of B2B or CORE mandate.	String	70
- dd.mandateId	Mandate ID.	String	39
- dd.mandateVersionTag	Version tag of the mandate.	String	4
- dd.debtorBankName	Debtor Bank Name from Create Mandate API.	String	70
- dd.debtorBankBic	Debtor Bank Bic from Create Mandate API.	String	11

info

These "name/value pairs" represent SEPA-specific mandate attributes that can be included in "additionalData" and it in turn help SmartPay manage SEPA Direct Debit transactions efficiently by storing relevant mandate information within the payment option.

Transaction Status Flow

Merchants should implement SmartPay notifications to receive transaction status updates. Upon receiving a notification, merchants must call the Get Payment Status API to verify the transaction status.

Communication with the Customer

Effective communication ensures a smooth payment experience for customers, for example, in case of refunds and disputes. SEPA mandates provide customers with a refund mechanism. Merchants should clearly outline refund policies and provide support for dispute resolution.

SEPA Test Data

SEPA Bank Accounts

IBAN	SWIFT / BIC	Country	Result
DE89370400440532013000	COBADEFFXXX	Germany	Success
DE72710900000147433891	GENODEF1BGL	Germany	Success
DE75512108001245126199	SOGEDEFFXXX	Germany	Success
MT84MALT011000012345MTLCAST001S	MALTMTMT	Malta	Success
FR1420041010050500013M02606	PSSTFRPPLIL	France	Success
PL61109010140000071219812874	WBKPPLPPXXX	Poland	Success
IT60X0542811101000000123456	BLOPIT22	Italy	Success
ES9121000418450200051332	CAIXESBBXXX	Spain	Success
AT483200000012345864	RLNWATWWXXX	Austria	Success

Introduction​

Workflows and Transaction Types​

SmartPay Integration Flow for Merchants​

Customer-Initiated Transactions (CIT)​

Merchant-Initiated Transactions (MIT)​

Mandate Management​

SEPA DD Stored Payment Options​

SEPA DD Additional Data Parameters​

Transaction Status Flow​

Communication with the Customer​

SEPA Test Data​

Introduction

Workflows and Transaction Types

SmartPay Integration Flow for Merchants

Customer-Initiated Transactions (CIT)

Merchant-Initiated Transactions (MIT)

Mandate Management

SEPA DD Stored Payment Options

SEPA DD Additional Data Parameters

Transaction Status Flow

Communication with the Customer

SEPA Test Data