Memo Bank API
2.0

Welcome! You can use the Memo Bank API to check your current accounts, fetch your transactions, make payments, create IBANs or payment cards, and access all Memo Bank features.

If you're a third-party payment service provider complying with PSD2, perhaps you'd be more interested in our NextGenPSD2 API.

This is the documentation for version 2.0 of the API. Last update on Jan 26, 2023.

Base URL
https://api.memo.bank

Getting started

To get started with our API, talk to your banker first. He or she needs to activate the API feature on your Memo Bank workspace.

Once your banker has granted you an API access, you can then setup your authentication using our web interface. To do so, navigate to Company Settings > API connections in your Memo Bank workspace. Note that only owners and administrators have access to this page.

As an output of this process, you'll have three pieces of information allowing you to authenticate requests on the API:

  1. a certificate and its SHA256 thumbprint;
  2. a secret code;
  3. a cryptographic private key.

Authentication

Our authentication is based on JSON Web Token (JWT) and JSON Web Signature (JWS).

No matter which coding language you're using, there should be a library to handle the cryptographic part for you. All you need is to feed it the right header and payload claims.

In the JWT header:

  • alg must be RS256, as we require a RSA-SHA256 signature.
  • typ must be JWT.
  • x5t#S256 is the SHA256 thumbprint of the certificate, which you can find on the user interface.

In the JWT payload:

  • sub must be the method of the request, followed by a space and the full path, including query params.
  • aud must be the domain on which you do the request, e.g. api.memo.bank.
  • iat must be the timestamp at which you created the token. Note that we accept only 5 seconds of difference with the server time, to mitigate clock skew.
  • jti must be a unique identifier for the token. It must be different for each request, we suggest you should use V4 UUIDs.
  • sec must be the secret information you obtained during the setup process on the user interface. This is a custom claim, not covered by the JWT specification.
  • dig#S256 must be a base64url_encoding(sha_256(body)), to be provided only if the request has a body, so for example it is not necessary on GET requests (see base64url_encoding). This is a custom claim, not covered by the JWT specification.

The JWT must then be signed with the private key you generated during the setup (see Getting started), and included in the HTTP headers of the request, as a standard bearer token Authorization: Bearer <token>.

Example JWT header and payload.

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t#S256": "3A14ZcxIaasp4RHaYReL7wevm3oDzn7ZqmgqScCMY74"
}
{
  "sub": "POST /v1/transfers",
  "aud": "api.memo.bank",
  "iat": 1657055009,
  "jti": "5525620b-9dcd-4562-8c6c-60984f46cb48",
  "sec": "a2029d646c94406d2945b7a2b31e4fb3ff09a6d0ae29144380775b5471c4e846",
  "dig#S256": "lW6N_kO2gPMsMkzXyn028gWwrnaN0kJaiy7FMJcR0Ek"
}

Idempotent requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a transfer does not go through due to a network connection error, you can retry the request with the same idempotency key to guarantee that only the single transfer originally attempted is created.

To perform an idempotent request, provide an additional Idempotency-Key request header. We recommend using a V4 UUID. In case the API call fails with a network error, or responds with a 5XX or 409 status code, we expect the caller to perform retries with the same Idempotency-Key header until it responds differently. For any other response code, especially other 4XX errors, there is no point in attempting retries, as we will always send the same result.
When a previous response is replayed, the response is sent with an additional HTTP header Idempotent-Replayed: true.

Idempotency keys will persist in the API for 24 hours. If an original request is still being processed when an idempotency key is reused, the API will return a 409 Conflict error (which is safe to retry).

Subsequent requests must be identical to the original request or the API will return a 422 Unprocessable Entity error. We don't support setting an idempotency key on GET and DELETE requests, as these requests are inherently idempotent.

curl --request POST \
  --url https://api.memo.bank/v1/transfers \
  --header 'Authorization: Bearer ***' \
  --header 'Idempotency-Key: 19b390d1-e7d4-4e27-abe2-49cac9b41ba1' \
  --header 'Content-Type: application/json' \
  --data '{...}'

Errors

The API uses standard HTTP response codes to indicate the success or failure of requests. Codes in the 2xx range indicate success; codes in the 4xx and 5xx ranges indicate errors. The format of error messages is unified, and can be distinguished by their code key. The message is a plain English explanation of the problem.

{
  "code": "error_code",
  "message": "Example error message.",
}

Versioning and backwards compatibility

The API is versioned by path (/v1/...). When we introduce breaking changes, we will increase this version number. We'll of course continually make backward-compatible changes without increasing the version number.

Examples of things we do not consider breaking include:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses. We will occasionally move response fields in the API, and will continue to return the existing field in its previous location, while removing it from this documentation.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings. Strings that are marked as const or enum in this documentation will not change.
  • Adding new EventType or ResourceType enum values for webhooks.
  • Adding new TransactionSource enum values for transactions.

Accounts

Accounts are the current accounts that you own. They boil down to a list of transactions with a balance. To see the transactions linked to a given account, use the Transactions endpoint.

Get an account

GET /v2/accounts/{id}

