API guide — SEPA Transfer lifecycle: initiation, monitoring, and completion

Before you start

This guide walks you through an example of usage of the Memo Bank API – initiate and track a SEPA Credit Transfer.

📑 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. Follow the API Reference | Webhooks to configure them for your API application.

Transfers lifecycle

The transfers API resource represents SEPA Credit Transfers (SCT) and SEPA Instant Credit Transfers (SCT-Inst). Their lifecycle can be summarized as follows:

  • Transfer initiation. A transfer is initiated by the API client, i.e. your application. The transfer is verified and acknowledged by Memo Bank, or rejected if our checks fail.
  • Transfer execution. Transfers management is regulated by the European Payments Council (EPC) for all participating banks. SCT-Inst are executed immediately while SCT may have several execution slots per day. Your application should consider a transfer as done only at this stage.
  • Transfers can be rejected or returned. Banks may reject a transfer before it is credited to your counterparts or return them after it has been settled in some regulated cases.

📑 See our API Reference | Transfers lifecycle for more details.

1. Initiate a SEPA transfer: hands on

You can initiate a SEPA transfer to John Doe from a given account by a POST to https://api.memo.bank/v2/transfers .

POST /v2/transfers HTTP/1.1
Authorization: Bearer ***

{
  "amount": 500,
  "beneficiary_name": "John Doe",
  "beneficiary_iban": "FR7628233000010196123704550",
  "local_iban": "FR7617338000039641754396175",
  "type_strategy": "standard_only",
  "message": "invoice for John",
  "end_to_end_id": "abcd-efgh-123",
  "internal_note": "Monthly fees John",
  "custom_id": "your-123-id",
  "custom_metadata": "{'key': 'your own metadata'}"
}

The local_iban links to the account or the virtual IBAN from which the transfer amount will be debited.

You may want to add a message and/or an end_to_end_id to share with the transfer beneficiary bank. Note that unfortunately it is not possible to control how the beneficiary bank will display this information to your beneficiary.

You may want to include a custom_id and/or custom_metadata . These values are not shared with the beneficiary bank and are only used for your own purposes.

type_strategy field

This optional field may be used to indicate that you want to initiate a SEPA Credit Transfer, a SEPA Instant Credit Transfer, or let Memo Bank decide the fastest strategy.

Note 1: if you decide to initiate a SEPA Instant Credit Transfer ("type_strategy": "instant_only" ) your request may be rejected if the counterparts’ bank has technical issues or does not support instant payments.

Note 2: when using the instant_if_available strategy, Memo Bank will not fallback a failed instant transfer as a standard transfer.

If the previous POST request is accepted by Memo Bank, your system will receive a response similar to the example below:

HTTP 200 OK

{
	"id": "851af2de-332f-434e-b250-220790aff792",
	"reference": "6c465e55-a86a-30c1-a8f9-c41880cf76c7",
	"amount": 500,
	"currency": "EUR",
	"local_iban": "FR7617338000039641754396175",
	"account_id": "cd09799d-2475-4d31-8bd2-11c104733258",
	"beneficiary_iban": "FR7628233000010196123704550",
	"transfer_type": "standard",
	"type_strategy": "standard_only",
	"status": "pending",
	"message": "invoice for John",
	"end_to_end_id": "abcd-efgh-123",
	"internal_note": "Monthly fees John",
	"custom_id": "your-123-id",
	"custom_metadata": "{'key': 'your own metadata'}"
}

The Memo Bank response contains a representation of your transfer request state. The 200 OK

response code indicates that Memo Bank acknowledges your transfer initiation request, while the

"status": "pending" indicates that it is about to be processed.

The id is a unique value that will allows you to the transfer status all along its lifecycle.

📑 See the API Reference | Transfers to have the full list of fields representing a transfer.

2. Transfer lifecycle follow-up

We encourage you to setup a webhooks URL to receive status updates for your initiated transfers in real time.

POST your/webhook.uri HTTP 1.1

{
  "id": "ad8340e7-0675-4182-9c95-520e7c9a72a3",
  "date": "2024-09-27T09:30:00+00:00",
  "event_type": "transfer_confirmed",
  "resource_type": "transfer",
  "resource_id": "851af2de-332f-434e-b250-220790aff792"
}

The resource_id allows you to understand which transfer a webhook notification refers to.

Once a transfer has been correctly executed by Memo Bank, your will receive a notification of type transfer and "event_type": "transfer_confirmed".

sepa transfer lifecycle

You can now consider the transfer as done.

Find more details about the webhooks events structure in the API Reference | webhooks.

GET transfer details

You can retrieve the same information, as well as additional data using GET /transfers/<transfer-unique-id> .

Polling strategy is not recommended. Webhooks eliminate the need for regular polling by enabling you to simply “wait” for a notification when an operation’s status changes.

GET /v2/transfers/851af2de-332f-434e-b250-220790aff792 HTTP/1.1
Authorization: Bearer ***

HTTP 200 OK 

{
	"id": "851af2de-332f-434e-b250-220790aff792",
	"reference": "6c465e55-a86a-30c1-a8f9-c41880cf76c7",
	"amount": 500,
	"currency": "EUR",
	"local_iban": "FR7617338000039641754396175",
	"account_id": "cd09799d-2475-4d31-8bd2-11c104733258",
	"beneficiary_iban": "FR7628233000010196123704550",
	"transfer_type": "standard",
	"type_strategy": "standard_only",
	"status": "confirmed",
	"message": "invoice for John",
	"end_to_end_id": "abcd-efgh-123",
	"internal_note": "Monthly fees John",
	"custom_id": "your-123-id",
	"custom_metadata": "{'key': 'your metadata'}"
}

Errors and idempotency

A transfer 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

If you want to initiate a bulk of trasfers and follow its execution progress, check How to initiate a bulk and follow its execution progress?. You can also refer to our FAQs for more information.