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.

📑 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 mandate statuses. Understanding how our webhooks function is essential for tracking the status of a mandate and managing any necessary follow-up after they have been sent.

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

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 of mandate signature for a SEPA Direct Debit collection.

📑 See our API Reference | Mandate signature requests for more details.

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.

1. Initiate a SEPA mandate signature request: hands on

You can initiate a SEPA mandate signature request with a HTTP POST to: https://api.memo.bank/v2/mandate_signature_requests . In the example below, the mandate signature request will be sent by Memo Bank to Mr. John Doe by email.

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

{
  "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"
}

The debtor_email defines the email address to which the mandate request will be sent.

You can choose the request language using the language field.

The scheme field defines if a Core or B2B mandate will be generated upon signature.

Finally, the reference indicates the Unique Mandate Reference that will be used by the payer to uniquely identify your SEPA Direct Debit collections.

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

HTTP 200 OK
{
	"id": "5c8e54c3-cdc5-4b51-b01c-1bfd5148905c",
	"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",
	"status": "sent",
	"is_deleted": false,
	"language": "french"
}

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

2. Mandate signature follow-up

Each signature request lifecycle can be summarized as follows:

• mandate_signature_request_sent . The signature request email has been sent your counterpart.
• mandate_signature_request_completed . The signature request has been signed.
• mandate_signature_request_expired . The signature request expired before it could be signed. You can renew the request if needed.

SEPA Direct Debit collections can only be initiated when the corresponding mandate has been signed. Memo Bank informs your system about the requests 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 allows you to understand which signature request a webhook notification refers to.

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

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

3. GET mandate signature requests details

You can retrieve a given mandate signature request information using GET /mandate_signature_requests/<request-unique-id> .

Note that the URL resource ID in the example below is the same indicated in the resource_id field of the webhook.

GET /v2/mandate_signature_requests/5c8e54c3-cdc5-4b51-b01c-1bfd5148905c HTTP/1.1
Authorization: Bearer ***

HTTP 200 OK 
{
	"id": "5c8e54c3-cdc5-4b51-b01c-1bfd5148905c", 
	"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",
	"status": "completed",
	"is_deleted": false,
	"language": "french"
}

List all mandate signature requests

You can have a quick overview of all the ongoing signature requests by HTTP GET to /v2/mandate_signature_requests .

Use the status query parameter to filter by the desired status.

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

----------
HTTP 200 OK 
{
	"results": [
		{
			"id": "5c8e54c3-cdc5-4b51-b01c-1bfd5148905c",
			"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",
			"status": "sent",
			"is_deleted": false,
			"language": "french"
		},
		{
			"id": "this-is-another-signature-requestid",
			"reference": "QWERTY123",
			"scheme": "b2b",
			"debtor_email": "jane.doe+testmandate@memo.bank",
			"email_custom_message": "Hi Mrs. Doe, here's another collection mandate to sign.",
			"status": "completed",
			"is_deleted": false,
			"language": "english"
		},
		{
			...
		}
	]
}

The example above shows you that Mr. Doe didn’t sign yet the mandate: the request with id 5c8e54c3-cdc5-4b51-b01c-1bfd5148905c is not completed yet.