SDD Mandates API

1. Introduction

1.1. Preface

SDD is a Europe-wide direct debit system that allows merchants to collect Euro-denominated payments from accounts in the 36 SEPA countries and associated territories. SDD has now been implemented in all Eurozone countries and non-Eurozone SEPA countries. In these countries, all Euro-denominated payments must be collected via the SEPA payment scheme.

What is an API?
An Application Programming Interface (API) is a way for two or more apps to communicate with each other. An API is a type of software interface offering a service to other pieces of software. APIs work by sharing data between apps, systems, and devices. This happens through a request and response cycle. A user initiates a request for data by interacting with an app. The request is sent to an API, which retrieves the data and then returns it to a user. A document that describes how to build or use such a connection or interface is called an API specification.

What is SEPA?
SEPA (Single Euro Payment Area) is a system of transactions that was created by the European Union. SEPA harmonises the way in which cashless payments are transacted between Euro countries. Types of SEPA transfers:

SEPA Credit Transfer (SCT) uses an IBAN (International Bank Account Number) and sometimes a BIC (Bank Identifier Code) to transfer money from one bank account to another. A beneficiary obtains the money within a business day after a payment has been received.
SEPA Instant is where money is transferred from one bank account to another in a matter of seconds and does not involve any intermediaries in the process. However, for this function to work, both the sending and receiving banks must be registered as SEPA Instant members.
SEPA Direct Debits (SDD) are an option for recurring payments.

Signed consent and authorisation given by a debtor (merchant’s client) to a creditor (merchant) and to a creditor’s (merchant’s) financial institution to enable:

A creditor to initiate a debit from a debtor’s nominated payment account.
A debtor’s financial institution to comply with such instructions.

A mandate can be issued and signed in paper or electronic format.

Whilst a mandate is a single agreement, it may be triggered several times in its lifetime.

1.2. URLs

It is very important to note that all base URLs are defined by the {baseUrl}.

So, substitute {baseUrl} with one of the base URLs in the table below, depending on the whether the Stage or Production environment is used:

Environment	URL

Environment	URL
Stage	https://mandates-stage.sepagateway.eu
Production	https://mandates.sepagateway.eu

2. Prerequisites & important notes

2.1. Onboarding

In order to use this set of APIs, the merchant must already be onboarded and be in possession of a valid token.

Contact the ISX relationship management team for assistance.

2.2. Character sets

All content is restricted to the Latin character set as defined below:
a b c d e f g h i j k i m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
0 1 2 3 4 5 6 7 8 9
/ - ? : ( ) . , ' +
Space
Content must not start or end with a '/' & must not contain '//'.

3. SDD mandates API endpoints

The SDD Mandates API consists of 5 API endpoints:

API endpoint	Type	Description

API endpoint	Type	Description
/merchant/signup	POST	This API endpoint is used to create a mandate.
/merchant/{mandateID}	GET	This API endpoint is used to identify a mandate for editing or cancelling.
/merchant/cancel	POST	This API endpoint is used to cancel a mandate.
/merchant/list	GET	This API endpoint is used to list all mandates created by a merchant.
/merchant/trigger	POST	This API endpoint is used to execute mandates created by a merchant.

What is an API endpoint?
An API endpoint is a digital location where an API receives requests about a specific resource on its server. An endpoint is typically a uniform resource locator (URL) that provides the location of a resource on the server.

4. Mandate sign up endpoint

This API endpoint is used to create a mandate.

This is a POST endpoint.

4.1. Request

4.1.1. Schema

Field	Data type	Max. length	Mandatory	Comments

