Memo Bank NextGenPSD2 API
1.0

Memo Bank NextGenPSD2 API allows Third Party Providers to access account information and initiate payments 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 (e.g. https://api.memo.bank/nextgenpsd2 for the production environment).

This is the documentation for version 1.0 of the API. Last update on Jan 3, 2023.

Base URL
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 from them to send us an email with the following elements :

  • 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.

Authentication

OAuth2

We use the standard Authorization Code grant flow from OAuth2 to authenticate a TPP on behalf of a PSU.

As an example, in production our URLs are:

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

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 has the same value as the client_id obtained during the onboarding process.

Response formats

Success cases

Only the application/json content type is supported.

Error cases

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

Some errors may not 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.

The application/problem+json content type from RFC7807 is not currently supported.

Authorisation

Authorisations for a consent or a payment are always implicitly created and the /authorisations sub-resources are not implemented.


AIS

Account Information Service.

Consent is given using the OAuth2 as a pre-step authentication flow described in NextGenPSD2 specifications.
This means you don't have to manage consents using the dedicated endpoints (which are not implemented), but only to redirect the PSU to our authorisation page (using AIS as OAuth2 scope).
After performing a strong customer authentication, the PSU will be redirected to your redirect URI with an authorisation code that you can then exchange for an access token.

This access token will let you authenticate at the XS2A interface to request the PSU accounts balances and transactions history.

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" \
 -H "Signature: $SIGNATURE"
Response example (default)
{
  "account": {
    "currency": "string",
    "resourceId": "string",
    "iban": "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": "2023-05-04"
      }
    ],
    "_links": {
      "balances": {
        "href": "string"
      },
      "transactions": {
        "href": "string"
      }
    },
    "ownerName": "string"
  }
}

Responses

GET /v1/accounts
curl \
 -X GET https://api.memo.bank/nextgenpsd2/v1/accounts \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Signature: $SIGNATURE"