Path parameters

  • id string(uuid) Required

    ID of the account.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      ID of the account.

    • name string Required

      Name of the account, as seen in the Memo Bank interface.

    • status string Required

      Status of the account.

      Values are active or closed.

    • balance integer(int64) Required

      Balance of the account, in cents. It represents the available money on the account at the time of the request. Note that authorized overdrafts are not included in the balance.

    • currency string Required

      Currency of the account balance, in ISO 4217 format.

    • iban string Required

      Main IBAN of the account.

    • is_main boolean Required

      Flag indicating if this account is the main account of your workspace.

GET /v2/accounts/{id}
curl \
 -X GET https://api.memo.bank/v2/accounts/c70bd7bc-58e0-4fdb-8c1f-70186e0de587 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "id": "db2b50c0-a943-4eb1-a69f-fa37f112daa8",
  "name": "Main account",
  "status": "active",
  "balance": 42,
  "currency": "EUR",
  "iban": "FR7617338000017498690379033",
  "is_main": true
}

List all accounts

GET /v2/accounts

Query parameters

  • page integer(int32)

    Index of the requested page.

    Minimum value is 1. Default value is 1.

  • size integer(int32)

    Number of elements per page in response.

    Minimum value is 1, maximum value is 100. Default value is 10.

Responses

  • 200 object

    OK

    • results array[object] Required

      Elements of the page.

      • id string(uuid) Required

        ID of the account.

      • name string Required

        Name of the account, as seen in the Memo Bank interface.

      • status string Required

        Status of the account.

        Values are active or closed.

      • balance integer(int64) Required

        Balance of the account, in cents. It represents the available money on the account at the time of the request. Note that authorized overdrafts are not included in the balance.

      • currency string Required

        Currency of the account balance, in ISO 4217 format.

      • iban string Required

        Main IBAN of the account.

      • is_main boolean Required

        Flag indicating if this account is the main account of your workspace.

    • has_prev boolean Required

      Flag indicating if there is a previous page.

    • has_next boolean Required

      Flag indicating if there is a next page.

GET /v2/accounts
curl \
 -X GET https://api.memo.bank/v2/accounts \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "id": "db2b50c0-a943-4eb1-a69f-fa37f112daa8",
      "name": "Main account",
      "status": "active",
      "balance": 42,
      "currency": "EUR",
      "iban": "FR7617338000017498690379033",
      "is_main": true
    }
  ],
  "has_prev": true,
  "has_next": true
}

IBANs

IBANs are identifiers for bank accounts. There are two types of IBANs at Memo Bank:

  • Main IBANs, which acts as a primary identifier for a bank account. There's exactly one main IBAN per bank account. You can't 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're 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.

List all IBANs

GET /v2/ibans

Query parameters

  • account_id string(uuid)

    ID of the account.

  • page integer(int32)

    Index of the requested page.

    Minimum value is 1. Default value is 1.

  • size integer(int32)

    Number of elements per page in response.

    Minimum value is 1, maximum value is 100. Default value is 10.

Responses

  • 200 object

    OK

    • results array[object] Required

      Elements of the page.

      • id string(uuid) Required

        ID of the IBAN.

      • account_id string(uuid) Required

        ID of the account this IBAN belongs to.

      • iban string Required

        Actual value of the IBAN.

      • name string Required

        Name of the IBAN.

      • status string Required

        Status of the IBAN. It determines if an IBAN accepts incoming or outgoing transfers.

        Values are active or inactive.

      • type string Required

        Flag indicating if this IBAN is the main IBAN of an account, or a virtual IBAN. Please note that main IBANs cannot be updated or deleted.

        Values are main or virtual.

    • has_prev boolean Required

      Flag indicating if there is a previous page.

    • has_next boolean Required

      Flag indicating if there is a next page.

GET /v2/ibans
curl \
 -X GET https://api.memo.bank/v2/ibans \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "id": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
      "account_id": "de2284c3-0360-4e4a-b10d-771f75b772d4",
      "iban": "FR27590171083068762111832788",
      "name": "customer no12345",
      "status": "active",
      "type": "main"
    }
  ],
  "has_prev": true,
  "has_next": true
}

Body Required

  • account_id string(uuid) Required

    ID of the account.

  • name string Required

    Custom name of the new IBAN, as seen in the Memo Bank interface.

Responses

  • 201 object

    Created

    • id string(uuid) Required

      ID of the IBAN.

    • account_id string(uuid) Required

      ID of the account this IBAN belongs to.

    • iban string Required

      Actual value of the IBAN.

    • name string Required

      Name of the IBAN.

    • status string Required

      Status of the IBAN. It determines if an IBAN accepts incoming or outgoing transfers.

      Values are active or inactive.

    • type string Required

      Flag indicating if this IBAN is the main IBAN of an account, or a virtual IBAN. Please note that main IBANs cannot be updated or deleted.

      Values are main or virtual.

POST /v2/ibans
curl \
 -X POST https://api.memo.bank/v2/ibans \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"account_id":"29883c3d-0b11-4c38-91b0-af9018cc5b14","name":"customer no12345"}'
Request example
{
  "account_id": "29883c3d-0b11-4c38-91b0-af9018cc5b14",
  "name": "customer no12345"
}
Response example (201)
{
  "id": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
  "account_id": "de2284c3-0360-4e4a-b10d-771f75b772d4",
  "iban": "FR27590171083068762111832788",
  "name": "customer no12345",
  "status": "active",
  "type": "main"
}

Get an IBAN