Field	Data type	Max. length	Mandatory	Comments
first_name	string	70	yes	The first name of the client.
middle_name	string	70	no	The middle name of the client.
last_name	string	70	yes	The last name of the client.
mobile	string	50	yes	The mobile telephone number of the client.
email	string	200	yes	The email address must include an @ symbol & at least one period. If the ‘Email’ field is completed, then the owner of the email address will be sent an email by the system upon mandate creation, execution & cancellation.
acno	string	34	yes	This value must be a valid IBAN.
residential_address_street_number	string		yes	The street number of the client address.
residential_address_street	string		yes	The street of the client address.
residential_address_city	string		yes	The city of the client address.
residential_address_subdivision	string		no	The province of the client address.
residential_address_country	string		yes	The country of the client address.
residential_address_secondary	string		no	The apartment, suite, etc. of the client address.
residential_address_postal_code	string		yes	The postal code of the client address.
amount	decimal	7	yes	Value must be a whole number (not cents).
currency	string	3	yes	Currently, the value is always “EUR”.
type	string	9	yes	Values: Null, “Frequent”, “Recurring”, “Limited”, “OneOff“.
recurring	string	20	conditional	Currently, the value is always “Monthly”.
debitDate	integer		conditional	Value must be from 1 or 31 inclusive.
identifier	string	50	yes	Refers to a reference of a merchant’s client.
verify	boolean		yes	Values: true or false. If the value is “true“, then open banking verification must be performed in order to verify the account ownership (i.e., authentication).
return_url	string		no	The value is a URL set by a merchant. When an end user has completed the form & clicks the ‘Done’ button, then the system uses the defined URL to redirect the end user.
redirect	boolean		no	Values: true or false. If the value is “false“, then the eMandate UI is not shown, a mandate is created & an API response that a mandate was created is returned.

4.1.2. Sample request body

{
  "client": {
    "first_name": "John",
    "middle_name": "",
    "last_name": "Doe",
    "mobile": "+440000000000",
    "email": "john.doe@mail.com",
    "acno": "LT601010012345678901",
    "residential_address_street_number": "173",
    "residential_address_street": "New Bond Street",
    "residential_address_city": "London",
    "residential_address_subdivision": "",
    "residential_address_country": "United Kindgom",
    "residential_address_secondary": "",
    "residential_address_postal_code": "W1S 4RF"
  },
  "transaction": {
    "amount": 500,
    "currency": "EUR",
    "type": "Limited",
    "recurring": "None",
    "debitDate": 31
  },
  "account": {
    "identifier": "John_Doe_01"
  },
  "verify": true,
  "return_url": "https://www.example.com"
}

With the use of the above JSON script, a user is given very limited control in what can be changed in terms of “transaction“. For allowing a user more flexibility, refer to Section 4.1.3. below for more information.

type
The type field options may be explained as follows:

A Frequent is a fixed amount, with no fixed date.
A Recurring is a fixed amount on a scheduled day (e.g., fixed rent every month).
A Limited is an amount with a max. cap on a scheduled day (e.g., electricity bill, up to a certain amount, every month).
A OneOff is a fixed amount that is scheduled to take place only once.

For more information, peruse the appendix below.

Limited
Regarding the recurring Limited, if the amount due is more than the max. cap, the payment is rejected.

debitDate
Regarding the debitDate field, if the selected day is 29, 30 or 31, then, depending on the month, the system will execute the instruction on the last day of the month if the month ends earlier. For example, if the debitDate field is set to 31 and the current month is April, then the system will execute the instruction on 30 April because April does not have 31 days.

verify
Regarding the verify field, if this field is set to ‘true’, then verification must take place with open banking, otherwise it is skipped.

OneOff
Regarding the OneOff type, the recurring & debitDate fields are not mandatory - they can be null. The mandate & the trigger do not necessarily have to have the same amount - the amount set during the creation of the mandate is the maximum amount & the triggered amount cannot exceed this.

4.1.3. (a) Sample request body

If a merchant wishes to allow a user to choose the type of mandate and fine-tune its associated fields, the “amount“, “type“, “recurring“, and “debitDate“ fields of the JSON must be removed.

{
  "client": {
    "first_name": "John",
    "middle_name": "",
    "last_name": "Doe",
    "mobile": "+440000000000",
    "email": "john.doe@mail.com",
    "acno": "LT601010012345678901",
    "residential_address_street_number": "173",
    "residential_address_street": "New Bond Street",
    "residential_address_city": "London",
    "residential_address_subdivision": "",
    "residential_address_country": "United Kindgom",
    "residential_address_secondary": "",
    "residential_address_postal_code": "W1S 4RF"
  },
  "transaction": {
    "currency": "EUR"
  },
  "account": {
    "identifier": "John_Doe_01"
  },
  "verify": true
}

