Joint Initiative on a PSD2 Compliant XS2A Interface NextGenPSD2 XS2A Framework Implementation Guidelines Version 1.3.8 30 October 2020 License Notice This Specification has been prepared by the Participants of the Joint Initiative pan-European PSD2-Interface Interoperability* (hereafter: Joint Initiative). This Specification is published by the Berlin Group under the following license conditions: "Creative Commons Attribution-NoDerivatives 4.0 International Public License" This means that the Specification can be copied and redistributed in any medium or format for any purpose, even commercially, and when shared, that appropriate credit must be given, a link to the license must be provided, and indicated if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. In addition, if you remix, transform, or build upon the Specification, you may not distribute the modified Specification. Implementation of certain elements of this Specification may require licenses under third party intellectual property rights, including without limitation, patent rights. The Berlin Group or any contributor to the Specification is not, and shall not be held responsible in any manner for identifying or failing to identify any or all such third party intellectual property rights. The Specification, including technical data, may be subject to export or import regulations in different countries. Any user of the Specification agrees to comply strictly with all such regulations and acknowledges that it has the responsibility to obtain licenses to export, re-export, or import (parts of) the Specification. * The ‘Joint Initiative pan-European PSD2-Interface Interoperability’ brings together participants of the Berlin Group with additional European banks (ASPSPs), banking associations, payment associations, payment schemes and interbank processors. NextGenPSD2 XS2A Framework – Implementation Guidelines Contents Contents 1 Introduction ............................................................................................... 1 1.1 Background ..................................................................................... 1 1.2 XS2A Interface Specification ........................................................... 2 1.3 Structure of the Document ............................................................... 3 1.4 Document History ............................................................................ 4 2 Character Sets and Notations ................................................................... 7 2.1 Character Set .................................................................................. 7 2.2 Notation ........................................................................................... 8 2.2.1 Notation for Requests .......................................................... 8 2.2.2 Notation for Responses ........................................................ 9 3 Transport Layer ...................................................................................... 10 4 Application Layer: Guiding Principles ...................................................... 11 4.1 Location of Message Parameters .................................................. 11 4.2 Signing Messages at Application Layer ......................................... 12 4.3 Optional Usage of OAuth2 for PSU Authentication or Authorisation ................................................................................. 13 4.4 XS2A Interface API Structure ........................................................ 15 4.5 Multicurrency Accounts ................................................................. 16 4.6 Authorisation Endpoints ................................................................. 17 4.7 Payment Cancellation Endpoints ................................................... 19 4.8 Requirements on PSU Context Data ............................................. 20 4.9 Requirements on TPP Identification .............................................. 22 4.10 Requirements on TPP URIs .......................................................... 23 4.11 API Access Methods ..................................................................... 24 4.11.1 Payments Endpoints .......................................................... 24 4.11.2 Accounts Endpoint ............................................................. 28 4.11.3 Card-accounts Endpoint ..................................................... 31 4.11.4 Consents Endpoint ............................................................. 32 4.11.5 Signing-baskets Endpoint ................................................... 34 4.11.6 Funds-Confirmations Endpoint ........................................... 36 4.12 HTTP Response Codes ................................................................. 36 Published by the Berlin Group under Creative Commons Attribution-NoDerivatives 4.0 International Public License Page i (ref. License Notice for full license conditions) NextGenPSD2 XS2A Framework – Implementation Guidelines Contents 4.13 Additional Error Information ........................................................... 38 4.13.1 NextGenPSD2 Specific Solution ........................................ 38 4.13.2 Standardised Additional Error Information .......................... 40 4.14 Status Information ......................................................................... 41 4.14.1 Status Information for PIS .................................................. 41 4.14.2 Status Information for the AIS within the Establish Consent Process .............................................................................. 44 4.15 API Steering Process by Hyperlinks .............................................. 45 4.16 Data Extensions ............................................................................ 49 5 Payment Initiation Service ...................................................................... 51 5.1 Payment Initiation Flows ................................................................ 51 5.1.1 Redirect SCA Approach: Explicit Start of the Authorisation Process .............................................................................. 51 5.1.2 Redirect SCA Approach: Explicit Start of the Authorisation Process with Confirmation Code ........................................ 52 5.1.3 Redirect SCA Approach: Implicit Start of the Authorisation Process .............................................................................. 53 5.1.4 Redirect SCA Approach: Implicit Start of the Authorisation Process with Confirmation Code ........................................ 55 5.1.5 OAuth2 SCA Approach: Implicit Start of the Authorisation Process .............................................................................. 55 5.1.6 OAuth2 SCA Approach: Implicit Start of the Authorisation Process with Confirmation Code ........................................ 56 5.1.7 Decoupled SCA Approach: Implicit Start of the Authorisation Process .............................................................................. 58 5.1.8 Embedded SCA Approach without SCA method (e.g. Creditor in Exemption List) ................................................. 58 5.1.9 Embedded SCA Approach with only one SCA method available ............................................................................. 60 5.1.10 Embedded SCA Approach with Selection of an SCA method ............................................................................... 60 5.1.11 Combination of Flows due to mixed SCA Approaches ....... 61 5.1.12 Multilevel SCA Approach: Example for the Redirect SCA Approach ........................................................................... 62 5.2 Data Overview Payment Initiation Service ..................................... 65 5.3 Payment Initiation Request ............................................................ 71 Published by the Berlin Group under Creative Commons Attribution-NoDerivatives 4.0 International Public License Page ii (ref. License Notice for full license conditions) NextGenPSD2 XS2A Framework – Implementation Guidelines Contents 5.3.1 Payment Initiation with JSON encoding of the Payment Instruction .......................................................................... 71 5.3.2 Payment Initiation with pain.001 XML message as Payment Instruction .......................................................................... 85 5.3.3 Payment Initiation for Bulk Payments ................................. 87 5.3.4 Initiation for Standing Orders for Recurring/Periodic Payments ........................................................................... 89 5.4 Get Transaction Status Request .................................................... 95 5.5 Get Payment Request ................................................................... 99 5.6 Payment Cancellation Request.................................................... 101 5.7 Get Cancellation Authorisation Sub-Resources Request ............. 107 5.8 Multilevel SCA for Payments ....................................................... 109 5.9 Payment Initiation Specifics for Multi-currency Accounts ............. 111 6 Account Information Service ................................................................. 112 6.1 Account Information Service Flows .............................................. 116 6.1.1 Account Information Consent Flow ................................... 116 6.1.2 Read Account Data Flow.................................................