GET /v2/ibans/{id}

Path parameters

  • id string(uuid) Required

    ID of the IBAN.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      ID of the IBAN.

    • account_id string(uuid) Required

      ID of the account this IBAN belongs to.

    • iban string Required

      Actual value of the IBAN.

    • name string Required

      Name of the IBAN.

    • status string Required

      Status of the IBAN. It determines if an IBAN accepts incoming or outgoing transfers.

      Values are active or inactive.

    • type string Required

      Flag indicating if this IBAN is the main IBAN of an account, or a virtual IBAN. Please note that main IBANs cannot be updated or deleted.

      Values are main or virtual.

GET /v2/ibans/{id}
curl \
 -X GET https://api.memo.bank/v2/ibans/c70bd7bc-58e0-4fdb-8c1f-70186e0de587 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "id": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
  "account_id": "de2284c3-0360-4e4a-b10d-771f75b772d4",
  "iban": "FR27590171083068762111832788",
  "name": "customer no12345",
  "status": "active",
  "type": "main"
}

Delete an IBAN

DELETE /v2/ibans/{id}

This operation permanently deletes an IBAN from your account.

Path parameters

  • id string(uuid) Required

    ID of the IBAN.

Responses

DELETE /v2/ibans/{id}
curl \
 -X DELETE https://api.memo.bank/v2/ibans/c70bd7bc-58e0-4fdb-8c1f-70186e0de587 \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Update an IBAN

PATCH /v2/ibans/{id}

This operation allows you to update an IBAN name or change its status. Only provided parameters have an affect on the current state of an IBAN.

Path parameters

  • id string(uuid) Required

    ID of the IBAN.

Body Required

  • name string

    New IBAN name.

  • status string

    New IBAN status.

    Values are active or inactive.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      ID of the IBAN.

    • account_id string(uuid) Required

      ID of the account this IBAN belongs to.

    • iban string Required

      Actual value of the IBAN.

    • name string Required

      Name of the IBAN.

    • status string Required

      Status of the IBAN. It determines if an IBAN accepts incoming or outgoing transfers.

      Values are active or inactive.

    • type string Required

      Flag indicating if this IBAN is the main IBAN of an account, or a virtual IBAN. Please note that main IBANs cannot be updated or deleted.

      Values are main or virtual.

PATCH /v2/ibans/{id}
curl \
 -X PATCH https://api.memo.bank/v2/ibans/fe98f29d-5165-45ff-83f9-d7aa83e970b5 \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"name":"string","status":"active"}'
Request example
{
  "name": "string",
  "status": "active"
}
Response example (200)
{
  "id": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
  "account_id": "de2284c3-0360-4e4a-b10d-771f75b772d4",
  "iban": "FR27590171083068762111832788",
  "name": "customer no12345",
  "status": "active",
  "type": "main"
}

Transactions

Transactions are debit and credit operations on an account.

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.

Also, note that rejected means that the transaction was rejected before it was authorized, having no possible impact on the balance at any time. On the other hand, canceled means that the transaction was first authorized and then canceled, so it had a temporary impact on the balance.

Get a transaction

GET /v2/transactions/{id}

Path parameters

  • id string(uuid) Required

    ID of the transaction.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      Unique ID of the transaction.

    • reference string(uuid) Required

      Reference of the money movement. In case you initiate a transfer between two of your own accounts, both transactions (debit and credit) will have the same reference, it can be safely used to correlate them.

    • account_id string(uuid) Required

      ID of the account this transaction belongs to.

    • amount integer(int64) Required

      Amount of the transaction, in cents. The amount is always positive, use direction to give it a sign.

    • currency string Required

      Currency of the transaction amount, in ISO 4217 format.

    • direction string Required

      Direction of the transaction.

      Values are debit or credit.

    • request_date string(date-time) Required

      Date at which the transaction has been requested, in ISO8601 format.Usually the same as the execution date, except for scheduled transfers and transfer requests.

    • execution_date string(date-time) Required

      Date at which the transaction processing has started or will start, in ISO8601 format. For debits, that’s when the money is removed from the available balance of the account.

    • accounting_date string(date-time)

      Date at which the transaction has been confirmed, in ISO8601 format. For credits, that’s when the money is credited from the available balance of the account.

    • counterparty_name string Required

      Name of the counterparty.

    • Internal note attached to this transaction, visible only in your Memo Bank workspace.

    • status string Required

      Current status of the transaction.

      Values are scheduled, authorized, confirmed, rejected, or canceled.

    • batch_id string(uuid)

      ID of the batch this transaction belongs to, if any.

    • attachment_count integer(int32)

      Number of documents attached to this transaction.

    • source object Required

      Source of the transaction. Please refer to the OpenAPI source file for more details. We may add additional possible source types over time; your application should be able to handle such additions gracefully.

      • type string

        Values are bank_account_remuneration, card_deferred, card_withdrawal, collection_incoming, collection_outgoing, collection_incoming_return, collection_outgoing_return, debt_purchase_application_fees, debt_purchase_disbursement, debt_purchase_interests, debt_purchase_repayment, diverse_operation, loan_application_fees, loan_disbursement, loan_guarantee_fee, loan_repayment, maintenance_transfer, overdraft_agios, overdraft_application_fees, subscription, transfer_incoming, transfer_outgoing, transfer_incoming_return, transfer_outgoing_return, wire_transfer_incoming, or wire_transfer_outgoing.

