openapi: 3.1.0
info:
title: Memo Bank API
description: |
**Welcome!** You can use our [Premium Bank API](https://memo.bank/produit/api/) to check your company’s accounts, fetch your transactions, make SEPA transfers, initiate SEPA direct debit collections, create virtual IBANs, and access most of Memo Bank features.
> info
> If you are a **third-party payment service provider** complying with PSD2, you may be more interested in our [NextGenPSD2 API](https://docs-nextgenpsd2.api.memo.bank).
version: "2.0"
servers:
- url: https://api.memo.bank
description: Production
- url: https://api.sandbox.memo.bank
description: Sandbox
tags:
- name: Accounts
description: |
Accounts are any bank account that your company owns: current account, ring-fenced account, settlement account, specially dedicated account, trust account, meal voucher account, booster account, etc. They boil down to a list of [transactions](#endpoint-transactions) and a balance.
- name: IBANs
description: |
IBANs are identifiers for bank accounts. There are two types of IBANs at Memo Bank:
* Main IBANs, which act as primary identifiers for a bank account. There is exactly one main IBAN per bank account. You cannot delete it. When an account is closed, its main IBAN remains active only for incoming transactions, which will be automatically rerouted to the main account.
* Virtual IBANs, which are aliases for the main IBAN. They can be created, deactivated, and reactivated at will. When the account they are attached to is closed, they get reattached to the main account.
All operations on IBANs are synchronous and effective immediately, meaning that you can use a new IBAN to send or receive money right after its creation.
- name: Account assessments
description: |
Account assessments allow you to assess SEPA counterparty accounts before initiating transactions with them. An assessment provides:
* **Risk indicators**: Detection of fraudulent activity, suspicious patterns, and other risk signals.
* **Identification matching**: Verify that the account name or other identifiers match the value known by the account holder.
* **Account reachability**: Information about which payment schemes are supported by the account holder.
Account assessments are processed asynchronously: you need to listen to `account_assessment_completed` and `account_assessment_failed` webhook events to know when its time to retrieve the assessment results.
This feature is subject to specific pricing, please reach out to your banker to get more information.
- name: Transactions
description: |
Transactions are any debit and credit operations on an account.
<img src="https://assets.memo.bank/memobankapi/transactions-lifecycle-api-v2.png" alt="Transactions lifecycle" width="750">
Note that the status of the transaction indicates whether or not it affects the account’s available balance. `debit` transactions impact the balance as soon as they reach the `authorized` state. `credit` transactions impact it only when their status turns to `confirmed`.
- name: Transfers
description: |
Transfers are transfers within the SEPA-zone, including SEPA standard transfers, SEPA instant transfers and Target 2 transfers.
They can be initiated asynchronously, one by one or in bulk.
They have a similar lifecycle compared to [transactions](#endpoint-transactions) but note that there are some minor differences for the `canceled` and `failed` states.
<img src="https://assets.memo.bank/memobankapi/transfers-lifecycle-api-v3.png" alt="Transfers lifecycle" width="750">
- name: Wire Transfers
description: "Wire transfers are transfers going through Swift. They allow you to\
\ send funds outside the SEPA network and to transfer money in foreign currencies.\n\
\nInitiating a wire transfer may require you to upload a supporting document.\
\ In such case the transfer will have a `pending_attachment_required` status and\
\ you'll receive an event `wire_transfer_attachment_required` on your webhook.\
\ \n\nIf no document is required but you still want to attach one to your transaction,\
\ use the [attachments](#endpoint-attachments) endpoints.\n\n<img src=\"https://assets.memo.bank/memobankapi/wire-transfers-lifecycle-api-v1.png\"\
\ alt=\"Wire transfers lifecycle\" width=\"750\">\n"
- name: Collections
description: "Collections are SEPA direct debit collections, including SEPA CORE\
\ direct debits and SEPA B2B direct debits. \n\nTo initiate a direct debit, a\
\ **mandate** signed by the debtor is required. You have the option to use our\
\ [signature request](endpoint-mandate-signature-requests) workflow, which handles\
\ this signature, or you can choose to manage it yourself. Whichever method you\
\ select, you will only need to provide the mandate information when setting\
\ up the direct debit, not the signed document itself.\n\nThey can be initiated\
\ asynchronously, one by one or in bulk. \n\nUnlike [transfers](#endpoint-transfers),\
\ collections can only be scheduled for a date in the future. As a result, their\
\ lifecycle is also simplified.\n\n<img src=\"https://assets.memo.bank/memobankapi/collections-lifecycle-api-v3.png\"\
\ alt=\"Collections lifecycle\" width=\"750\">\n"
- name: Mandate signature requests
description: |
Mandate signature requests are a way to prepare and send collection mandates for signature. The mandate debtor receives an email with a link so they can complete and sign the mandate. Once it has been signed, the resulting mandate becomes immediately available for making [collections](#endpoint-collections). Dedicated [webhook events](#webhook-webhook) can be used to track mandate signature requests state changes.
- name: Attachments
description: |
Documents attached to transactions.
- name: Users
description: |
The members of your Memo Bank workspace.
- name: Webhook
description: |
# Events
When something interesting happens on your Memo Bank workspace, such as a new transaction being created, Memo Bank can reach out to your application so that you can take action (such as sending an e-mail alert about the transaction to your user) automatically.
The first step is to add a webhook to your application in the [`API`](https://client.memo.bank/api) section of your Memo Bank workspace. As part of this, you will have to provide a URL on your own servers. Memo Bank will then send HTTPS requests to that URL when there is an activity on your Memo Bank workspace.
Note that even if webhooks are setup within an application, events will be received even when they result from actions triggered on the Memo Bank webapp or any other application.
# Consuming events
Individual events do not contain very much information on their own. This is by design, as the API structure can remain extremely stable and avoid difficult webhook migrations in the future as the Memo Bank API changes. If you need additional metadata, such as the amount of the transaction in the above example, make a `GET` request to the API for that information. You can use the `resource_type` and `resource_id` to determine what resource to fetch from the API.
# Failures and retries
If your application returns anything other than a 2xx HTTP status code, if we do not receive a response before timing out or in the case of a network failure, we will retry the event up to 8 times with exponentially increasing backoffs. In your webhook endpoint implementation, we recommend you place inbound Events into your application's own queuing system (such as Kafka, Resque, etc) for asynchronous event processing, and returning a 200 response from your endpoint as quickly as possible.
Since retries may occur, your webhook endpoint must be idempotent. You should handle the possibility of receiving the same event multiple times. We recommend using the event `id` field to detect and ignore duplicate events on your side.
# Securing your webhook endpoint (recommended)
Memo Bank will include an `Authorization` header in each webhook request. Inside of it, you will find `Bearer <token>` with the authentication token we provided when you created the webhook on the web interface. We recommend that you check this header and reject requests with invalid token, indicating a malicious request that would not have been issued by Memo Bank.
We also recommend that you restrict which IP addresses can call your webhook. Here is the list of our IPv4 addresses:
* Memo Bank Premium API (i.e. `api.memo.bank`):
* `34.38.96.206`
* `35.189.206.171`
* `35.241.129.224`
* `34.155.214.185`
* `34.155.206.98`
* `34.163.14.38`
* Memo Bank Premium Sandbox API (i.e. `api.sandbox.memo.bank`):
* `34.155.60.111`
* `34.163.27.39`
- name: Webhooks
description: |
Manage webhooks for your application. Webhooks allow you to receive real-time notifications when events occur on your Memo Bank workspace.
Please refer to the [Webhook](https://docs.api.memo.bank/group/webhook-webhook) section for more information.
- name: Sandbox
description: |
Sandbox only endpoints.
paths:
/v2/account_assessments:
post:
tags:
- Account assessments
summary: Create an account assessment
description: |-
This endpoint allows you to assess a SEPA counterparty account by retrieving risk and fraud indicators, account capabilities and by performing IBAN and name/identification matching.
**Scope**: `account-assessments:write`
operationId: createAccountAssessment
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateAccountAssessment"
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/PendingAccountAssessment"
security:
- JWT: []
/v2/account_assessments/{id}:
get:
tags:
- Account assessments
summary: Get an account assessment
description: "**Scope**: `account-assessments:read`"
operationId: getAccountAssessment
parameters:
- name: id
in: path
description: ID of the account assessment.
required: true
schema:
type: string
format: uuid
example: 61ccd037-8d95-4856-89e7-b043fb84ca26
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
discriminator:
propertyName: status
mapping:
pending: "#/components/schemas/PendingAccountAssessment"
completed: "#/components/schemas/CompletedAccountAssessment"
failed: "#/components/schemas/FailedAccountAssessment"
oneOf:
- $ref: "#/components/schemas/PendingAccountAssessment"
- $ref: "#/components/schemas/CompletedAccountAssessment"
- $ref: "#/components/schemas/FailedAccountAssessment"
security:
- JWT: []
/v2/accounts/{id}:
get:
tags:
- Accounts
summary: Get an account
description: "**Scope**: `accounts:read`"
operationId: getAccount
parameters:
- name: id
in: path
description: ID of the account.
required: true
schema:
type: string
format: uuid
example: c70bd7bc-58e0-4fdb-8c1f-70186e0de587
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Account"
security:
- JWT: []
/v2/accounts:
get:
tags:
- Accounts
summary: List all accounts
description: "**Scope**: `accounts:read`"
operationId: listAccounts
parameters:
- name: page
in: query
description: "Index of the requested page. Deprecated, use `page_token` instead."
deprecated: true
schema:
minimum: 1
type: integer
format: int32
- name: page_token
in: query
description: "Token used to fetch a specific page, as returned by the `next_page_token`\
\ or `prev_page_token` field of a previous response. Mutually exclusive\
\ with `page`."
schema:
type: string
- name: size
in: query
description: Number of elements per page in response.
schema:
maximum: 100
minimum: 1
type: integer
format: int32
default: 10
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/AccountPage"
security:
- JWT: []
/v2/attachments:
get:
tags:
- Attachments
summary: List all attachments
description: "**Scope**: `attachments:read`"
operationId: listAttachments
parameters:
- name: transaction_id
in: query
description: Filter attachments by transaction.
schema:
type: string
format: uuid
example: 29883c3d-0b11-4c38-91b0-af9018cc5b14
- name: include_deleted
in: query
description: "When set to true, results will include attachments that have\
\ been deleted."
schema:
type: boolean
default: false
- name: page
in: query
description: "Index of the requested page. Deprecated, use `page_token` instead."
deprecated: true
schema:
minimum: 1
type: integer
format: int32
- name: page_token
in: query
description: "Token used to fetch a specific page, as returned by the `next_page_token`\
\ or `prev_page_token` field of a previous response. Mutually exclusive\
\ with `page`."
schema:
type: string
- name: size
in: query
description: Number of elements per page in response.
schema:
maximum: 100
minimum: 1
type: integer
format: int32
default: 10
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/AttachmentPage"
security:
- JWT: []
post:
tags:
- Attachments
summary: Create an attachment
description: |-
This operation allows you to upload and attach a document to a transaction.
**Scope**: `attachments:write`
operationId: createAttachment
requestBody:
content:
multipart/form-data:
schema:
required:
- document
- transaction_id
type: object
properties:
document:
type: string
format: binary
transaction_id:
type: string
description: ID of the transaction the document will be attached
to.
format: uuid
example: 3439bd9a-077a-4c02-8bd7-f14eadf8975b
responses:
"201":
description: Created
content:
application/json:
schema:
$ref: "#/components/schemas/Attachment"
security:
- JWT: []
/v2/attachments/{id}:
get:
tags:
- Attachments
summary: Get an attachment
description: |-
This operation uses content negotiation to request either a JSON representation of the attachment, or the actual document. Check the OpenAPI specification for more details.
**Scope**: `attachments:read`
operationId: getAttachment
parameters:
- name: id
in: path
description: ID of the attachment.
required: true
schema:
type: string
format: uuid
example: c70bd7bc-58e0-4fdb-8c1f-70186e0de587
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Attachment"
application/octet-stream:
schema:
type: string
format: binary
security:
- JWT: []
delete:
tags:
- Attachments
summary: Delete an attachment
description: "**Scope**: `attachments:write`"
operationId: deleteAttachment
parameters:
- name: id
in: path
description: ID of the attachment.
required: true
schema:
type: string
format: uuid
example: c70bd7bc-58e0-4fdb-8c1f-70186e0de587
responses:
"204":
description: No content
security:
- JWT: []
/v2/collections/{id}:
get:
tags:
- Collections
summary: Get a collection
description: "**Scope**: `collections:read`"
operationId: getCollection
parameters:
- name: id
in: path
description: ID of the collection.
required: true
schema:
type: string
format: uuid
example: 45195a6f-daa8-4bc1-9ac4-3979e72bd89d
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Collection"
security:
- JWT: []
delete:
tags:
- Collections
summary: Cancel a SEPA Direct Debit collection
description: |-
This endpoint allows you to cancel a SEPA Direct Debit collection before it has been submitted.
Concretely a collection can only be canceled while in `scheduled` state.
**Scope**: `collections:write`
operationId: cancelCollection
parameters:
- name: id
in: path
description: ID of the collection.
required: true
schema:
type: string
format: uuid
example: 45195a6f-daa8-4bc1-9ac4-3979e72bd89d
responses:
"200":
description: OK
security:
- JWT: []
/v2/collections:
post:
tags:
- Collections
summary: Schedule a SEPA Direct Debit collection
description: |-
This endpoint allows you to schedule a SEPA Direct Debit collection to be credited on one of your accounts.
**Scope**: `collections:write`
operationId: createCollection
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateCollection"
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Collection"
security:
- JWT: []
/v2/collections/bulks:
post:
tags:
- Collections
summary: Create bulk collections
description: |-
This endpoint allows to create up to 5000 collections with a single call. It acts exactly as if you called the `POST /v2/collections` endpoint 5000 times yourself, except you don't need to worry about rate limiting. It also allows you to get an aggregated state for this bulk.
This endpoint does not perform the collections synchronously, a `200 OK` response means the bulk will be handled in the near future. You can either poll the `GET` endpoint or use the webhooks to follow its progress.
Note that the completion of a bulk does not mean all collections are settled, it only means the collections were initiated (the equivalent of a call to `POST /v2/collections`).
**Scope**: `collections:write`
operationId: createCollectionsBulk
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateBulkCollections"
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/BulkCollections"
security:
- JWT: []
/v2/collections/bulks/{id}:
get:
tags:
- Collections
summary: Get a bulk and its current progress
description: "**Scope**: `collections:read`"
operationId: getCollectionsBulk
parameters:
- name: id
in: path
description: ID of the bulk.
required: true
schema:
type: string
format: uuid
example: 6ba07619-24ff-43f3-b1f0-cdc9b06bf8a7
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/BulkCollections"
security:
- JWT: []
/v2/collections/bulks/{id}/collections:
get:
tags:
- Collections
summary: Get the status of individual collection in a bulk
description: "**Scope**: `collections:read`"
operationId: getCollectionsBulkItems
parameters:
- name: id
in: path
description: ID of the bulk.
required: true
schema:
type: string
format: uuid
example: 6ba07619-24ff-43f3-b1f0-cdc9b06bf8a7
- name: status
in: query
description: Filter collections by status.
schema:
uniqueItems: true
type: array
items:
type: string
enum:
- pending
- scheduled
- confirmed
- returned
- canceled
- failed
- name: page
in: query
description: "Index of the requested page. Deprecated, use `page_token` instead."
deprecated: true
schema:
minimum: 1
type: integer
format: int32
- name: page_token
in: query
description: "Token used to fetch a specific page, as returned by the `next_page_token`\
\ or `prev_page_token` field of a previous response. Mutually exclusive\
\ with `page`."
schema:
type: string
- name: size
in: query
description: Number of elements per page in response.
schema:
maximum: 100
minimum: 1
type: integer
format: int32
default: 10
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/CollectionPage"
security:
- JWT: []
/v2/ibans:
get:
tags:
- IBANs
summary: List all IBANs
description: "**Scope**: `ibans:read`"
operationId: listIbans
parameters:
- name: account_id
in: query
description: ID of the account.
schema:
type: string
format: uuid
example: 29883c3d-0b11-4c38-91b0-af9018cc5b14
- name: include_deleted
in: query
description: "When set to true, results will include IBANs that have been\
\ deleted."
schema:
type: boolean
default: false
- name: page
in: query
description: "Index of the requested page. Deprecated, use `page_token` instead."
deprecated: true
schema:
minimum: 1
type: integer
format: int32
- name: page_token
in: query
description: "Token used to fetch a specific page, as returned by the `next_page_token`\
\ or `prev_page_token` field of a previous response. Mutually exclusive\
\ with `page`."
schema:
type: string
- name: size
in: query
description: Number of elements per page in response.
schema:
maximum: 100
minimum: 1
type: integer
format: int32
default: 10
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/IbanPage"
security:
- JWT: []
post:
tags:
- IBANs
summary: Create a virtual IBAN
description: "**Scope**: `ibans:write`"
operationId: createIban
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/CreateIban"
required: true
responses:
"201":
description: Created
content:
application/json:
schema:
$ref: "#/components/schemas/Iban"
security:
- JWT: []
/v2/ibans/{id}:
get:
tags:
- IBANs
summary: Get an IBAN
description: "**Scope**: `ibans:read`"
operationId: getIban
parameters:
- name: id
in: path
description: ID of the IBAN.
required: true
schema:
type: string
format: uuid
example: c70bd7bc-58e0-4fdb-8c1f-70186e0de587
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Iban"
security:
- JWT: []
delete:
tags:
- IBANs
summary: Delete an IBAN
description: |-
This operation permanently deletes an IBAN from your account.
**Scope**: `ibans:write`
operationId: deleteIban
parameters:
- name: id
in: path
description: ID of the IBAN.
required: true
schema:
type: string
format: uuid
example: c70bd7bc-58e0-4fdb-8c1f-70186e0de587
responses:
"204":
description: No content
security:
- JWT: []
patch:
tags:
- IBANs
summary: Update an IBAN
description: |-
This operation allows you to update an IBAN name or change its status. Only provided parameters have an effect on the current state of an IBAN.
**Scope**: `ibans:write`
operationId: updateIban
parameters:
- name: id
in: path
description: ID of the IBAN.
required: true
schema:
type: string
format: uuid
example: c70bd7bc-58e0-4fdb-8c1f-70186e0de587
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateIban"
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/Iban"
security:
- JWT: []
/v2/mandate_signature_requests:
get:
tags:
- Mandate signature requests
summary: List the mandate signature requests
description: "**Scope**: `mandate-signature-requests:read`"
operationId: listMandateSignatureRequests
parameters:
- name: status
in: query
description: Filter mandate signature requests by status.
schema:
uniqueItems: true
type: array
items:
type: string
enum:
- sent
- expired
- completed
- name: page
in: query
description: "Index of the requested page. Deprecated, use `page_token` instead."
deprecated: true
schema:
minimum: 1
type: integer
format: int32
- name: page_token
in: query
description: "Token used to fetch a specific page, as returned by the `next_page_token`\
\ or `prev_page_token` field of a previous response. Mutually exclusive\
\ with `page`."
schema:
type: string
- name: size
in: query
description: Number of elements per page in response.
schema:
maximum: 100
minimum: 1
type: integer
format: int32
default: 10
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/MandateSignatureRequestPage"
security:
- JWT: []
post:
tags:
- Mandate signature requests
summary: Create a new mandate signature request
description: |-
An email will be sent to the mandate debtor so they can complete and sign the collection mandate.
**Scope**: `mandate-signature-requests:write`
operationId: createMandateSignatureRequest
requestBody:
content:
application/json:
schema:
type: object
discriminator:
propertyName: mode
mapping:
email: "#/components/schemas/CreateEmailMandateSignatureRequest"
redirect: "#/components/schemas/CreateRedirectMandateSignatureRequest"
oneOf:
- $ref: "#/components/schemas/CreateEmailMandateSignatureRequest"
- $ref: "#/components/schemas/CreateRedirectMandateSignatureRequest"
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
required:
- debtor_email
- id
- is_deleted
- language
- mode
- reference
- scheme
- status
type: object
properties:
reference:
pattern: "^[A-Za-z0-9+?/\\-:().,'\\s]{1,35}$"
type: string
description: The unique mandate reference.
example: ABC123DEF
id:
type: string
description: ID of the mandate signature request.
format: uuid
example: 61b05c4f-3f72-4951-8c30-a2a9faaa5184
scheme:
type: string
description: The mandate scheme.
example: core
enum:
- b2b
- core
language:
type: string
description: The language used for the email and signature page
for the debtor.
example: french
default: french
enum:
- french
- english
status:
type: string
description: Current status of the mandate signature request.
example: sent
enum:
- sent
- expired
- completed
mode:
type: string
description: Define the delivery strategy of this signature request.
enum:
- email
- redirect
contract_reference:
type: string
description: The contract reference attached to the mandate. This
is optional metadata.
example: CUST-1234
is_deleted:
type: boolean
description: Whether or not this mandate signature request has
been deleted.
example: false
debtor:
$ref: "#/components/schemas/MandateSignatureRequestDebtor"
debtor_email:
type: string
description: The email address of the debtor.
example: foo@bar.com
discriminator:
propertyName: mode
mapping:
email: "#/components/schemas/EmailMandateSignatureRequest"
redirect: "#/components/schemas/RedirectMandateSignatureRequest"
oneOf:
- $ref: "#/components/schemas/EmailMandateSignatureRequest"
- $ref: "#/c
# --- truncated at 32 KB (214 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/memo-bank/refs/heads/main/openapi/memo-bank-premium-bank-api-openapi.yml