The currency of the mandate can only be EUR.

If the currency of a mandate is set to anything other than EUR, an error similar to the following results:

{
  "traceId": "00-751133f7786a1d08f7d98fab367",
  "message": "Bad request model",
  "dateTime": "2024-03-28T12:17:07.2403821+02:00",
  "fieldErrors": [
    {
      "field": "Transaction.Currency",
      "errors": [
        "Not valid currency specified"
      ]
    }
  ]
}

4.1.3. (b) Sample request body with no redirect

{
  "client": {
    "first_name": "Joe",
    "middle_name": "",
    "last_name": "Doe",
    "mobile": "+440000000000",
    "email": "joe.doe@mail.com",
    "acno": "MT34CFTE28004000000000000002260",
    "residential_address_street_number": "string",
    "residential_address_street": "string",
    "residential_address_city": "string",
    "residential_address_subdivision": "string",
    "residential_address_country": "Malta",
    "residential_address_secondary": "string",
    "residential_address_postal_code": "string"
  },
  "transaction": {
    "amount": 500,
    "currency": "EUR",
    "type": "Frequent",
    "recurring": "None",
    "debitDate": 31,
    "reference": "string"
  },
  "account": {
    "identifier": "string"
  },
  "verify": false,
  "redirect": false
}

redirect

If any mandatory data is missing from the API (refer to Section 4.1.1. above) or if there is an issue & the “redirect” attribute is set to “false”, then the mandate sign up UI is displayed & descriptions of errors are provided in the validation results tag.
If the “verify” attribute is set to “true” & the “redirect” attribute is set to “false”, then the open banking UI is displayed.
If the “redirect” attribute not provided, then the mandate sign up UI is displayed.

4.2. Response

4.2.1. Schema

Field	Data type	Comments

Field	Data type	Comments
url	string	Used to populate the iFrame of a website.
success	boolean	Values: true or false.
state	string	Values: “Recorded”, “Created”, “Declined“, “Cancelled“ or “Active”. Refer to this link for more information.
mandate_created	boolean	Values: true or false.

Notes

The ‘state' field will only be displayed if the ‘mandate_created’ field is set to ‘true’.
The 'url’ field will only be displayed if the ‘mandate_created’ field is set to ‘false’.

4.2.2. Sample response body

{
  "data": {
    "success": true,
    "state": "Active",
    "mandate_created": true
  }
}

{
   "data": {
      "url": "https://sdd.prod.isx.money/mandate/create?token=eyJhb...",
      "success": true,
      "mandate_created": false,
      "validationResult": {
         "traceld": "00-c5d87...",
         "message": "Bad request model",
         "dateTime": "2024-12-05T10:28:33.8556166+02:00",
         "fieldErrors": [
            {
               "field": "Client.Acno",
               "errors": [
                  "IBAN is not valid: BBAN_LENGTH"
               ]
            }
         ]
      }
   }
}

url
A Uniform Resource Locator (url), or a web address, is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. A URL is a specific type of Uniform Resource Identifier. The url field is used to populate the iFrame in the merchant’s website.

4.2.3. Request URL

https://{baseUrl}/merchant/signup

5. Mandate ID endpoint

This API endpoint is used to identify a mandate for editing or cancelling.

This is a GET endpoint.

5.1. Request

5.1.1. Parameter

Field	Data type	Max. length	Mandatory	Comments

Field	Data type	Max. length	Mandatory	Comments
mandateId	string	35	yes	The ID of the mandate e.g., LTLND-202403-00000055.

mandateID
The mandateID is used to be able to edit or cancel a mandate.

5.2. Response

5.2.1. Schema

Field	Data type	Comments

Field	Data type	Comments
url	string	Used to populate the iFrame of a website.
success	boolean	Values: true or false.
state	string	Values: “Recorded”, “Created”, “Declined“, “Cancelled“ or “Active”. Refer to this link for more information.
mandate_created	boolean	Values: true or false.