GET /v2/transactions/{id}
curl \
 -X GET https://api.memo.bank/v2/transactions/c70bd7bc-58e0-4fdb-8c1f-70186e0de587 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "id": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
  "reference": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
  "account_id": "708683cb-60f6-464a-a62f-be2e339c34aa",
  "amount": 42,
  "currency": "EUR",
  "direction": "debit",
  "request_date": "2023-05-04T09:42:00+00:00",
  "execution_date": "2023-05-04T09:42:00+00:00",
  "accounting_date": "2023-05-04T09:42:00+00:00",
  "counterparty_name": "string",
  "internal_note": "phone bill",
  "status": "scheduled",
  "batch_id": "dc47b1ee-1bd7-4072-8d1b-27ff4297b33e",
  "attachment_count": 42,
  "source": {
    "type": "bank_account_remuneration"
  }
}

List all transactions

GET /v2/transactions

Query parameters

  • account_id string(uuid)

    Filter transactions by account.

  • page integer(int32)

    Index of the requested page.

    Minimum value is 1. Default value is 1.

  • size integer(int32)

    Number of elements per page in response.

    Minimum value is 1, maximum value is 100. Default value is 10.

  • start_date string(date-time)

    Filter transactions by accounting date (inclusive greater than), in ISO8601 format.

  • end_date string(date-time)

    Filter transactions by account date (exclusive lower than), in ISO8601 format.

  • reference string(uuid)

    Filter transactions by reference.

  • Filter transactions by local IBAN. Allows for example to list all incoming and outgoing transactions that passed through a given virtual IBAN.

  • batch_id string(uuid)

    Filter transactions by transaction batch.

  • order_by string

    Sort transactions in ascending or descending order.

    Values are execution_date or -execution_date. Default value is -execution_date.

Responses

  • 200 object

    OK

    • results array[object] Required

      Elements of the page.

      • id string(uuid) Required

        Unique ID of the transaction.

      • reference string(uuid) Required

        Reference of the money movement. In case you initiate a transfer between two of your own accounts, both transactions (debit and credit) will have the same reference, it can be safely used to correlate them.

      • account_id string(uuid) Required

        ID of the account this transaction belongs to.

      • amount integer(int64) Required

        Amount of the transaction, in cents. The amount is always positive, use direction to give it a sign.

      • currency string Required

        Currency of the transaction amount, in ISO 4217 format.

      • direction string Required

        Direction of the transaction.

        Values are debit or credit.

      • request_date string(date-time) Required

        Date at which the transaction has been requested, in ISO8601 format.Usually the same as the execution date, except for scheduled transfers and transfer requests.

      • execution_date string(date-time) Required

        Date at which the transaction processing has started or will start, in ISO8601 format. For debits, that’s when the money is removed from the available balance of the account.

      • accounting_date string(date-time)

        Date at which the transaction has been confirmed, in ISO8601 format. For credits, that’s when the money is credited from the available balance of the account.

      • counterparty_name string Required

        Name of the counterparty.

      • Internal note attached to this transaction, visible only in your Memo Bank workspace.

      • status string Required

        Current status of the transaction.

        Values are scheduled, authorized, confirmed, rejected, or canceled.

      • batch_id string(uuid)

        ID of the batch this transaction belongs to, if any.

      • attachment_count integer(int32)

        Number of documents attached to this transaction.

      • source object Required

        Source of the transaction. Please refer to the OpenAPI source file for more details. We may add additional possible source types over time; your application should be able to handle such additions gracefully.

        • type string

          Values are bank_account_remuneration, card_deferred, card_withdrawal, collection_incoming, collection_outgoing, collection_incoming_return, collection_outgoing_return, debt_purchase_application_fees, debt_purchase_disbursement, debt_purchase_interests, debt_purchase_repayment, diverse_operation, loan_application_fees, loan_disbursement, loan_guarantee_fee, loan_repayment, maintenance_transfer, overdraft_agios, overdraft_application_fees, subscription, transfer_incoming, transfer_outgoing, transfer_incoming_return, transfer_outgoing_return, wire_transfer_incoming, or wire_transfer_outgoing.

    • has_prev boolean Required

      Flag indicating if there is a previous page.

    • has_next boolean Required

      Flag indicating if there is a next page.

GET /v2/transactions
curl \
 -X GET https://api.memo.bank/v2/transactions \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "id": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
      "reference": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
      "account_id": "708683cb-60f6-464a-a62f-be2e339c34aa",
      "amount": 42,
      "currency": "EUR",
      "direction": "debit",
      "request_date": "2023-05-04T09:42:00+00:00",
      "execution_date": "2023-05-04T09:42:00+00:00",
      "accounting_date": "2023-05-04T09:42:00+00:00",
      "counterparty_name": "string",
      "internal_note": "phone bill",
      "status": "scheduled",
      "batch_id": "dc47b1ee-1bd7-4072-8d1b-27ff4297b33e",
      "attachment_count": 42,
      "source": {
        "type": "bank_account_remuneration"
      }
    }
  ],
  "has_prev": true,
  "has_next": true
}

Attachments

Documents attached to transactions.

Please note that the documents attached to a transaction which belongs to a transaction batch will be attached to all the transactions of the batch.

