API guide — Initiate and follow up mandate signature requests

Before you start

This guide walks you through an example of usage of the Memo Bank API – initiate and track a SEPA Direct Debit mandate signature request, either by email or from your own onboarding or checkout flow.

📑 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. All the endpoints described in this guide are also available on the sandbox.

API authentication and signature

Each request to the Memo Bank API must be authenticated. See API Reference | Getting started to learn how to create and manage your API credentials, and how to create and sign your authentication token.

Set up your webhooks

Memo Bank uses webhooks to inform your system of the status of your mandate signature requests. Understanding how our webhooks work is essential to track a request and manage any follow-up once it has been sent.

📑 Follow the API Reference | Webhooks to configure them for your API application and find all the details on the structure of webhook events.

SEPA Direct Debit mandate

SEPA Direct Debit (SDD) management is regulated by the European Payments Council (EPC) for all participating banks. Please refer to SEPA Direct Debit lifecycle to understand how to initiate and follow up SDD collections via the Memo Bank API.

The mandate_signature_requests API resource represents a request for the electronic signature of a SEPA Direct Debit mandate by your debtor. Once the request is completed, the signed mandate is stored in your Memo Bank workspace and can be used to initiate collections.

Note: if your system already manages mandate signatures, just include the mandate information in your SEPA Direct Debit requests. A new mandate will be created automatically in your Memo Bank workspace if one doesn’t already exist.

Two delivery modes: email or redirect

The mode field of a signature request defines how the debtor reaches the signature page:

  • email → Memo Bank sends an email to the debtor, with a link to the signature page. Use it when the debtor is not in front of your product, for instance for mandates collected by your sales or finance team.
  • redirect → Memo Bank returns a signature_url. You redirect the debtor to it from your own website or app, and Memo Bank redirects them to your redirect_uri  once the mandate is signed. Use it to keep the debtor in your onboarding, subscription or checkout flow.

Both modes produce the same signed mandate. The mode field was introduced in July 2026: requests created before then are email requests.

1. Initiate a mandate signature request: hands on

You initiate a mandate signature request with an HTTP POST to /v2/mandate_signature_requests. Whatever the mode, the following fields apply:

  • reference is the Unique Mandate Reference that will be used by the payer to identify your SEPA Direct Debit collections;
  • scheme defines whether a Core or B2B mandate will be generated upon signature;
  • debtor_email is the email address of the debtor. It is required in both modes;
  • language  (optional, french by default) sets the language of the email and of the signature page;
  • contract_reference (optional) is metadata attached to the mandate;
  • debtor (optional) prefills the signing form with data you already collected (see below).

1.1 By email

In the example below, the mandate signature request is sent by Memo Bank to Mr. John Doe by email. The email_custom_message field adds your own text to this email.

POST /v2/mandate_signature_requests HTTP/1.1
Content-Type: application/json
Authorization: Bearer ***
Host: api.memo.bank

{
  "mode": "email",
  "reference": "ABC123DEF",
  "scheme": "core",
  "debtor_email": "john.doe+testmandate@memo.bank",
  "email_custom_message": "Hi Mr. Doe, here's a collection mandate to sign.",
  "contract_reference": "CUST-1234",
  "language": "french"
}

If the POST is accepted by Memo Bank, your system receives a response indicating the request id.

HTTP 200 OK
{
  "id": "5c8e54c3-cdc5-4b51-b01c-1bfd5148905c",
  "mode": "email",
  "reference": "ABC123DEF",
  "scheme": "core",
  "debtor_email": "john.doe+testmandate@memo.bank",
  "email_custom_message": "Hi Mr. Doe, here's a collection mandate to sign.",
  "contract_reference": "CUST-1234",
  "language": "french",
  "status": "sent",
  "is_deleted": false
}

The request has been sent  to Mr. Doe’s email address for approval and signature.

1.2 From your own flow (redirect)

With mode set to redirect, the debtor never has to leave your journey to open an email:

  1. Your end user is in your onboarding, subscription or checkout flow;
  2. Your system creates a mandate signature request with mode  set to redirect  and a redirect_uri ;
  3. Memo Bank returns a signature_url ;
  4. You redirect the end user to this URL, where they complete and sign the mandate on a Memo Bank page;
  5. Once the mandate is signed, Memo Bank redirects the end user to your redirect_uri ;
  6. Your system receives the mandate_signature_request_completed  webhook and can start initiating SEPA Direct Debits for this mandate.

The redirect_uri must be an absolute HTTPS URL (2,048 characters maximum). You can include your own identifiers in it, for instance as a query parameter, to recognise the user when they come back. The email_custom_message  field does not apply to this mode.

In the example below, Mrs. Jane Doe has already entered her details in your flow: the debtor  object prefills the signing form with them. All its fields are optional, and the debtor can still edit them before signing. This object is available in both modes.

POST /v2/mandate_signature_requests HTTP/1.1
Content-Type: application/json
Authorization: Bearer ***
Host: api.memo.bank

{
 "mode": "redirect",
 "reference": "QWERTY123",
 "scheme": "core",
 "debtor_email": "jane.doe+testmandate@memo.bank",
 "redirect_uri": "https://example.com/checkout/mandate-signed",
 "contract_reference": "CUST-5678",
 "language": "english",
 "debtor": {
   "name": "Jane Doe",
   "iban": "FR2512739000308553756377J95",
   "address": {
     "street": "rue de la Boétie",
     "postal_code": "75008",
     "city": "Paris",
     "country": "FR"
     }
   }
}

