Memo Bank NextGenPSD2 API
1.0

Introduction

Memo Bank NextGenPSD2 API allows Third Party Providers to access account information on behalf of customers.

The API follows BerlinGroup NextGenPSD2 Implementation Guidelines as of version 1.3.11.
This document describe our implementation choices and where we have drifted away from the guidelines.

All non-absolute paths described in this document are relatives to the base URL of the server (https://api.memo.bank/nextgenpsd2).

Onboarding

For TPPs to be able to make a request on the API, they must follow the onboarding process. For that, it is required for them to provide the following elements :

  • a logo
  • a redirect URI for OAuth2 authentication
  • a valid QSealC certificate

In exchange of what they will receive :

  • a client_id and a client_secret to be used with OAuth2 authentication
  • a username to be used with HTTP Signature authentication

Authentication

OAuth2

We use OAuth2 as a pre-step to authenticate the PSU.

The access_token has a TTL of 2 hours and the refresh_token has a TTL of 2 weeks.

The TPP should refresh the token before expiration in order to reuse the same consent for the next requests.

HTTP Signature

Requests must be signed by TPPs using the private key associated to the certificate provided during the onboarding process.

Here is an exhaustive list of headers that must be signed :

  • @request-target (mandatory)
  • authorization (mandatory)
  • date (mandatory)
  • digest (only if the request has a body)
  • host (mandatory)
  • psu-corporate-id (only if included in the request)
  • psu-id (only if included in the request)
  • tpp-redirect-uri (only if included in the request)
  • x-request-id (only if included in the request)

The special header @request-target should be used in place of (request-target) described in draft-cavage-http-signatures-12.

In the Signature header, a username field must be provided instead of a keyId field. This username is obtained during the onboarding process.

Consent is given during the OAuth2 pre-step authentication and linked to an access_token/refresh_token pair.

Every consent gives access to its accounts balances and transactions history. They also have an unlimited usage frequency.

/consents endpoints are not implemented yet.

Response formats

Success cases

The API only support application/json content type.

Error cases

In case of processing error, the API will use NextGenPSD2 specific solution to give additional error information in the response.

Some errors won't follow this format if they are sent by a proxy between the client and the application. This is the case with most authentication errors as of now.

There is no support for the application/problem+json content type from RFC7807.

This is the documentation for version 1.0 of the API. Last update on Aug 3, 2022.

Base URL
https://api.memo.bank/nextgenpsd2

Authentication

O auth2 (oauth2)

Retrieve an Access Token with the Oauth flows described below before accessing the API. Once you have an access token, send it in the Authorization http header to authenticate with the API.

Flow type Authorization URL Token URL Refresh URL scopes
authorizationCode https://client.memo.bank/authorize /oauth2/token /oauth2/token
  • AIS: Account Information Service.
  • PIS: Payment Initiation Service.
  • PIIS: Confirmation of Funds Service.


Read account details

GET /v1/accounts/{accountId}

Path parameters

Responses

GET /v1/accounts/{accountId}
curl \
 -X GET https://api.memo.bank/nextgenpsd2/v1/accounts/{accountId} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (default)
{
  "account": {
    "currency": "string",
    "resourceId": "string",
    "iban": "string",
    "bban": "string",
    "name": "string",
    "displayName": "string",
    "product": "string",
    "cashAccountType": "string",
    "status": "enabled",
    "bic": "string",
    "usage": "PRIV",
    "balances": [
      {
        "balanceAmount": {
          "currency": "string",
          "amount": "string"
        },
        "balanceType": "closingBooked",
        "creditLimitIncluded": true,
        "referenceDate": "2022-05-04"
      }
    ],
    "_links": {
      "balances": {
        "href": "string"
      },
      "transactions": {
        "href": "string"
      }
    },
    "ownerName": "string"
  }
}

Read account list

GET /v1/accounts

Responses

GET /v1/accounts
curl \
 -X GET https://api.memo.bank/nextgenpsd2/v1/accounts \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (default)
{
  "accounts": [
    {
      "currency": "string",
      "resourceId": "string",
      "iban": "string",
      "bban": "string",
      "name": "string",
      "displayName": "string",
      "product": "string",
      "cashAccountType": "string",
      "status": "enabled",
      "bic": "string",
      "usage": "PRIV",
      "balances": [
        {
          "balanceAmount": {
            "currency": "string",
            "amount": "string"
          },
          "balanceType": "closingBooked",
          "creditLimitIncluded": true,
          "referenceDate": "2022-05-04"
        }
      ],
      "_links": {
        "balances": {
          "href": "string"
        },
        "transactions": {
          "href": "string"
        }
      },
      "ownerName": "string"
    }
  ]
}

Read balance

GET /v1/accounts/{accountId}/balances

Path parameters

Responses

GET /v1/accounts/{accountId}/balances
curl \
 -X GET https://api.memo.bank/nextgenpsd2/v1/accounts/{accountId}/balances \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (default)
{
  "account": {
    "iban": "string",
    "bban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "balances": [
    {
      "balanceAmount": {
        "currency": "string",
        "amount": "string"
      },
      "balanceType": "closingBooked",
      "creditLimitIncluded": true,
      "referenceDate": "2022-05-04"
    }
  ]
}

Read transaction details

GET /v1/accounts/{accountId}/transactions/{transactionId}

Path parameters

Responses

GET /v1/accounts/{accountId}/transactions/{transactionId}
curl \
 -X GET https://api.memo.bank/nextgenpsd2/v1/accounts/{accountId}/transactions/{transactionId} \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (default)
{
  "transactionsDetails": {
    "transactionAmount": {
      "currency": "string",
      "amount": "string"
    },
    "transactionId": "string",
    "endToEndId": "string",
    "batchIndicator": true,
    "batchNumberOfTransactions": 42,
    "mandateId": "string",
    "bookingDate": "2022-05-04",
    "valueDate": "2022-05-04",
    "currencyExchange": [
      {
        "sourceCurrency": "string",
        "exchangeRate": "string",
        "unitCurrency": "string",
        "targetCurrency": "string",
        "quotationDate": "2022-05-04"
      }
    ],
    "creditorName": "string",
    "creditorAccount": {
      "iban": "string",
      "bban": "string",
      "currency": "string",
      "cashAccountType": "string"
    },
    "creditorAgent": "string",
    "debtorName": "string",
    "debtorAccount": {
      "iban": "string",
      "bban": "string",
      "currency": "string",
      "cashAccountType": "string"
    },
    "debtorAgent": "string",
    "remittanceInformationUnstructured": "string",
    "entryDetails": [
      {
        "transactionAmount": {
          "currency": "string",
          "amount": "string"
        },
        "endToEndId": "string",
        "mandateId": "string",
        "currencyExchange": [
          {
            "sourceCurrency": "string",
            "exchangeRate": "string",
            "unitCurrency": "string",
            "targetCurrency": "string",
            "quotationDate": "2022-05-04"
          }
        ],
        "creditorName": "string",
        "creditorAccount": {
          "iban": "string",
          "bban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "creditorAgent": "string",
        "debtorName": "string",
        "debtorAccount": {
          "iban": "string",
          "bban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "debtorAgent": "string",
        "remittanceInformationUnstructured": "string"
      }
    ],
    "_extras": {
      "counterpartyAndRemittanceInformationUnstructured": "string"
    }
  }
}

Read transaction list of an account

GET /v1/accounts/{accountId}/transactions

Path parameters

Query parameters

  • bookingStatus Required string

    Supported values are : booked, pending and both.

    Values are information, booked, pending, both, or all.

  • dateFrom string(date)
  • dateTo string(date)
  • Unsupported.

  • deltaList boolean

    Unsupported.

  • orderBy string

    Supported values are : bookingDate, -bookingDate.

    Default value is bookingDate.

  • page integer(int32)

    Minimum value is 1. Default value is 1.

  • size integer(int32)

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

Responses

GET /v1/accounts/{accountId}/transactions
curl \
 -X GET https://api.memo.bank/nextgenpsd2/v1/accounts/{accountId}/transactions?bookingStatus=information \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (default)
{
  "account": {
    "iban": "string",
    "bban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "balances": [
    {
      "balanceAmount": {
        "currency": "string",
        "amount": "string"
      },
      "balanceType": "closingBooked",
      "creditLimitIncluded": true,
      "referenceDate": "2022-05-04"
    }
  ],
  "transactions": {
    "_links": {
      "account": {
        "href": "string"
      },
      "first": {
        "href": "string"
      },
      "next": {
        "href": "string"
      },
      "previous": {
        "href": "string"
      },
      "last": {
        "href": "string"
      }
    },
    "booked": [
      {
        "transactionAmount": {
          "currency": "string",
          "amount": "string"
        },
        "transactionId": "string",
        "endToEndId": "string",
        "batchIndicator": true,
        "batchNumberOfTransactions": 42,
        "mandateId": "string",
        "bookingDate": "2022-05-04",
        "valueDate": "2022-05-04",
        "currencyExchange": [
          {
            "sourceCurrency": "string",
            "exchangeRate": "string",
            "unitCurrency": "string",
            "targetCurrency": "string",
            "quotationDate": "2022-05-04"
          }
        ],
        "creditorName": "string",
        "creditorAccount": {
          "iban": "string",
          "bban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "creditorAgent": "string",
        "debtorName": "string",
        "debtorAccount": {
          "iban": "string",
          "bban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "debtorAgent": "string",
        "remittanceInformationUnstructured": "string",
        "entryDetails": [
          {
            "transactionAmount": {
              "currency": "string",
              "amount": "string"
            },
            "endToEndId": "string",
            "mandateId": "string",
            "currencyExchange": [
              {
                "sourceCurrency": "string",
                "exchangeRate": "string",
                "unitCurrency": "string",
                "targetCurrency": "string",
                "quotationDate": "2022-05-04"
              }
            ],
            "creditorName": "string",
            "creditorAccount": {
              "iban": "string",
              "bban": "string",
              "currency": "string",
              "cashAccountType": "string"
            },
            "creditorAgent": "string",
            "debtorName": "string",
            "debtorAccount": {
              "iban": "string",
              "bban": "string",
              "currency": "string",
              "cashAccountType": "string"
            },
            "debtorAgent": "string",
            "remittanceInformationUnstructured": "string"
          }
        ],
        "_extras": {
          "counterpartyAndRemittanceInformationUnstructured": "string"
        }
      }
    ],
    "pending": [
      {
        "transactionAmount": {
          "currency": "string",
          "amount": "string"
        },
        "transactionId": "string",
        "endToEndId": "string",
        "batchIndicator": true,
        "batchNumberOfTransactions": 42,
        "mandateId": "string",
        "bookingDate": "2022-05-04",
        "valueDate": "2022-05-04",
        "currencyExchange": [
          {
            "sourceCurrency": "string",
            "exchangeRate": "string",
            "unitCurrency": "string",
            "targetCurrency": "string",
            "quotationDate": "2022-05-04"
          }
        ],
        "creditorName": "string",
        "creditorAccount": {
          "iban": "string",
          "bban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "creditorAgent": "string",
        "debtorName": "string",
        "debtorAccount": {
          "iban": "string",
          "bban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "debtorAgent": "string",
        "remittanceInformationUnstructured": "string",
        "entryDetails": [
          {
            "transactionAmount": {
              "currency": "string",
              "amount": "string"
            },
            "endToEndId": "string",
            "mandateId": "string",
            "currencyExchange": [
              {
                "sourceCurrency": "string",
                "exchangeRate": "string",
                "unitCurrency": "string",
                "targetCurrency": "string",
                "quotationDate": "2022-05-04"
              }
            ],
            "creditorName": "string",
            "creditorAccount": {
              "iban": "string",
              "bban": "string",
              "currency": "string",
              "cashAccountType": "string"
            },
            "creditorAgent": "string",
            "debtorName": "string",
            "debtorAccount": {
              "iban": "string",
              "bban": "string",
              "currency": "string",
              "cashAccountType": "string"
            },
            "debtorAgent": "string",
            "remittanceInformationUnstructured": "string"
          }
        ],
        "_extras": {
          "counterpartyAndRemittanceInformationUnstructured": "string"
        }
      }
    ]
  }
}