List all attachments

GET /v2/attachments

Query parameters

  • transaction_id string(uuid)

    Filter attachments by transaction.

  • page integer(int32)

    Index of the requested page.

    Minimum value is 1. Default value is 1.

  • size integer(int32)

    Number of elements per page in response.

    Minimum value is 1, maximum value is 100. Default value is 10.

Responses

  • 200 object

    OK

    • results array[object] Required

      Elements of the page.

      • id string(uuid) Required

        ID of the attachment.

      • transaction_ids array[string(uuid)] Required

        IDs of the transactions this document is attached to. Contains at least one value but multiple values when the document is attached to a transaction batch.

      • filename string Required

        Name of the attached file.

      • size integer(int64) Required

        Size of the attached file in bytes.

      • mime_type string Required

        Mime type of the attached file.

      • date string(date-time) Required

        Date at which the file has been attached to a transaction.

    • has_prev boolean Required

      Flag indicating if there is a previous page.

    • has_next boolean Required

      Flag indicating if there is a next page.

GET /v2/attachments
curl \
 -X GET https://api.memo.bank/v2/attachments \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "results": [
    {
      "id": "db2b50c0-a943-4eb1-a69f-fa37f112daa8",
      "transaction_ids": [
        "20588f37-0ca6-4abd-80ae-1964d601b516"
      ],
      "filename": "document.pdf",
      "size": 42,
      "mime_type": "application/pdf",
      "date": "2023-05-04T09:42:00+00:00"
    }
  ],
  "has_prev": true,
  "has_next": true
}

Create an attachment

POST /v2/attachments

This operation allows you to upload and attach a document to a transaction.

Body

Responses

  • 201 object

    Created

    • id string(uuid) Required

      ID of the attachment.

    • transaction_ids array[string(uuid)] Required

      IDs of the transactions this document is attached to. Contains at least one value but multiple values when the document is attached to a transaction batch.

    • filename string Required

      Name of the attached file.

    • size integer(int64) Required

      Size of the attached file in bytes.

    • mime_type string Required

      Mime type of the attached file.

    • date string(date-time) Required

      Date at which the file has been attached to a transaction.

POST /v2/attachments
curl \
 -X POST https://api.memo.bank/v2/attachments \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: multipart/form-data" \
 -F "document=@file" \
 -F "transaction_id=3439bd9a-077a-4c02-8bd7-f14eadf8975b"
Request example
{
  "document": "@file",
  "transaction_id": "3439bd9a-077a-4c02-8bd7-f14eadf8975b"
}
Response example (201)
{
  "id": "db2b50c0-a943-4eb1-a69f-fa37f112daa8",
  "transaction_ids": [
    "20588f37-0ca6-4abd-80ae-1964d601b516"
  ],
  "filename": "document.pdf",
  "size": 42,
  "mime_type": "application/pdf",
  "date": "2023-05-04T09:42:00+00:00"
}

Get an attachment

GET /v2/attachments/{id}

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.

Path parameters

  • id string(uuid) Required

    ID of the attachment.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      ID of the attachment.

    • transaction_ids array[string(uuid)] Required

      IDs of the transactions this document is attached to. Contains at least one value but multiple values when the document is attached to a transaction batch.

    • filename string Required

      Name of the attached file.

    • size integer(int64) Required

      Size of the attached file in bytes.

    • mime_type string Required

      Mime type of the attached file.

    • date string(date-time) Required

      Date at which the file has been attached to a transaction.

GET /v2/attachments/{id}
curl \
 -X GET https://api.memo.bank/v2/attachments/c70bd7bc-58e0-4fdb-8c1f-70186e0de587 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "id": "db2b50c0-a943-4eb1-a69f-fa37f112daa8",
  "transaction_ids": [
    "20588f37-0ca6-4abd-80ae-1964d601b516"
  ],
  "filename": "document.pdf",
  "size": 42,
  "mime_type": "application/pdf",
  "date": "2023-05-04T09:42:00+00:00"
}

Delete an attachment

DELETE /v2/attachments/{id}

Path parameters

  • id string(uuid) Required

    ID of the attachment.

Responses

DELETE /v2/attachments/{id}
curl \
 -X DELETE https://api.memo.bank/v2/attachments/c70bd7bc-58e0-4fdb-8c1f-70186e0de587 \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Schedule a SEPA Direct Debit collection

POST /v2/collections

This endpoint allows you to schedule a SEPA Direct Debit collection to be credited on one of your accounts.

