API guide — Initiate a bulk and follow its execution progress

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 bulk transfer or direct debit, and managing any necessary follow-up after execution.

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

Bulk vs. Transfers and Direct debits lifecycle

Bulks can be used to initiate a group of transfers or collections. As every other request, a bulk will be received, validated and completed by Memo Bank. A completed bulk does not necessarily mean that all the corresponding operations have been successfully executed.

See our API guides on SEPA Transfers and SEPA Direct Debit collections if you need more details about their specific lifecycle.

Errors and idempotency

A transfer or a collection bulk may be rejected if there is any issue with your request, or it can fail in case of technical issues. Follow the API idempotency strategy to safely retry failed requests without accidentally performing the same operation twice.

1. Initiate and follow up on bulk transfers

When you want to initiate several outgoing transfers, you can use the Memo Bank API bulk transfers endpoint.

Send a POST request to /v2/transfers/bulks containing a set of transfers. You can refer to

SEPA Transfer lifecycle: initiation, monitoring, and completion to review the mandatory information needed for each transfer request.

POST /v2/transfers/bulks HTTP/1.1
Content-Type: application/json
Authorization: Bearer ***
Host: api.integration.memobank.io
Content-Length: 1236

{
  "transfers": [
    {
      "amount": 500,
      "beneficiary_name": "Amos Diggory",
      "beneficiary_iban": "FR7640618802612615881495245",
      "local_iban": "FR7617338000013302336218527",
      "type_strategy": "instant_if_available",
      "message": "invoice 1",
      "end_to_end_id": "b0bfb42baa2642c2af0ca3e880fcd590",
      "internal_note": "phone bill",
      "custom_id": "custom-id-1",
      "custom_metadata": "This is some metadata"
    },
	{
      "amount": 500,
      "beneficiary_name": "Alecto Carrow",
      "beneficiary_iban": "FR7610057195397557811759448",
      "local_iban": "FR7617338000013302336218527",
      "type_strategy": "instant_if_available",
      "message": "invoice 2",
      "end_to_end_id": "b0bfb42baa2642c2af0ca3e880fcd591",
      "internal_note": "phone bill",
      "custom_id": "custom-id-2"
    },
		    {
      "amount": 510,
      "beneficiary_name": "Jim Halpert",
      "beneficiary_iban": "FR7630001007941234567890185",
      "local_iban": "FR7617338000013302336218527",
      "type_strategy": "instant_only",
      "message": "invoice 3",
      "end_to_end_id": "b0bfb42baa2642c2af0ca3e880fcd592",
      "internal_note": "phone bill",
      "custom_id": "custom-id-3"
    }
  ]
}

Upon a succesfull request, the Memo Bank system will reply with a HTTP 200 OK like in the example below:

HTTP 200 OK

{
	"id": "485e0727-c8b7-31b5-aaa9-eab72f9b5bd9",
	"transfers_total": 3,
	"transfers_confirmed": 0,
	"transfers_canceled": 0,
	"transfers_failed": 0,
	"status": "pending"
}

The response above gives you some useful information about the bulk status:

An HTTP 200 OK indicates that your request was acknowledged by Memo Bank. It does not mean that the transfers are done.
The bulk id field can be used to follow-up on the bulk status and its transfers lifecycle.
The bulk pending status informs about the corresponding bulk transfers processing lifecycle.
All transfers are about to be processed, while for the moment there is no transfer confirmed , nor failed or cancelled . These values will eventually change when the bulk will be finalized.

See Create bulk transfers | Memo Bank API documentation to have a full overview of our endpoint for transfers bulk.

Bulk transfers follow-up

You can receive a real time notification about the progress of the bulk on your webhook URL. The resource_id indicates the bulk for which you are receiving a notification.

POST your/webhook.uri HTTP 1.1

{
  "id": "ad8340e7-0675-4182-9c95-520e7c9a72a3",
  "date": "2024-09-27T09:30:00+00:00",
  "event_type": "bulk_transfers_completed",
  "resource_type": "bulk_transfers",
  "resource_id": "485e0727-c8b7-31b5-aaa9-eab72f9b5bd9". <-- Note: this is the bulk id
}

The event_type = bulk_transfers_completed indicates that all transfers have been now processed by Memo Bank, but it does not necessarily mean that all of them were successful.

You can now retrieve the bulk details to verify if all the initiated transfers have the expected status sending a GET request to /v2/transfers/bulks/<bulk id> .

GET /v2/transfers/bulks/485e0727-c8b7-31b5-aaa9-eab72f9b5bd9 HTTP/1.1
Authorization: Bearer ***
Host: api.integration.memobank.io

HTTP 200 OK