Response example (default)
{
  "accounts": [
    {
      "currency": "string",
      "resourceId": "string",
      "iban": "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": "2023-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" \
 -H "Signature: $SIGNATURE"
Response example (default)
{
  "account": {
    "iban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "balances": [
    {
      "balanceAmount": {
        "currency": "string",
        "amount": "string"
      },
      "balanceType": "closingBooked",
      "creditLimitIncluded": true,
      "referenceDate": "2023-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" \
 -H "Signature: $SIGNATURE"
Response example (default)
{
  "transactionsDetails": {
    "transactionAmount": {
      "currency": "string",
      "amount": "string"
    },
    "transactionId": "string",
    "endToEndId": "string",
    "batchIndicator": true,
    "batchNumberOfTransactions": 42,
    "mandateId": "string",
    "bookingDate": "2023-05-04",
    "valueDate": "2023-05-04",
    "currencyExchange": [
      {
        "sourceCurrency": "string",
        "exchangeRate": "string",
        "unitCurrency": "string",
        "targetCurrency": "string",
        "quotationDate": "2023-05-04"
      }
    ],
    "creditorName": "string",
    "creditorAccount": {
      "iban": "string",
      "currency": "string",
      "cashAccountType": "string"
    },
    "creditorAgent": "string",
    "debtorName": "string",
    "debtorAccount": {
      "iban": "string",
      "currency": "string",
      "cashAccountType": "string"
    },
    "debtorAgent": "string",
    "remittanceInformationUnstructured": "string",
    "_extras": {
      "counterpartyAndRemittanceInformationUnstructured": "string"
    }
  }
}

Read transaction list of an account

GET /v1/accounts/{accountId}/transactions

You can retrieve the full transactions history of an account, it is not limited to 90 days.

Path parameters

Query parameters

  • bookingStatus string Required

    Values are booked, pending, or both.

  • dateFrom string(date)
  • dateTo string(date)
  • orderBy string

    Values are bookingDate or -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=booked \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Signature: $SIGNATURE"
Response example (default)
{
  "account": {
    "iban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "balances": [
    {
      "balanceAmount": {
        "currency": "string",
        "amount": "string"
      },
      "balanceType": "closingBooked",
      "creditLimitIncluded": true,
      "referenceDate": "2023-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": "2023-05-04",
        "valueDate": "2023-05-04",
        "currencyExchange": [
          {
            "sourceCurrency": "string",
            "exchangeRate": "string",
            "unitCurrency": "string",
            "targetCurrency": "string",
            "quotationDate": "2023-05-04"
          }
        ],
        "creditorName": "string",
        "creditorAccount": {
          "iban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "creditorAgent": "string",
        "debtorName": "string",
        "debtorAccount": {
          "iban": "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": "2023-05-04",
        "valueDate": "2023-05-04",
        "currencyExchange": [
          {
            "sourceCurrency": "string",
            "exchangeRate": "string",
            "unitCurrency": "string",
            "targetCurrency": "string",
            "quotationDate": "2023-05-04"
          }
        ],
        "creditorName": "string",
        "creditorAccount": {
          "iban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "creditorAgent": "string",
        "debtorName": "string",
        "debtorAccount": {
          "iban": "string",
          "currency": "string",
          "cashAccountType": "string"
        },
        "debtorAgent": "string",
        "remittanceInformationUnstructured": "string",
        "_extras": {
          "counterpartyAndRemittanceInformationUnstructured": "string"
        }
      }
    ]
  }
}

PIS

Payment Initiation Service.

Payment initiation is done using the integrated OAuth2 authentication flow described in NextGenPSD2 specifications.
This means you first have to initiate a payment using the dedicated endpoint, then redirect the PSU to our authorisation page following the link present in the response (using PIS:{paymentId} as OAuth2 scope).
After performing a strong customer authentication, the PSU will be redirected to your redirect URI with an authorisation code that you can then exchange for an access token.

This access token is only needed to cancel a payment on behalf a PSU (this does not require a strong customer authentication). It is not needed to retrieve the current status of a payment.

Get payment information

GET /v1/{payment-service}/{payment-product}/{paymentId}

Path parameters

Responses

  • 200 object

    OK

    One of:
GET /v1/{payment-service}/{payment-product}/{paymentId}
curl \
 -X GET https://api.memo.bank/nextgenpsd2/v1/{payment-service}/{payment-product}/{paymentId} \
 -H "Signature: $SIGNATURE"
Response examples (200)
{
  "debtorAccount": {
    "iban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "instructedAmount": {
    "currency": "string",
    "amount": "string"
  },
  "creditorAccount": {
    "iban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "creditorName": "string",
  "endToEndIdentification": "string",
  "remittanceInformationUnstructured": "string",
  "requestedExecutionDate": "2023-05-04",
  "transactionStatus": "ACSC",
  "tppMessage": [
    {
      "category": "ERROR",
      "code": "ACCESS_EXCEEDED",
      "path": "string",
      "text": "string"
    }
  ]
}
{
  "debtorAccount": {
    "iban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "payments": [
    {
      "instructedAmount": {
        "currency": "string",
        "amount": "string"
      },
      "creditorAccount": {
        "iban": "string",
        "currency": "string",
        "cashAccountType": "string"
      },
      "creditorName": "string",
      "endToEndIdentification": "string",
      "remittanceInformationUnstructured": "string"
    }
  ],
  "requestedExecutionDate": "2023-05-04",
  "transactionStatus": "ACSC",
  "tppMessage": [
    {
      "category": "ERROR",
      "code": "ACCESS_EXCEEDED",
      "path": "string",
      "text": "string"
    }
  ]
}

Cancel a payment.

DELETE /v1/{payment-service}/{payment-product}/{paymentId}

Path parameters

Responses

DELETE /v1/{payment-service}/{payment-product}/{paymentId}
curl \
 -X DELETE https://api.memo.bank/nextgenpsd2/v1/{payment-service}/{payment-product}/{paymentId} \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Signature: $SIGNATURE"
Response example (default)
{
  "transactionStatus": "ACSC"
}

Get payment initiation status

GET /v1/{payment-service}/{payment-product}/{paymentId}/status

Path parameters

Responses

  • default object

    default response

    • transactionStatus string Required

      Values are ACSC, RCVD, PDNG, RJCT, CANC, ACFC, or PART.

    • Minimum length is 0, maximum length is 500.

    • tppMessage array[object]
      • category string Required

        Values are ERROR or WARNING.

      • code string Required

        Values are ACCESS_EXCEEDED, BENEFICIARY_WHITELISTING_REQUIRED, CANCELLATION_INVALID, CERTIFICATE_BLOCKED, CERTIFICATE_EXPIRED, CERTIFICATE_INVALID, CERTIFICATE_MISSING, CERTIFICATE_REVOKE, CONSENT_EXPIRED, CONSENT_INVALID, CONSENT_UNKNOWN, CORPORATE_ID_INVALID, EXECUTION_DATE_INVALID, FORMAT_ERROR, FUNDS_NOT_AVAILABLE, KID_MISSING, PARAMETER_NOT_CONSISTENT, PARAMETER_NOT_SUPPORTED, PAYMENT_FAILED, PERIOD_INVALID, PRODUCT_INVALID, PRODUCT_UNKNOWN, PSU_CREDENTIALS_INVALID, REQUESTED_FORMATS_INVALID, RESOURCE_BLOCKED, RESOURCE_EXPIRED, RESOURCE_UNKNOWN, ROLE_INVALID, SCA_INVALID, SCA_METHOD_UNKNOWN, SERVICE_BLOCKED, SERVICE_INVALID, SESSIONS_NOT_SUPPORTED, SIGNATURE_INVALID, SIGNATURE_MISSING, STATUS_INVALID, TIMESTAMP_INVALID, TOKEN_EXPIRED, TOKEN_INVALID, TOKEN_UNKNOWN, or WARNING.

      • path string
      • text string

        Minimum length is 0, maximum length is 500.

GET /v1/{payment-service}/{payment-product}/{paymentId}/status
curl \
 -X GET https://api.memo.bank/nextgenpsd2/v1/{payment-service}/{payment-product}/{paymentId}/status \
 -H "Signature: $SIGNATURE"
Response example (default)
{
  "transactionStatus": "ACSC",
  "psuMessage": "string",
  "tppMessage": [
    {
      "category": "ERROR",
      "code": "ACCESS_EXCEEDED",
      "path": "string",
      "text": "string"
    }
  ]
}

Initiate a payment

POST /v1/{payment-service}/{payment-product}

Path parameters

  • payment-service string Required

    Values are payments or bulk-payments.

  • payment-product string Required

    Values are sepa-credit-transfers or instant-sepa-credit-transfers.

Body object

One of:

Responses

  • default object

    default response

    • transactionStatus string Required

      Values are ACSC, RCVD, PDNG, RJCT, CANC, ACFC, or PART.

    • paymentId string Required
    • Minimum length is 0, maximum length is 500.

    • tppMessages array[object]
      • category string Required

        Values are ERROR or WARNING.

      • code string Required

        Values are ACCESS_EXCEEDED, BENEFICIARY_WHITELISTING_REQUIRED, CANCELLATION_INVALID, CERTIFICATE_BLOCKED, CERTIFICATE_EXPIRED, CERTIFICATE_INVALID, CERTIFICATE_MISSING, CERTIFICATE_REVOKE, CONSENT_EXPIRED, CONSENT_INVALID, CONSENT_UNKNOWN, CORPORATE_ID_INVALID, EXECUTION_DATE_INVALID, FORMAT_ERROR, FUNDS_NOT_AVAILABLE, KID_MISSING, PARAMETER_NOT_CONSISTENT, PARAMETER_NOT_SUPPORTED, PAYMENT_FAILED, PERIOD_INVALID, PRODUCT_INVALID, PRODUCT_UNKNOWN, PSU_CREDENTIALS_INVALID, REQUESTED_FORMATS_INVALID, RESOURCE_BLOCKED, RESOURCE_EXPIRED, RESOURCE_UNKNOWN, ROLE_INVALID, SCA_INVALID, SCA_METHOD_UNKNOWN, SERVICE_BLOCKED, SERVICE_INVALID, SESSIONS_NOT_SUPPORTED, SIGNATURE_INVALID, SIGNATURE_MISSING, STATUS_INVALID, TIMESTAMP_INVALID, TOKEN_EXPIRED, TOKEN_INVALID, TOKEN_UNKNOWN, or WARNING.

      • path string
      • text string

        Minimum length is 0, maximum length is 500.

POST /v1/{payment-service}/{payment-product}
curl \
 -X POST https://api.memo.bank/nextgenpsd2/v1/{payment-service}/{payment-product} \
 -H "Content-Type: application/json" \
 -H "Signature: $SIGNATURE" \
 -d '{"debtorAccount":{"iban":"string","currency":"string","cashAccountType":"string"},"instructedAmount":{"currency":"string","amount":"string"},"creditorAccount":{"iban":"string","currency":"string","cashAccountType":"string"},"creditorName":"string","endToEndIdentification":"string","remittanceInformationUnstructured":"string","requestedExecutionDate":"2023-05-04"}'
Request examples
# Headers
Signature: $SIGNATURE

# Payload
{
  "debtorAccount": {
    "iban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "instructedAmount": {
    "currency": "string",
    "amount": "string"
  },
  "creditorAccount": {
    "iban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "creditorName": "string",
  "endToEndIdentification": "string",
  "remittanceInformationUnstructured": "string",
  "requestedExecutionDate": "2023-05-04"
}
# Headers
Signature: $SIGNATURE

# Payload
{
  "debtorAccount": {
    "iban": "string",
    "currency": "string",
    "cashAccountType": "string"
  },
  "payments": [
    {
      "instructedAmount": {
        "currency": "string",
        "amount": "string"
      },
      "creditorAccount": {
        "iban": "string",
        "currency": "string",
        "cashAccountType": "string"
      },
      "creditorName": "string",
      "endToEndIdentification": "string",
      "remittanceInformationUnstructured": "string"
    }
  ],
  "requestedExecutionDate": "2023-05-04"
}
Response example (default)
{
  "transactionStatus": "ACSC",
  "paymentId": "string",
  "_links": {
    "self": {
      "href": "string"
    },
    "status": {
      "href": "string"
    }
  },
  "psuMessage": "string",
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "ACCESS_EXCEEDED",
      "path": "string",
      "text": "string"
    }
  ]
}