Body Required

  • amount integer(int64) Required

    Amount to be collected, in cents. The currency is always EURO.

    Minimum value is 1.

  • mandate object Required

    The SEPA Direct Debit collection mandate to be used.

    • reference string Required

      The unique mandate reference.

      Format should match the following pattern: [A-Za-z0-9+?/\-:().,'\s]{1,35}.

    • scheme string Required

      The mandate scheme.

      Values are b2b or core.

    • signature_date string(date)

      The mandate signature date, in ISO8601 format. The date must not be in the future. This field is only required in case of a new mandate. If there is an existing mandate matching the scheme and with the same reference, this field will be ignored.

    • debtor object

      The debtor associated with this mandate.This field is only required in case of a new mandate. If there is an existing mandate matching the scheme and with the same reference, this field will be ignored.

      • name string Required

        Name of the debtor.

        Minimum length is 1, maximum length is 256.

      • iban string Required

        IBAN of the debtor.

      • address object

        The debtor's address. Mandatory only when the the debtor's bank — more specifically, its BIC — is located in a non-EEA SEPA country or territory.

        • street string

          Name of the street.

          Minimum length is 1, maximum length is 256.

        • Number of the building or house.

          Minimum length is 1, maximum length is 256.

        • Postal or zip code.

          Minimum length is 1, maximum length is 256.

        • city string

          Name of the city.

          Minimum length is 1, maximum length is 256.

        • country string Required

          ISO3166-1 alpha-2 country code.

          Format should match the following pattern: [A-Z]{2}.

    • The contract reference attached to this mandate. This is optional metadata.If there is an existing mandate matching the scheme and with the same reference, this field will be ignored when provided.

      Minimum length is 1, maximum length is 256.

  • scheduled_date string(date) Required

    The ISO8601 formatted date on which the direct debit collection will be submitted. This date must be in the future. If your direct debit is scheduled to be submitted on a non-business day, it will be effectively submitted on the next business day. The execution will then happen on the following business day. For example, a direct debit scheduled on a Saturday will be submitted on the following Monday and executed on the Tuesday (assuming that both week days are business days).

  • local_iban string Required

    Existing IBAN to be credited. It can be the main IBAN of an account or a virtual IBAN.

  • message string

    Message attached to this collection, visible by all involved parties.

    Minimum length is 1, maximum length is 256.

  • Internal note attached to this collection, visible only in your Memo Bank workspace.

    Minimum length is 1, maximum length is 256.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      ID of the collection.

    • reference string(uuid) Required

      Unique reference, can be used to correlate with the resulting Transaction.

    • amount integer(int64) Required

      The collection amount, in cents.

    • currency string Required

      Currency of the amount, in ISO 4217 format.

    • mandate object Required

      The SEPA Direct Debit collection mandate used.

      • reference string Required

        The unique mandate reference.

      • scheme string Required

        The mandate scheme.

        Values are b2b or core.

    • scheduled_date string(date) Required

      The collection scheduled date, in ISO8601 format.

    • local_iban string Required

      IBAN credited or to be credited. It can be the main IBAN of an account or a virtual IBAN.

    • status string Required

      Current status of the collection.

      Values are pending, scheduled, confirmed, or failed.

    • Code that represents the failure reason when the collection has failed:
      - invalid_mandate_iban: The mandate's IBAN is invalid.
      - unreachable_mandate_iban: The mandate's IBAN is unreachable for the given scheme.
      - missing_debtor_address: The debtor address is missing and required for non-EEA SEPA country.
      - core_limit_exceeded: The limit for CORE collections was exceeded.
      - execution_failure: The collection was executed but failed before settlement.

      Values are invalid_mandate_iban, unreachable_mandate_iban, missing_debtor_address, core_limit_exceeded, or execution_failure.

    • message string

      Message attached to this collection, visible by all involved parties.

    • Internal note attached to this collection, visible only in your Memo Bank workspace.

POST /v2/collections
curl \
 -X POST https://api.memo.bank/v2/collections \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"amount":500,"mandate":{"reference":"ABC123DEF","scheme":"core","signature_date":"2022-12-01","debtor":{"name":"John Doe","iban":"FR2512739000308553756377J95","address":{"street":"rue de la Boétie","building_number":"42","postal_code":"75008","city":"Paris","country":"FR"}},"contract_reference":"CUST-1234"},"scheduled_date":"2022-12-05","local_iban":"FR6430003000509825397888D64","message":"invoice no12345","internal_note":"phone bill"}'
Request example
{
  "amount": 500,
  "mandate": {
    "reference": "ABC123DEF",
    "scheme": "core",
    "signature_date": "2022-12-01",
    "debtor": {
      "name": "John Doe",
      "iban": "FR2512739000308553756377J95",
      "address": {
        "street": "rue de la Boétie",
        "building_number": "42",
        "postal_code": "75008",
        "city": "Paris",
        "country": "FR"
      }
    },
    "contract_reference": "CUST-1234"
  },
  "scheduled_date": "2022-12-05",
  "local_iban": "FR6430003000509825397888D64",
  "message": "invoice no12345",
  "internal_note": "phone bill"
}
Response example (200)
{
  "id": "61b05c4f-3f72-4951-8c30-a2a9faaa5184",
  "reference": "ab004cfc-99fb-4ba9-bc9c-70982f853cb1",
  "amount": 500,
  "currency": "EUR",
  "mandate": {
    "reference": "ABC123DEF",
    "scheme": "core"
  },
  "scheduled_date": "2022-12-05",
  "local_iban": "FR6430003000509825397888D64",
  "status": "failed",
  "failure_code": "invalid_mandate_iban",
  "message": "invoice no12345",
  "internal_note": "phone bill"
}

Get a collection

GET /v2/collections/{id}

Path parameters

  • id string(uuid) Required

    ID of the collection.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      ID of the collection.

    • reference string(uuid) Required

      Unique reference, can be used to correlate with the resulting Transaction.

    • amount integer(int64) Required

      The collection amount, in cents.

    • currency string Required

      Currency of the amount, in ISO 4217 format.

    • mandate object Required

      The SEPA Direct Debit collection mandate used.

      • reference string Required

        The unique mandate reference.

      • scheme string Required

        The mandate scheme.

        Values are b2b or core.

    • scheduled_date string(date) Required

      The collection scheduled date, in ISO8601 format.

    • local_iban string Required

      IBAN credited or to be credited. It can be the main IBAN of an account or a virtual IBAN.

    • status string Required

      Current status of the collection.

      Values are pending, scheduled, confirmed, or failed.

    • Code that represents the failure reason when the collection has failed:
      - invalid_mandate_iban: The mandate's IBAN is invalid.
      - unreachable_mandate_iban: The mandate's IBAN is unreachable for the given scheme.
      - missing_debtor_address: The debtor address is missing and required for non-EEA SEPA country.
      - core_limit_exceeded: The limit for CORE collections was exceeded.
      - execution_failure: The collection was executed but failed before settlement.

      Values are invalid_mandate_iban, unreachable_mandate_iban, missing_debtor_address, core_limit_exceeded, or execution_failure.

    • message string

      Message attached to this collection, visible by all involved parties.

    • Internal note attached to this collection, visible only in your Memo Bank workspace.

GET /v2/collections/{id}
curl \
 -X GET https://api.memo.bank/v2/collections/45195a6f-daa8-4bc1-9ac4-3979e72bd89d \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "id": "61b05c4f-3f72-4951-8c30-a2a9faaa5184",
  "reference": "ab004cfc-99fb-4ba9-bc9c-70982f853cb1",
  "amount": 500,
  "currency": "EUR",
  "mandate": {
    "reference": "ABC123DEF",
    "scheme": "core"
  },
  "scheduled_date": "2022-12-05",
  "local_iban": "FR6430003000509825397888D64",
  "status": "failed",
  "failure_code": "invalid_mandate_iban",
  "message": "invoice no12345",
  "internal_note": "phone bill"
}

