Memo Bank API
1.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 1.0 of the API. Last update on Mar 17, 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:

a certificate and its SHA256 thumbprint;
a secret code;
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 /v1/accounts/{id}

Path parameters

id string(uuid) Required

ID of the account.

Memo Bank API 1.0

Body Required

Body Required

Body Required

Body Required

Memo Bank API
1.0