{
	"id": "485e0727-c8b7-31b5-aaa9-eab72f9b5bd9",
	"transfers_total": 3,
	"transfers_confirmed": 2,
	"transfers_canceled": 0,
	"transfers_failed": 1,
	"status": "completed"
}

In this example, one of the initiated transfers eventually failed. Based on your business logic, you may want to investigate the reason for the failure and take the most appropriate actions.

Send a GET request to /v2/transfers/bulks/<bulk id>/transfers to review the status of the individual transfers within a given bulk.

GET /v2/transfers/bulks/485e0727-c8b7-31b5-aaa9-eab72f9b5bd9/transfers HTTP/1.1
Authorization: Bearer ***
Host: api.integration.memobank.io

HTTP 200 OK

{
	"results": [
		{
			"id": "24ef0e63-6e84-4d00-b293-4167af5092a9",
			"reference": "e3b117e3-8494-4f91-99c3-81b7b68776f7",
			"amount": 500,
			"currency": "EUR",
			"local_iban": "FR7617338000013302336218527",
			"account_id": "33a6a690-27a4-41d0-8da2-dac0a31fb018",
			"beneficiary_iban": "FR7640618802612615881495245",
			"transfer_type": "instant",
			"type_strategy": "instant_if_available",
			"status": "confirmed",
			"message": "invoice 1",
			"end_to_end_id": "b0bfb42baa2642c2af0ca3e880fcd590",
			"internal_note": "phone bill",
			"custom_id": "custom-id-1",
			"custom_metadata": "This is some metadata"
		},
		{
			"id": "64700795-d94c-4c46-9167-7cf6eca61902",
			"reference": "a6e92d6b-b124-449f-bc48-43282502d9fb",
			"amount": 500,
			"currency": "EUR",
			"local_iban": "FR7617338000013302336218527",
			"account_id": "33a6a690-27a4-41d0-8da2-dac0a31fb018",
			"beneficiary_iban": "FR7610057195397557811759448",
			"transfer_type": "instant",
			"type_strategy": "instant_if_available",
			"status": "confirmed",
			"message": "invoice 2",
			"end_to_end_id": "b0bfb42baa2642c2af0ca3e880fcd591",
			"internal_note": "phone bill",
			"custom_id": "custom-id-2"
		},
		{
			"id": "a24dc7ca-3055-4831-96aa-d62ed68bed3a",
			"reference": "c2b8a794-f7ee-4fe8-b032-33d94936eaea",
			"amount": 500,
			"currency": "EUR",
			"local_iban": "FR7617338000013302336218527",
			"account_id": "33a6a690-27a4-41d0-8da2-dac0a31fb018",
			"beneficiary_iban": "FR7630001007941234567890185",
			"transfer_type": "instant",
			"type_strategy": "instant_only",
			"status": "failed",
			"failure_code": "instant_transfer_not_available",
			"message": "invoice 3",
			"end_to_end_id": "b0bfb42baa2642c2af0ca3e880fcd592",
			"internal_note": "phone bill",
			"custom_id": "custom-id-3"
		}
	],
	"has_prev": false,
	"has_next": false
}

We can see that the third transfer failed, with failure code instant_transfer_not_available .

The initial completed bulk webhook notification indicated that all transfers have been processed, but you needed to review the bulk transfers details to confirm which of them are in confirmed status.

2. Initiate and follow up on bulk direct debit collections

When you want to initiate a group of direct debit collections, you can use the Memo Bank API bulk collections endpoint.

Send a POST request to /v2/collections/bulks containing a set of collections to initiate. You can refer to SEPA Direct Debit lifecycle to review the mandatory information needed for each collection request.

POST /v2/collections/bulks HTTP/1.1
Content-Type: application/json
Authorization: Bearer ***
Host: api.integration.memobank.io
Content-Length: 919

{
  "collections": [
    {
      "amount": 500,
      "mandate": {
        "reference": "RUM348DK",
        "scheme": "core"
      },
      "scheduled_date": "2024-11-21",
      "local_iban": "FR7617338000013302336218527",
      "message": "invoice 1",
      "internal_note": "phone bill John Doe"
    },
		    {
      "amount": 500,
      "mandate": {
        "reference": "PIVERTETASSOCIES-M0077293",
        "scheme": "core"
      },
      "scheduled_date": "2024-11-21",
      "local_iban": "FR7617338000013302336218527",
      "message": "invoice 2",
      "internal_note": "phone bill Fleur Delacour"
    },
		{
      "amount": 500,
      "mandate": {
        "reference": "PIVERTETASSOCIES-M0077297",
        "scheme": "core"
      },
      "scheduled_date": "2024-11-21",
      "local_iban": "FR7617338000013302336218527",
      "message": "invoice 3",
      "internal_note": "phone bill Lee Jordan"
    }
  ]
}

