Request and JSON Format Reference

This page contains the JSON format reference documentation of the Zilverline Banking API. It was compiled from the documentation of The Berlin Group, NextGenPSD2 XS2A Framework Implementation Guidelines (1.3.12), paragraph 6.5.4 Read Transaction List.

Conversion requests

HTTP Call

POST /mt940

POST /camt053

POST /upload

Transforms uploaded MT940 or CAMT.053 data to the JSON format as described below.

Request Header

Request Body

Response Header

Response Body

Response (Example)

Response in JSON format for an access on a regular account

HTTP/1.x 200 Ok
X-Request-ID:		99391c7e-ad88-49ec-a2ad-99ddcb1f7757
Content-Type:		application/json
[
  {
    "account": {
      "bic": "KNABNL2H",
      "iban": "NL92KNAB0123123123",
      "bban": "123123123",
      "currency": "EUR"
    },
    "balances": [
      {
        "balanceAmount": {
          "currency": "EUR",
          "amount": "1000.00"
        },
        "balanceType": "openingBooked",
        "referenceDate": "2016-04-22"
      },
      {
        "balanceAmount": {
          "currency": "EUR",
          "amount": "1010.00"
        },
        "balanceType": "closingBooked",
        "referenceDate": "2016-04-25"
      }
    ],
    "transactions": {
      "booked": [
        {
          "endToEndId": "3111211AA002222",
          "bookingDate": "2016-04-22",
          "valueDate": "2016-04-22",
          "transactionAmount": {
            "currency": "EUR",
            "amount": "10.00"
          },
          "debtorName": "ABABABABA AAAA SSSSSS",
          "debtorAccount": {
            "iban": "NL61RABO0242424242",
            "bban": "242424242",
            "currency": "EUR"
          },
          "debtorAgent": "KNABNL2HXXX",
          "remittanceInformationUnstructured": "201604-005",
          "additionalInformation": "SEPA OVERBOEKING",
          "bankTransactionCode": "N110",
          "providerSpecificData": {
            "bankName": "KNAB",
            "bankReference": "A123123123123122",
            "customerReference": "3111211AA002222",
            "mt940": ":61:1604220422C10,00N1103111211AA002222//A123123123123122\n:86:/TRTP/SEPA OVERBOEKING/IBAN/NL61RABO0242424242/BIC/KNABNL2HXXX/NAME/ABABABABA AAAA SSSSSS/EREF/3111211AA002222/REMI/201604-005"
          }
        }
      ]
    }
  }
]

Tamper Protection

The Open Banking API offers unique MT940 Tamper protection. The following checks are performed when the Tamper Protection is enabled with the parameter tamper_protection set to "1".

Opening / closing balance

Every bank statement in MT940 has an opening and closing balance. The Tamper Protection service checks if the difference between this opening and closing balance matches with the sum of all transactions in the bank statement.

When this does not match, it means the bank statement is not complete or has been tampered with. An error with the code "TAMPER_PROTECTION" and extra text will be returned.

Opening / closing balance reference dates

Every bank statement in MT940 has an opening and closing balance reference date. The Tamper Protection service checks if the closing balance date is at or after the opening balance reference date.

When the closing balance date is before the opening balance date, the bank statement has invalid or corrupted data. An error with the code "TAMPER_PROTECTION" and extra text will be returned.

ING & Van Lanschot bank checks

With the MT940 data from the ING and Van Lanschot banks, a special Tag 86 (Totals hash) is usually added to the end of each bank statement. With these totals, extra checks can be performed.

Amount of debit transactions

The Tag 86 totals hash contains the amount of debit transactions. The Tamper Protection service checks if this matches with the amount of debit transactions in the bank statement.

If it does not match, a debit transaction may be missing meaning the bank statement has invalid or corrupted data. An error with the code "TAMPER_PROTECTION" and extra text will be returned.

Amount of credit transactions

The Tag 86 totals hash contains the amount of credit transactions. The Tamper Protection service checks if this matches with the amount of credit transactions in the bank statement.

If it does not match, a credit transaction may be missing meaning the bank statement has invalid or corrupted data. An error with the code "TAMPER_PROTECTION" and extra text will be returned.

Sum of debit transactions

The Tag 86 totals hash contains the sum of debit transaction amounts. The Tamper Protection service checks if this matches with the amount of actual debit transactions in the bank statement.

If it does not match, a debit transaction may have a changed amount or a debit transaction may be missing, meaning the bank statement has invalid or corrupted data. An error with the code "TAMPER_PROTECTION" and extra text will be returned.

Sum of credit transactions

The Tag 86 totals hash contains the sum of credit transaction amounts. The Tamper Protection service checks if this matches with the amount of actual credit transactions in the bank statement.

If it does not match, a credit transaction may have a changed amount or a credit transaction may be missing, meaning the bank statement has invalid or corrupted data. An error with the code "TAMPER_PROTECTION" and extra text will be returned.

Response in Error Cases

In order to achieve a better readability, the main part of the document describes responses in case of a positive processing result only. The following section gives specific rules for the case of a negative processing result.

Header

In general, the same rules regarding the presence of header elements apply for both positive and negative responses. An exception is made for cases where an error occurred before functional processing. Examples for such error cases are general server errors (typically with 50x http response code) and – depending on the implementation – the validation of the certificate. In those error cases, the specified headers may be omitted.

Additional Error Information

The NextGenPSD2 XS2A specification offers a proprietary way to transport additional error information. In this solution, the additional error information is sent to the TPP using the data element tppMessageInformation with the attribute category set to "ERROR". The attribute "code" indicates the unique error code. It will further offer a free text field to describe the error context or actions to be taken to the TPP.

Response Code

The HTTP response code will be usually 400 or 500 for unexpected errors.

Response Header

Response Body

Example 1 (Access token not correct):

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "TOKEN_INVALID",
      "text": "additional text information"
    }
  ]
}

Example 2 (No file given):

{
  "tppMessages": [
    {
      "category": "ERROR",
      "code": "MISSING_FILE",
      "text": "Bad file or file not specified in 'file' parameter"
    }
  ]
}

Account Reference

This type contains any account identification which can be used on payload-level to address specific accounts. Exactly one of the attributes defined as "conditional" shall be used.

Remark: The currency of the account is needed, where the currency is an account characteristic identifying certain sub-accounts under one external identifier like an IBAN. These sub-accounts are separated accounts from a legal point of view and have separated balances, transactions etc.

Amount

Balance

Balance Type value

Account Report

Transaction

Provider Specific Data

This type contains extra data not originally included in the NextGenPSD2 format.

Remittance

TPP Message Information