The response contains the signature_url  to redirect Mrs. Doe to.

HTTP 200 OK
{
  "id": "9b1e3a7c-2d4f-4e6a-8c0b-5f7d9e1a3b2c",
  "mode": "redirect",
  "reference": "QWERTY123",
  "scheme": "core",
  "debtor_email": "jane.doe+testmandate@memo.bank",
  "redirect_uri": "https://example.com/checkout/mandate-signed",
  "signature_url": "https://client.memo.bank/mandate/abc123",
  "contract_reference": "CUST-5678",
  "language": "english",
  "status": "sent",
  "is_deleted": false
}

The arrival of the end user on your redirect_uri is not a proof of signature: anyone can open this URL directly, and a redirect can be interrupted. Always rely on the mandate_signature_request_completed webhook, or on a GET on the request, before initiating collections.

2. Mandate signature follow-up

Each signature request lifecycle can be summarized as follows:

  • mandate_signature_request_sent. The signature request has been created and is awaiting signature. In email mode, the email has been sent to your counterpart.
  • mandate_signature_request_completed. The mandate has been signed.
  • mandate_signature_request_expired. The signature request expired before the mandate could be signed. You can renew it if needed (see section 4).
  • mandate_signature_request_deleted. The signature request has been deleted.

SEPA Direct Debit collections can only be initiated once the corresponding mandate has been signed. Memo Bank informs your system of these status changes in real time using webhooks.

POST your/webhook.uri HTTP 1.1
{
  "id": "ad8340e7-0675-4182-9c95-520e7c9a72a3",
  "date": "2024-09-27T09:30:00+00:00",
  "event_type": "mandate_signature_request_completed",
  "resource_type": "mandate_signature_request",
  "resource_id": "5c8e54c3-cdc5-4b51-b01c-1bfd5148905c"
}

The resource_id tells you which signature request a webhook notification refers to.

John Doe has now signed his mandate, which has been generated and stored in your Memo Bank workspace: you can initiate collections for this mandate!

Find more details about the webhook events generated for mandate signature requests in the API Reference | Webhooks.

3. Get a mandate signature request’s details

You can retrieve a given mandate signature request with a GET on /v2/mandate_signature_requests/{id}.

Polling is not recommended to track the status of a mandate signature request. Use webhooks to know when a request has been signed.

Note that the resource ID in the URL below is the same as the one indicated in the resource_id  field of the webhook. Once the request is completed , the response includes the debtor  object as filled in and signed by the debtor.

GET /v2/mandate_signature_requests/5c8e54c3-cdc5-4b51-b01c-1bfd5148905c HTTP/1.1
Authorization: Bearer ***
Host: api.memo.bank
HTTP 200 OK
{
  "id": "5c8e54c3-cdc5-4b51-b01c-1bfd5148905c",
  "mode": "email",
  "reference": "ABC123DEF",
  "scheme": "core",
  "debtor_email": "john.doe+testmandate@memo.bank",
  "email_custom_message": "Hi Mr. Doe, here's a collection mandate to sign.",
  "contract_reference": "CUST-1234",
  "language": "french",
  "status": "completed",
  "is_deleted": false,
  "debtor": {
    "name": "John Doe",
    "iban": "FR7630006000011234567890189",
    "address": {
      "street": "1 rue de Rivoli",
      "postal_code": "75004",
      "city": "Paris",
      "country": "FR"
    }
  }
}

List all mandate signature requests

You can get an overview of your signature requests with a GET on /v2/mandate_signature_requests. Use the status  query parameter to filter by one or more statuses. Results are paginated: pass the next_page_token  of a response as the page_token  query parameter to fetch the next page.

GET /v2/mandate_signature_requests HTTP/1.1
Authorization: Bearer ***
Host: api.memo.bank

HTTP 200 OK

{

  "results": [

{
  "id": "5c8e54c3-cdc5-4b51-b01c-1bfd5148905c",
  "mode": "email",
  "reference": "ABC123DEF",
  "scheme": "core",
  "debtor_email": "john.doe+testmandate@memo.bank",
  "email_custom_message": "Hi Mr. Doe, here's a collection mandate to sign.",
  "contract_reference": "CUST-1234",
  "language": "french",
  "status": "completed",
  "is_deleted": false,
  "debtor": {
    ...
  }
},
{
  "id": "9b1e3a7c-2d4f-4e6a-8c0b-5f7d9e1a3b2c",
  "mode": "redirect",
  "reference": "QWERTY123",
  "scheme": "core",
  "debtor_email": "jane.doe+testmandate@memo.bank",
  "redirect_uri": "https://example.com/checkout/mandate-signed",
  "signature_url": "https://client.memo.bank/mandate/abc123",
  "contract_reference": "CUST-5678",
  "language": "english",
  "status": "sent",
  "is_deleted": false
},
{
  ...
}

  ],

  "next_page_token": "eyJwIjozfQ",

  "prev_page_token": null

}

The example above shows that Mrs. Doe hasn’t signed her mandate yet: the request with id 9b1e3a7c-2d4f-4e6a-8c0b-5f7d9e1a3b2c  is still sent.

4. Renew or delete a request

A request in expired status can be renewed with a POST on /v2/mandate_signature_requests/{id}/renewals.

A request that is no longer needed can be deleted with a DELETE on /v2/mandate_signature_requests/{id}, as long as it is not completed. The mandate_signature_request_deleted event then notifies your system.