Upon a succesfull request, the Memo Bank system will reply with a HTTP 200 OK like in the example below:

HTTP 200 OK

{
	"id": "701ebfae-4431-3e4d-a072-5b3337b0a7c0",
	"collections_total": 3,
	"collections_confirmed": 0,
	"collections_canceled": 0,
	"collections_failed": 0,
	"status": "pending"
}

The response above gives you some useful information about the bulk status:

An HTTP 200 OK indicates that your request was acknowledged by Memo Bank. It does not mean that the collections are done.
The bulk id field can be used to follow-up on the bulk status and its collections lifecycle.
The bulk pending status informs about the corresponding bulk collections processing lifecycle.
All collections are about to be processed, while for the moment there is no collection confirmed , nor failed or cancelled . These values will eventually change when the bulk will be finalized.

See Create bulk collections | Memo Bank API documentation to have a full overview of our endpoint for transfers bulk.

Bulk collection follow-up

You can receive a real time notification about the progress of the bulk on your webhook URL. The resource_id indicates the bulk for which you are receiving a notification.

POST your/webhook.uri HTTP 1.1

{
  "id": "ad123456-0675-4182-9c95-520e7c9a72a3",
  "date": "2024-09-29T11:30:00+00:00",
  "event_type": "bulk_collections_completed",
  "resource_type": "bulk_collections",
  "resource_id": "701ebfae-4431-3e4d-a072-5b3337b0a7c0". <-- Note: this is the bulk id
}

When the event_type is bulk_collections_completed , all collections have been processed by Memo Bank, but it does not necessarily mean that all of them were successful.

You can retrieve the bulk details to verify if all the initiated collections have the expected status sending a GET request to /v2/collections/bulks/<bulk id> .

GET /v2/collections/bulks/701ebfae-4431-3e4d-a072-5b3337b0a7c0 HTTP/1.1
Authorization: Bearer ***
Host: api.integration.memobank.io

HTTP 200 OK

{
	"id": "701ebfae-4431-3e4d-a072-5b3337b0a7c0",
	"collections_total": 3,
	"collections_confirmed": 3,
	"collections_canceled": 0,
	"collections_failed": 0,
	"status": "completed"
}

Based on your business logic, you may want to check the status of a single collection or investigate the reason for the failure and take the most appropriate actions if not all the collections are in confirmed status.

Send a GET request to /v2/collections/bulks/<bulk id>/collections .

GET /v2/collections/bulks/701ebfae-4431-3e4d-a072-5b3337b0a7c0/collections HTTP/1.1
Authorization: Bearer ***
Host: api.integration.memobank.io

HTTP 200 OK

{
	"results": [
		{
			"id": "fed7b4b8-8231-4115-b773-49b706f7e6c3",
			"reference": "4e673254-7506-4ea9-af91-62a092f54e5e",
			"amount": 500,
			"currency": "EUR",
			"mandate": {
				"reference": "RUM348DK",
				"scheme": "core"
			},
			"scheduled_date": "2024-11-21",
			"local_iban": "FR7617338000013302336218527",
			"account_id": "33a6a690-27a4-41d0-8da2-dac0a31fb018",
			"status": "confirmed",
			"message": "invoice 1",
			"internal_note": "phone bill John Doe"
		},
		{
			"id": "4f29ba77-ed5b-429b-b848-ec37fd6e2196",
			"reference": "d87941a4-2439-43a9-87b2-90e7130a8a16",
			"amount": 500,
			"currency": "EUR",
			"mandate": {
				"reference": "PIVERTETASSOCIES-M0077293",
				"scheme": "core"
			},
			"scheduled_date": "2024-11-21",
			"local_iban": "FR7617338000013302336218527",
			"account_id": "33a6a690-27a4-41d0-8da2-dac0a31fb018",
			"status": "confirmed",
			"message": "invoice 2",
			"internal_note": "phone bill Fleur Delacour"
		},
		{
			"id": "9cc7057e-8dfc-48d0-a245-dd4f19bcc26f",
			"reference": "e1748b5e-7815-43f9-9bf2-d51bc4059e4c",
			"amount": 500,
			"currency": "EUR",
			"mandate": {
				"reference": "PIVERTETASSOCIES-M0077297",
				"scheme": "core"
			},
			"scheduled_date": "2024-11-21",
			"local_iban": "FR7617338000013302336218527",
			"account_id": "33a6a690-27a4-41d0-8da2-dac0a31fb018",
			"status": "confirmed",
			"message": "invoice 3",
			"internal_note": "phone bill Lee Jordan"
		}
	],
	"has_prev": false,
	"has_next": false
}