Interface Documentation
The implementation of this XS2A interface is based on the Implementation Guidelines of the Berlin Group. The functions supported correspond to those offered in the corresponding online banking functions. No endpoints are provided for services related to card accounts and signing baskets, since these functions are not equally available in online banking.
The Implementation Guidelines define some functionality and subprocesses as optional. Which of these are supported can be found on the corresponding page.
Currently all responses of this interface are encoded in JSON format. Camt.05x and MT94X formats are not supported.
A TLS-connection secures the endpoints provided by this XS2A interface. It is mandatory that the TPP uses a qualified certificate for website authentication (QWAC), which has been issued by a qualified trust service provider according to the eIDAS regulation. The client certificate has to indicate all roles the TPP is authorised to use.
Supported trust service providers can be found in the Trusted List Browser by the European Commission.
According to the Implementation Guidelines, the signing of messages at application layer (electronic seals, QSealC) can be prescribed. This is not the case for this XS2A interface. Message signing is not supported.
This XS2A interface implies a 1:1 relationship between the resources to be created and the authorisation sub-resources. This simplification is possible, because no signing baskets are provided and payment orders must always be released by a single person, i.e., no need for multiple SCA. Thus, the creation of a resource to be released by SCA is always accompanied by the creation of an associated authorisation sub-resource (implicit start of the authorisation process).
The SCA redirect approach is supported. Since the authentication process is implicitly started, the parameter TPP-Redirect-URI is always mandatory. This differes from the Implementation Guidelines, which define a conditional usage.
For the reasons given above, the explicit creation and modification (PUT method) of authorisation sub-resources is not required and is not supported.
The combination of AIS and PIS services (sessions) is not supported by this XS2A interface.
| name | path | methods | description |
|---|---|---|---|
| Account Information Services |
|
|
These endpoints provide account information services and functions for creating and querying consents. |
| Funds Confirmation Services |
|
|
Creates a confirmation of funds request at the ASPSP. This operation is currently not supported. |
| Payment Initiation Services |
|
|
Payment endpoints for initiation, cancellation and querying of payments. |
| type | description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| AccountAccess | Requested access services for a consent. | ||||||||||||||||
| AccountDetails | The ASPSP shall give at least one of the account reference identifiers: - iban - bban - pan - maskedPan - msisdn If the account is a multicurrency account currency code in \"currency\" is set to \"XXX\". | ||||||||||||||||
| AccountList | List of accounts with details. | ||||||||||||||||
| AccountReference | Reference to an account by either * IBAN, of a payment accounts, or * BBAN, for payment accounts if there is no IBAN, or * the Primary Account Number (PAN) of a card, can be tokenised by the ASPSP due to PCI DSS requirements, or * the Primary Account Number (PAN) of a card in a masked form, or * an alias to access a payment account via a registered mobile phone number (MSISDN). | ||||||||||||||||
| AccountReport | JSON based account report. This account report contains transactions resulting from the query parameters. 'booked' shall be contained if bookingStatus parameter is set to \"booked\" or \"both\". 'pending' is not contained if the bookingStatus parameter is set to \"booked\". | ||||||||||||||||
| AccountStatus | Account status. The value is one of the following: - \"enabled\": account is available - \"deleted\": account is terminated - \"blocked\": account is blocked e.g. for legal reasons If this field is not used, than the account is available in the sense of this specification. | ||||||||||||||||
| AdditionalInformationAccess | Optional if supported by API provider. Is asking for additional information as added within this structured object. The usage of this data element requires at least one of the entries \"accounts\", \"transactions\" or \"balances\" also to be contained in the object. If detailed accounts are referenced, it is required in addition that any account addressed within the additionalInformation attribute is also addressed by at least one of the attributes \"accounts\", \"transactions\" or \"balances\". | ||||||||||||||||
| AdditionalInformationStructured | Is used if and only if the bookingStatus entry equals \"information\". Every active standing order related to the dedicated payment account result into one entry. | ||||||||||||||||
| Amount | |||||||||||||||||
| AuthenticationObject | Authentication object. | ||||||||||||||||
| AuthenticationType | Type of the authentication method. More authentication types might be added during implementation projects and documented in the ASPSP documentation. - 'SMS_OTP': An SCA method, where an OTP linked to the transaction to be authorised is sent to the PSU through a SMS channel. - 'CHIP_OTP': An SCA method, where an OTP is generated by a chip card, e.g. a TOP derived from an EMV cryptogram. To contact the card, the PSU normally needs a (handheld) device. With this device, the PSU either reads the challenging data through a visual interface like flickering or the PSU types in the challenge through the device key pad. The device then derives an OTP from the challenge data and displays the OTP to the PSU. - 'PHOTO_OTP': An SCA method, where the challenge is a QR code or similar encoded visual data which can be read in by a consumer device or specific mobile app. The device resp. the specific app than derives an OTP from the visual challenge data and displays the OTP to the PSU. - 'PUSH_OTP': An OTP is pushed to a dedicated authentication APP and displayed to the PSU. | ||||||||||||||||
| Authorisations | An array of all authorisationIds. | ||||||||||||||||
| Balance | A single balance element. | ||||||||||||||||
| BalanceType | The following balance types are defined: - \"closingBooked\": Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. For card-accounts, this is composed of - invoiced, but not yet paid entries - \"expected\": Balance composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. For card accounts, this is composed of: - invoiced, but not yet paid entries - not yet invoiced but already booked entries and - pending items (not yet booked) For card-accounts: \"money to spend with the value of a pre-approved credit limit on the card account\" - \"openingBooked\": Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. - \"interimAvailable\": Available balance calculated in the course of the account ?servicer?s business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. For card-accounts, this is composed of: - invoiced, but not yet paid entries - not yet invoiced but already booked entries - \"interimBooked\": Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. - \"forwardAvailable\": Forward available balance of money that is at the disposal of the account owner on the date specified. - \"nonInvoiced\": Only for card accounts, to be checked yet. | ||||||||||||||||
| ChallengeData | It is contained in addition to the data element 'chosenScaMethod' if challenge data is needed for SCA. In rare cases this attribute is also used in the context of the 'startAuthorisationWithPsuAuthentication' link. | ||||||||||||||||
| ConfirmationOfFunds | JSON Request body for the \"Confirmation of funds service\".
|
||||||||||||||||
| ConsentInformationResponse200Json | Body of the JSON response for a successfull get consent request. | ||||||||||||||||
| ConsentStatus | This is the overall lifecycle status of the consent. Valid values are: - 'received': The consent data have been received and are technically correct. The data is not authorised yet. - 'rejected': The consent data have been rejected e.g. since no successful authorisation has taken place. - 'valid': The consent is accepted and valid for GET account data calls and others as specified in the consent object. - 'revokedByPsu': The consent has been revoked by the PSU towards the ASPSP. - 'expired': The consent expired. - 'terminatedByTpp': The corresponding TPP has terminated the consent by applying the DELETE method to the consent resource. - 'partiallyAuthorised': The consent is due to a multi-level authorisation, some but not all mandated authorisations have been performed yet. The ASPSP might add further codes. These codes then shall be contained in the ASPSP's documentation of the XS2A interface and has to be added to this API definition as well. | ||||||||||||||||
| ConsentStatusResponse200 | Body of the JSON response for a successful get status request for a consent. | ||||||||||||||||
| Consents | Content of the body of a consent request. | ||||||||||||||||
| ConsentsResponse201 | Body of the JSON response for a successful consent request. | ||||||||||||||||
| DayOfExecution | Day of execution as string. This string consists of up two characters. Leading zeroes are not allowed. 31 is ultimo of the month. | ||||||||||||||||
| Error405NGAIS | NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 401. | ||||||||||||||||
| Error405NGPIIS | NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 401. | ||||||||||||||||
| Error405NGPIS | NextGenPSD2 specific definition of reporting error information in case of a HTTP error code 401. | ||||||||||||||||
| ExecutionRule | \"following\" or \"preceding\" supported as values. This data attribute defines the behaviour when recurring payment dates falls on a weekend or bank holiday. The payment is then executed either the \"preceding\" or \"following\" working day. ASPSP might reject the request due to the communicated value, if rules in Online-Banking are not supporting this execution rule. | ||||||||||||||||
| FrequencyCode | The following codes from the \"EventFrequency7Code\" of ISO 20022 are supported: - \"Daily\" - \"Weekly\" - \"EveryTwoWeeks\" - \"Monthly\" - \"EveryTwoMonths\" - \"Quarterly\" - \"SemiAnnual\" - \"Annual\" - \"MonthlyVariable\" | ||||||||||||||||
| MessageCode2XX | Message codes for HTTP Error codes 2XX. | ||||||||||||||||
| MessageCode405AIS | Message codes defined for AIS for HTTP Error code 405 (METHOD NOT ALLOWED). | ||||||||||||||||
| MessageCode405PIIS | Message codes defined for PIIS for HTTP Error code 405 (METHOD NOT ALLOWED). | ||||||||||||||||
| MessageCode405PIS | Message codes defined for payment cancelations PIS for HTTP Error code 405 (METHOD NOT ALLOWED). | ||||||||||||||||
| MonthOfExecution | Month of execution as string. This string consists of up two characters. Leading zeroes are not allowed. 12 is ultimo. | ||||||||||||||||
| PaymentInitationRequestResponse201 | Body of the response for a successful payment initiation request. | ||||||||||||||||
| PaymentInitiationCancelResponse202 | Body of the response for a successful cancel payment request. | ||||||||||||||||
| PaymentInitiationStatusResponse200Json | Body of the response for a successful payment initiation status request in case of an JSON based endpoint. | ||||||||||||||||
| PurposeCode | ExternalPurpose1Code from ISO 20022. Values from ISO 20022 External Code List ExternalCodeSets_1Q2018 June 2018. | ||||||||||||||||
| ReadAccountBalanceResponse200 | Body of the response for a successful read balance for an account request. | ||||||||||||||||
| RemittanceInformationStructured | Structured remittance information. | ||||||||||||||||
| ReportExchangeRate | Exchange Rate. | ||||||||||||||||
| ScaStatus | This data element is containing information about the status of the SCA method applied. The following codes are defined for this data type. * 'received': An authorisation or cancellation-authorisation resource has been created successfully. * 'psuIdentified': The PSU related to the authorisation or cancellation-authorisation resource has been identified. * 'psuAuthenticated': The PSU related to the authorisation or cancellation-authorisation resource has been identified and authenticated e.g. by a password or by an access token. * 'scaMethodSelected': The PSU/TPP has selected the related SCA routine. If the SCA method is chosen implicitly since only one SCA method is available, then this is the first status to be reported instead of 'received'. * 'unconfirmed': SCA is technically successfully finalised by the PSU, but the authorisation resource needs a confirmation command by the TPP yet. * 'started': The addressed SCA routine has been started. * 'finalised': The SCA routine has been finalised successfully (including a potential confirmation command). This is a final status of the authorisation resource. * 'failed': The SCA routine failed. This is a final status of the authorisation resource. * 'exempted': SCA was exempted for the related transaction, the related authorisation is successful. This is a final status of the authorisation resource. | ||||||||||||||||
| ScaStatusResponse | Body of the JSON response with SCA Status. | ||||||||||||||||
| StandingOrderDetails | Details of underlying standing orders. | ||||||||||||||||
| StartScaprocessResponse | Body of the JSON response for a Start SCA authorisation request. | ||||||||||||||||
| TppMessage2XX | |||||||||||||||||
| TppMessage405AIS | |||||||||||||||||
| TppMessage405PIIS | |||||||||||||||||
| TppMessage405PIS | |||||||||||||||||
| TppMessageCategory | Category of the TPP message category. | ||||||||||||||||
| TransactionDetails | Transaction details. | ||||||||||||||||
| TransactionStatus | The transaction status is filled with codes of the ISO 20022 data table: - 'ACCC': 'AcceptedSettlementCompleted' - Settlement on the creditor's account has been completed. - 'ACCP': 'AcceptedCustomerProfile' - Preceding check of technical validation was successful. Customer profile check was also successful. - 'ACSC': 'AcceptedSettlementCompleted' - Settlement on the debtor�s account has been completed. **Usage:** this can be used by the first agent to report to the debtor that the transaction has been completed. **Warning:** this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement. - 'ACSP': 'AcceptedSettlementInProcess' - All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution. - 'ACTC': 'AcceptedTechnicalValidation' - Authentication and syntactical and semantical validation are successful. - 'ACWC': 'AcceptedWithChange' - Instruction is accepted but a change will be made, such as date or remittance not sent. - 'ACWP': 'AcceptedWithoutPosting' - Payment instruction included in the credit transfer is accepted without being posted to the creditor customer�s account. - 'RCVD': 'Received' - Payment initiation has been received by the receiving agent. - 'PDNG': 'Pending' - Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed. - 'RJCT': 'Rejected' - Payment initiation or individual transaction included in the payment initiation has been rejected. - 'CANC': 'Cancelled' Payment initiation has been cancelled before execution Remark: This codeis accepted as new code by ISO20022. - 'ACFC': 'AcceptedFundsChecked' - Preceding check of technical validation and customer profile was successful and an automatic funds check was positive . Remark: This code is accepted as new code by ISO20022. - 'PATC': 'PartiallyAcceptedTechnical' Correct The payment initiation needs multiple authentications, where some but not yet all have been performed. Syntactical and semantical validations are successful. Remark: This code is accepted as new code by ISO20022. - 'PART': 'PartiallyAccepted' - A number of transactions have been accepted, whereas another number of transactions have not yet achieved 'accepted' status. Remark: This code may be used only in case of bulk payments. It is only used in a situation where all mandated authorisations have been applied, but some payments have been rejected. | ||||||||||||||||
| TransactionsResponse200Json | Body of the JSON response for a successful read transaction list request. This account report contains transactions resulting from the query parameters. |