Initiate a SEPA transfer

POST /v2/transfers

This endpoint allows you to initiate a SEPA transfer from your account.

Body Required

  • amount integer(int64) Required

    Amount of the transfer, in cents. The currency is always EURO.

    Minimum value is 1.

  • Name of the beneficiary. Will be used to create the beneficiary if one doesn't already exist with the same beneficiary_iban, will be ignored otherwise. If you know the beneficiary exists, you don't need to provide a name here.

  • beneficiary_iban string Required

    IBAN of the beneficiary. Note that when you perform a transfer between your own accounts, you can't use a virtual IBAN.

  • local_iban string Required

    Existing IBAN to be used as the source of the transfer. Can be the main IBAN of an account or a virtual IBAN. Note that when you perform a transfer between your own accounts, you can't use a virtual IBAN.

  • Determines whether to use an instant transfer (available in a few seconds on the beneficiary account), or a standard transfer (1-3 business days). By default, try to perform an instant transfer if possible for this beneficiary, and use a standard transfer otherwise.

    Values are standard_only, instant_only, or instant_if_available. Default value is instant_if_available.

  • scheduled_date string(date)

    The ISO8601 formatted date on which the transfer will be executed. If this date is not set, the transfer is executed immediately. Setting this date is incompatible with instant_only strategy.

  • message string

    Message attached to this transfer, visible by all involved parties.

  • Internal note attached to this transfer, visible only in your Memo Bank workspace.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      ID of the transfer

    • reference string(uuid) Required

      Unique reference, can be used to correlate with the resulting Transaction.

    • amount integer(int64) Required

      Amount of the transfer, in cents.

    • currency string Required

      Currency of the amount, in ISO 4217 format.

    • local_iban string Required

      IBAN used as a source of the transfer. It can be the main IBAN of an account or a virtual IBAN.

    • beneficiary_iban string Required

      IBAN of the beneficiary.

    • Type of the transfer. If the type strategy is instant_if_available, it can be missing while we determine the appropriate type.

      Values are standard or instant.

    • type_strategy string Required

      Strategy used when creating the transfer.

      Values are standard_only, instant_only, or instant_if_available.

    • status string Required

      Current status of the transfer.

      Values are pending, scheduled, authorized, confirmed, or failed.

    • Code that represents the failure reason when the transfer has failed:
      - insufficient_funds: Not enough funds on your account to execute the transfer.
      - execution_failure: The collection was executed but failed before settlement.
      - instant_transfer_not_available: The beneficiary can not receive instant transfers.
      - invalid_beneficiary_iban: The beneficiary's IBAN is invalid.
      - unreachable_beneficiary_iban: The beneficiary is unreachable for the given transfer type.
      - maximum_amount_exceeded: The transfer amount exceeds the limit.

      Values are insufficient_funds, execution_failure, instant_transfer_not_available, invalid_beneficiary_iban, unreachable_beneficiary_iban, or maximum_amount_exceeded.

    • scheduled_date string(date)

      Date on which the transfer was scheduled, if any.

    • message string

      Message attached to this transfer, visible by all involved parties.

    • Internal note attached to this transfer, visible only in your Memo Bank workspace.

POST /v2/transfers
curl \
 -X POST https://api.memo.bank/v2/transfers \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"amount":500,"beneficiary_name":"John Doe","beneficiary_iban":"FR2512739000308553756377J95","local_iban":"FR6430003000509825397888D64","type_strategy":"instant_if_available","scheduled_date":"2022-12-05","message":"invoice no12345","internal_note":"phone bill"}'
