API guide — SEPA Direct Debit lifecycle
Before you start
This guide walks you through an example of usage of the Memo Bank API – initiate and track a SEPA Direct Debit collection.
📑 For an in-depth understanding of the Memo Bank API resources and how you can interact with them, take a tour of our Memo Bank API Reference.
API authentication and signature
Each request to the Memo Bank API must be authenticated. See on API Reference | Getting started how to create and manage your API credentials, create and sign your authentication token.
Setup your webhooks
Memo Bank uses webhooks to inform your system on transfer statuses. Understanding how our webhooks function is essential for tracking the status of a collection and managing any necessary follow-up after execution.
📑 Follow the API Reference | Webhooks to configure them for your API application.
Pre-requisite: SDD mandates
In order to collect money via SDD, your must have signed an SDD mandate authorizing you to do so, as defined by the European Payments Council.
In the case of B2B SDD, your debtor will also have to present the signed mandate to his bank, or your collection will risk being refused by the counterparty bank.
If you don’t already have a signed mandate, you can invite your debtor to sign one via Memo Bank.
Schedule a SEPA Direct Debit collection
Make a POST call to the endpoint /v2/collections, specifying at least:
- the amount to be collected in cents,
- the mandate information,
- the scheduled date (in the future),
- the IBAN of your account that should be credited.
We encourage you to always include the mandate information in your request. This way, if the mandate does not exist in your workspace yet, we will automatically add it for you.
{
"amount": 600,
"mandate": {
"reference": "ABC123DEF",
"scheme": "core",
"signature_date": "2022-12-01",
"debtor": {
"name": "John Doe",
"iban": "FR2512739000308553756377J95",
"address": {
"street": "rue de la Boétie",
"building_number": "42",
"postal_code": "75008",
"city": "Paris",
"country": "FR"
},
"scheduled_date": "2024-11-14",
"local_iban": "FR7617338000017890121285329"
}
You may want to add a message and/or an end_to_end_id to share with the counterparty bank.
You may also want to include an internal note , custom_id and/or custom_metadata . These values are not shared with the counterparty bank and are only used for your own purposes.
If your request is valid, we will return a 200 OK response code. The status of the collection is now pending .
{
"id": "5744ac62-8f24-4e79-a65d-f016ad206ed7",
"reference": "35386ea4-7e83-3546-afe5-ffe2491552cf",
"amount": 600,
"currency": "EUR",
"mandate": {
"reference": "RUMB3",
"scheme": "core"
},
"scheduled_date": "2024-11-14",
"local_iban": "FR7617338000017890121285329",
"account_id": "ad6b1f1c-c3a1-4567-8e46-f05528299a8c",
"status": "pending"
}
In the response, you will get the id of the collection which you should store. This will allow your to track the collection throughout its lifecycle. You can also get details of the collection by making a GET call to v2/collections/{id}.
You can also store the reference of the collection. The same reference is used for transactions and collections (see our FAQ on transactions vs. collections).
Follow the collection lifecycle
- Collection scheduled. If the request to initiate a collection is valid, the collection will be scheduled for the date that you specified in your request. The collection status is
scheduled. - Collection confirmed. On the scheduled date, the collection is sent to the clearing house. If everything is in order, and the status becomes
confirmed. - Collection canceled. If you cancel the collection before the execution date, the status will be
canceled. - Collection failed. If there is an issue with your request, the collection status will be
failed. For more information on how to manage these collections, refer to this guide.
📑 See our API Reference | Collections for more details.
Collection scheduled
If you have a webhook setup, we will send a transaction_scheduled event once the collection is validated in our system.
{
"id": "3553d37b-0141-4a07-801f-edd205bd64bc",
"date": "2024-11-13T14:16:26.910514Z",
"event_type": "transaction_scheduled",
"resource_type": "transaction",
"resource_id": "3db15ced-32ff-4ae5-83ce-06d4744829bf"
}
Using the resource_id , you can make a GET call to v2/transactions/{id} to check which collection it is pertaining to by matching the reference with your initial collection.
{
"id": "3db15ced-32ff-4ae5-83ce-06d4744829bf",
"reference": "35386ea4-7e83-3546-afe5-ffe2491552cf",
"account_id": "ad6b1f1c-c3a1-4567-8e46-f05528299a8c",
"amount": 600,
"local_iban": "FR7617338000017890121285329",
"currency": "EUR",
"direction": "credit",
"request_date": "2024-11-13T14:16:26.785383Z",
"execution_date": "2024-11-14T00:00:00Z",
"counterparty_name": "Dunder Mifflin",
"status": "scheduled",
"attachment_count": 0,
"source": {
"local_iban": "FR7617338000017890121285329",
"counterparty_iban": "FR7642559000011234567890121",
"counterparty_bank_bic": "CCOPFRPPXXX",
"collection_id": "5744ac62-8f24-4e79-a65d-f016ad206ed7",
"type": "collection_outgoing"
}
}
Alternatively, to check the status of a collection, you can also make a GET call to v2/collections/{id}, using the id of the collection.
Collection confirmed
On the scheduled date which you defined, Memo Bank will send the collection to the clearing house. Your account will be credited as soon as the next day, or later depending on your plan and setup. We will send a collection_confirmed webhook event.
{
"id": "5bd1c41d-e395-40d4-ae1e-8214a574047b",
"date": "2024-10-30T11:45:19.218138Z",
"event_type": "collection_confirmed",
"resource_type": "collection",
"resource_id": "9e35afb9-d828-4cf4-a26b-2e1191b8211b"
}
Errors and idempotency
Finally, a collection may be rejected if there is any issue with your request, or it can fail in case of network issues. It is very important to follow the API idempotency strategy to safely retry failed requests without accidentally performing the same operation twice. We encourage you to have this implemented as a precondition to production rollout.
Going further
This guide provides more information on how to handle collection failures and returns. If you wish to initiate mandate signatures with Memo Bank, this guide provides a guide on how to start. You can also refer to our FAQ for more information on SDD collections with Memo Bank.