5.2.2. Sample response body

{
  "data": {
    "url": "https://sdd.prod.isx.money/mandate/edit?token=eyJhb...",
    "success": true,
    "state": "Active",
    "mandate_created": true
  }
}

url
A Uniform Resource Locator (url), or a web address, is a reference to a web resource that specifies its location on a computer network and a mechanism for retrieving it. A URL is a specific type of Uniform Resource Identifier. The url field is used to populate the iFrame in the merchant’s website.

5.2.3. Request URL

https://{baseUrl}/merchant/

The parameter is added to the end of the request URL: https://{baseUrl}/merchant/LTLND-202403-00000055

6. Mandate cancel endpoint

This API endpoint is used to cancel a mandate.

This is a POST endpoint.

6.1. Request

6.1.1. Schema

Field	Data type	Max. length	Mandatory	Comments

Field	Data type	Max. length	Mandatory	Comments
mandateID	string	35	yes	The ID of the mandate e.g., LTLND-202403-00000055.
reference	string	35	yes
identifier	string	50	yes	Refers to a reference of a merchant’s client.

6.1.2. Sample request body

{
  "transaction": {
    "mandateid": "LTLND-202403-00000055",
    "reference": ""
  },
  "account": {
    "identifier": "John_Doe_01"
  }
}

6.2. Response

6.2.1. Schema

Field	Data type	Comments

Field	Data type	Comments
mandateID	string	The ID of the mandate e.g., LTLND-202403-00000055.
cancelled	boolean	Values: true or false.

6.2.2. Sample response body

{
  "data": {
    "mandateId": "LTLND-202403-00000055",
    "cancelled": true
  }
}

6.2.3. Request URL

https://{baseUrl}/merchant/cancel

7. List of mandates endpoint

This API endpoint is used to list all mandates created by a merchant.

This is a GET endpoint.

7.1. Request

7.1.1. Parameters

Field	Data type	Max. length	Mandatory	Comments

Field	Data type	Comments
SortOrder	string	Values: Asc or Desc.
SortBy	string	Currently, the only option is “Created”.
MandateId	string	The ID of the mandate e.g., LTLND-202403-00000055.
StartDate	string	Format: yyyy-mm-dd.
EndDate	string	Format: yyyy-mm-dd.
State	string	Values: Null, Recorded, Created, Declined, Cancelled or Active. Refer to this link for more information.
Page	integer
RowsPerPage	integer

7.2. Response

7.2.1. Schema

Field	Data type	Max. length	Mandatory	Comments

Field	Data type	Max. length	Comments
mandateID	string	35	The ID of the mandate e.g., LTLND-202403-00000055.
reference	string	35
amount	number		Value is from 0.01 or 1000000 inclusive.
currency	string	3	Currently, the value is always “EUR”.
debitDate	integer		Value is from 1 or 31 inclusive.
debtorIBAN	string	50	The debtor’s IBAN, which is a valid IBAN.
created	string		Format: yyyy-mm-dd.
recurring	string		Currently, the value is always “Monthly”.
type	string		Values: Null, “Frequent”, “Recurring” or “Limited”.
status	string		Values: “Recorded”, “Created”, “Declined“, “Cancelled“ or “Active”. Refer to this link for more information.
page	integer
pageSize	integer
totalItems	integer
totalPages	integer

7.2.2. Sample response body