Request example
{
  "amount": 500,
  "beneficiary_name": "John Doe",
  "beneficiary_iban": "FR2512739000308553756377J95",
  "local_iban": "FR6430003000509825397888D64",
  "type_strategy": "instant_if_available",
  "scheduled_date": "2022-12-05",
  "message": "invoice no12345",
  "internal_note": "phone bill"
}
Response example (200)
{
  "id": "61b05c4f-3f72-4951-8c30-a2a9faaa5184",
  "reference": "ab004cfc-99fb-4ba9-bc9c-70982f853cb1",
  "amount": 500,
  "currency": "EUR",
  "local_iban": "FR6430003000509825397888D64",
  "beneficiary_iban": "FR2512739000308553756377J95",
  "transfer_type": "standard",
  "type_strategy": "standard_only",
  "status": "failed",
  "failure_code": "insufficient_funds",
  "scheduled_date": "2023-05-04",
  "message": "invoice no12345",
  "internal_note": "phone bill"
}

Get a transfer

GET /v2/transfers/{id}

Path parameters

  • id string(uuid) Required

    ID of the transfer.

Responses

  • 200 object

    OK

    • id string(uuid) Required

      ID of the transfer

    • reference string(uuid) Required

      Unique reference, can be used to correlate with the resulting Transaction.

    • amount integer(int64) Required

      Amount of the transfer, in cents.

    • currency string Required

      Currency of the amount, in ISO 4217 format.

    • local_iban string Required

      IBAN used as a source of the transfer. It can be the main IBAN of an account or a virtual IBAN.

    • beneficiary_iban string Required

      IBAN of the beneficiary.

    • Type of the transfer. If the type strategy is instant_if_available, it can be missing while we determine the appropriate type.

      Values are standard or instant.

    • type_strategy string Required

      Strategy used when creating the transfer.

      Values are standard_only, instant_only, or instant_if_available.

    • status string Required

      Current status of the transfer.

      Values are pending, scheduled, authorized, confirmed, or failed.

    • Code that represents the failure reason when the transfer has failed:
      - insufficient_funds: Not enough funds on your account to execute the transfer.
      - execution_failure: The collection was executed but failed before settlement.
      - instant_transfer_not_available: The beneficiary can not receive instant transfers.
      - invalid_beneficiary_iban: The beneficiary's IBAN is invalid.
      - unreachable_beneficiary_iban: The beneficiary is unreachable for the given transfer type.
      - maximum_amount_exceeded: The transfer amount exceeds the limit.

      Values are insufficient_funds, execution_failure, instant_transfer_not_available, invalid_beneficiary_iban, unreachable_beneficiary_iban, or maximum_amount_exceeded.

    • scheduled_date string(date)

      Date on which the transfer was scheduled, if any.

    • message string

      Message attached to this transfer, visible by all involved parties.

    • Internal note attached to this transfer, visible only in your Memo Bank workspace.

GET /v2/transfers/{id}
curl \
 -X GET https://api.memo.bank/v2/transfers/aa431134-bdc4-416e-8b7e-58a39e389707 \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "id": "61b05c4f-3f72-4951-8c30-a2a9faaa5184",
  "reference": "ab004cfc-99fb-4ba9-bc9c-70982f853cb1",
  "amount": 500,
  "currency": "EUR",
  "local_iban": "FR6430003000509825397888D64",
  "beneficiary_iban": "FR2512739000308553756377J95",
  "transfer_type": "standard",
  "type_strategy": "standard_only",
  "status": "failed",
  "failure_code": "insufficient_funds",
  "scheduled_date": "2023-05-04",
  "message": "invoice no12345",
  "internal_note": "phone bill"
}

Webhook

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 create a Webhook in the web interface, in Company Settings > Developers. As part of this, you'll 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.

Consuming Events

Individual Events don't 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, we'll retry it 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.

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.

Handle an event

POST /event

Body Required

  • id string(uuid) Required

    ID of this event. Must be used for idempotence: an event with the same ID can be sent multiple times in case of error, but should only be processed once.

  • date string(date-time) Required

    Event creation date, in ISO8601 format.

  • event_type string Required

    Type of event. We may add additional possible types over time; your application should be able to handle such additions gracefully.

    Values are account_created, account_updated, account_closed, attachment_created, attachment_deleted, collection_confirmed, collection_failed, iban_created, iban_updated, iban_deleted, transaction_scheduled, transaction_authorized, transaction_confirmed, transaction_rejected, transaction_canceled, transfer_confirmed, or transfer_failed.

  • resource_type string Required

    Type of the resource referenced by this event. We may add additional possible source types over time; your application should be able to handle such additions gracefully.

    Values are account, attachment, collection, iban, transaction, or transfer.

  • resource_id string(uuid) Required

    ID of the resource referenced by this event.

Responses

POST event
Request example
{
  "id": "ad8340e7-0675-4182-9c95-520e7c9a72a3",
  "date": "2023-05-04T09:42:00+00:00",
  "event_type": "account_created",
  "resource_type": "account",
  "resource_id": "5400f1ad-788c-4bef-9ded-4d7afd8472d7"
}