{
  "items": [
    {
      "mandateId": "LTLND-202403-00000055",
      "reference": "",
      "amount": 500,
      "currency": "EUR",
      "debitDate": 31,
      "debtorIBAN": "LT601010012345678901",
      "created": "2024-03-19T12:31:08.995Z",
      "recurring": "None",
      "type": "Limited",
      "status": "Recorded"
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 50,
    "totalItems": 1,
    "totalPages": 1
  }
}

7.2.3. Request URL

https://{baseUrl}/merchant/list

The parameters are added to the end of the request URL: https://{baseUrl}/merchant/list?SortOrder=Desc&SortBy=Created&StartDate=2024-03-21&EndDate=2024-03-21&Page=1&RowsPerPage=50

8. Mandate trigger endpoint

This API endpoint is used to execute mandates created by a merchant.

This is a POST endpoint.

The mandate trigger endpoint works with the Frequent and Limited mandate types only.
The mandate trigger endpoint does NOT work with the Recurring mandate type.

8.1. Request

8.1.1. Parameters

Field	Data type	Max. length	Mandatory	Comments

Field	Data type	Max. length	Mandatory	Comments
amount	number	7	yes	Value must be from 0.01 or 1000000 inclusive or can be null.
currency	string	3	yes	Currently, the value is always “EUR”.
mandateid	string	35	yes	The ID of the mandate e.g., LTLND-202403-00000055.
reference	string	35	yes
identifier	string	50	yes	Refers to a reference of a merchant’s client.

8.1.2. Sample response body

{
  "transaction": {
    "amount": 500,
    "currency": "EUR",
    "mandateid": "LTLND-202403-00000055",
    "reference": ""
  },
  "account": {
    "identifier": "John_Doe_01"
  }
}

8.2. Response

8.2.1. Schema

Field	Data type	Comments

Field	Data type	Comments
success	boolean	Values: true or false.
failReason	string

8.2.2. Sample response body

{
  "data": {
    "success": true,
    "failReason": "string"
  }
}

8.2.3. Request URL

https://{baseUrl}/merchant/trigger

9. HTTP status codes

The above endpoints will return HTTP status codes after processing.

HTTP status codes are classified as follows:

HTTP status code range	Description

HTTP status code range	Description
100-199	Informational responses
200-299	Successful responses
300-399	Redirection messages
400-499	Client error messages
500-599	Server error messages

In the event that any of the above endpoints return error codes, refer to this link for more information.

10. Mandate states

The mandate states are classified as follows:

State	Description

State	Description
Cancelled	Mandate has been cancelled. Mandate cannot be triggered and/or edited.
Active	Mandate has been set up & active. Mandate can be edited and/or cancelled.
Declined	Mandate has been declined. Mandate cannot be triggered and/or edited.
Created	Mandate has been created, but pending activation. Mandate can be edited and/or cancelled.
Recorded	Mandate has been recorded on the database, but has not been processed yet.

11. SIIN for SDD

SIIN
SEPA Instant Instant Notification (SIIN) is basically additional information/notification(s) of SEPA inbound transactions.

SIIN notifications for SDD are described here.

Appendix: Mandate types

Type	Description	Duration	Unique attributes	Example

Type	Description	Duration	Unique attributes	Example
Frequent	Allow monthly limit with multiple ad hoc debits within a month as long as it does not exceed the limit.	Monthly	Multiple ad hoc debits. No fixed date within a month. End user triggers.	End user signs up to betting site & has fixed mandate of €250 per month to use. User buys lottery ticket today, buys lottery ticket in 4 days & buys lottery ticket in 2 weeks. Every end/start of month, limit is reset & user can do another €250.
Recurring	Allow monthly single fixed amount to be debited within a month on fixed date only once.	Monthly	Single fixed debit on fixed date within a month. No involvement of merchant.	End user signs mandate to pay Netflix bill monthly. They know amount is fixed at €14.95. They set mandate to be automatically executed on 20^th of each month.
Limited	Allow monthly limit with a single ad hoc debit within a month only once. It cannot exceed limit & can only be triggered by a merchant up to a mandate date.	Monthly	Single ad hoc debit. Fixed date within a month to execute by a merchant. Merchant must trigger.	End user signs mandate to pay electricity bill. They set mandate that EAC must debit their account until 25^th of month otherwise it will fail. User also set a limit of €350 on mandate so EAC cannot exceed this limit. EAC can only trigger this mandate once. If amount is more than limit, then mandate will not be triggered.
OneOff	A fixed amount that is scheduled to take place only once.	No monthly limit renewal	After it is executed successfully, then the mandate is cancelled regardless if the transfer is successful or rejected. The mandate is cancelled immediately after the first trigger event or it expires after 36 months if the mandate is not triggered.