STET PSD2 API Documentation Author: Robache Hervé Date: 2018-04-10 Version: 1.3.0 (English) Table of content 1. INTRODUCTION ...................................................................................................... 9 1.1. Context .............................................................................................................................................. 9 1.2. Mission .............................................................................................................................................. 9 1.3. Licence ............................................................................................................................................ 10 2. BUSINESS MODEL ............................................................................................... 11 2.1. Actors and Roles ............................................................................................................................ 11 2.1.1. Payment Service User (PSU) ...................................................................................................... 11 2.1.2. API actors ..................................................................................................................................... 12 2.1.3. Registration Authorities (RA) ........................................................................................................ 13 2.2. Use cases ........................................................................................................................................ 14 2.2.1. PAO uses cases (NON-API) ........................................................................................................ 14 2.2.2. Registration use cases (NON-API) .............................................................................................. 15 2.2.3. AISP use cases ............................................................................................................................ 16 2.2.4. PIISP use cases ........................................................................................................................... 17 2.2.5. PISP uses cases .......................................................................................................................... 18 3. PREREQUISITES AND TECHNICAL DETAILS ................................................... 20 3.1. Actors registration ......................................................................................................................... 20 3.2. Cross-Authentication and Data Encryption ................................................................................ 20 3.3. Strong Customer Authentication (SCA) ...................................................................................... 20 3.3.1. Redirect Approach ........................................................................................................................ 21 3.3.2. Decoupled approach .................................................................................................................... 21 3.3.3. Embedded approach .................................................................................................................... 21 3.4. Authorization .................................................................................................................................. 22 3.4.1. Levels of authorization ................................................................................................................. 22 3.4.2. AISP and PIISP authorization levels ............................................................................................ 22 3.4.3. PISP authorization levels ............................................................................................................. 30 3.5. Applicative authentication ............................................................................................................ 32 3.6. Fraud detection oriented information .......................................................................................... 32 3.7. Specific HTTP messages to be used ........................................................................................... 33 3.8. STET PSD2 API technical summary............................................................................................. 34 4. FUNCTIONAL MODEL .......................................................................................... 35 4.1. Retrieval of the PSU accounts (AISP) .......................................................................................... 35 4.1.1. Prerequisites ................................................................................................................................. 35 4.1.2. Business flow ................................................................................................................................ 35 4.1.3. Request content ........................................................................................................................... 35 4.1.4. Response content (if no error) ..................................................................................................... 36 4.2. Retrieval of an account balances report (AISP) ......................................................................... 39 4.2.1. Prerequisites ................................................................................................................................. 39 4.2.2. Business flow ................................................................................................................................ 39 4.2.3. Request content ........................................................................................................................... 39 4.2.4. Response content (if no error) ..................................................................................................... 39 4.3. Retrieval of an account transaction set (AISP) ........................................................................... 41 4.3.1. Prerequisites ................................................................................................................................. 41 4.3.2. Business flow ................................................................................................................................ 41 4.3.3. Request content ........................................................................................................................... 41 4.3.4. Response content (if no error) ..................................................................................................... 42 4.4. Request for payment coverage check (PIISP) ............................................................................ 44 4.4.1. Prerequisites ................................................................................................................................. 44 4.4.2. Business flow ................................................................................................................................ 44 4.4.3. Request content ........................................................................................................................... 44 4.4.4. Response content (no error) ........................................................................................................ 45 4.5. Payment initiation on behalf of a merchant (PISP) .................................................................... 47 4.5.1. Prerequisites ................................................................................................................................. 47 4.5.2. Business flow ................................................................................................................................ 47 4.5.3. Request content ........................................................................................................................... 50 4.5.4. Response content (if no error) ..................................................................................................... 60 4.6. Retrieval of a Payment Request and its status (PISP) ............................................................... 61 4.6.1. Prerequisites ................................................................................................................................. 61 4.6.2. Business flow ................................................................................................................................ 61 4.6.3. Request content ........................................................................................................................... 61 4.6.4. Response content (if no error) ..................................................................................................... 61 4.6.5. Business reason codes in case of rejection ................................................................................. 71 4.7. Confirmation of a Payment Request (PISP) ................................................................................ 72 4.7.1. Prerequisites ................................................................................................................................. 72 4.7.2. Business flow ................................................................................................................................ 72 4.7.3. Request content ........................................................................................................................... 72 4.7.4. Response content (if no error) ..................................................................................................... 72 4.8. Transfer Initiation on behalf of a Payment Account Owner (PISP) .......................................... 73 4.8.1. Prerequisites ................................................................................................................................. 73 4.8.2. Business flow ................................................................................................................................ 73 4.8.3. Request content ........................................................................................................................... 76 4.8.4. Response content (if no error) ..................................................................................................... 80 4.9. Retrieval of a Transfer Request and its status (PISP)................................................................ 81 4.9.1. Prerequisites ................................................................................................................................. 81 4.9.2. Business flow ................................................................................................................................ 81 4.9.3. Request content ........................................................................................................................... 81 4.9.4. Response content (if no error) ..................................................................................................... 81 4.9.5. Business reason codes in case of rejection ................................................................................. 86 4.10. Confirmation of a Transfer Request (PISP) ................................................................................. 87 4.10.1. Prerequisites ............................................................................................................................ 87 4.10.2. Business flow ........................................................................................................................... 87 4.10.3. Request content ....................................................................................................................... 87 4.10.4. Response content (if no error) ................................................................................................. 87 5. AISP USE CASES ................................................................................................. 88 5.1. PSU Context Retrieval ................................................................................................................... 88 5.1.1. Request ........................................................................................................................................ 88 5.1.2. Response ..................................................................................................................................... 89 5.2. Account Balances Retrieval .......................................................................................................... 90 5.2.1. Request ........................................................................................................................................ 90 5.2.2. Response ..................................................................................................................................... 91 5.3. Account Transactions Retrieval ................................................................................................... 93 5.3.1. Request ........................................................................................................................................ 93 5.3.2. Response ..................................................................................................................................... 94 6. PIISP USE CASES ................................................................................................. 96 6.1. Account Amount Coverage Check ............................................................................................... 96 6.1.1. Request ........................................................................................................................................ 96 6.1.2. Response ..................................................................................................................................... 97 7. PISP USE CASES (REDIRECT APPROACH) ...................................................... 98 7.1. Payment Request ........................................................................................................................... 98 7.1.1. Request ........................................................................................................................................ 98 7.1.2. Response ................................................................................................................................... 102 7.2. Payment Request Retrieval ......................................................................................................... 102 7.2.1. Request ...................................................................................................................................... 102 7.2.2. Response ................................................................................................................................... 103 7.3. Payment Request Confirmation ................................................................................................. 107 7.3.1. Request ...................................................................................................................................... 107 7.3.2. Response ................................................................................................................................... 108 7.4. Transfer Request .......................................................................................................................... 111 7.4.1. Request ...................................................................................................................................... 111 7.4.2. Response ................................................................................................................................... 113 7.5. Transfer Request Retrieval ......................................................................................................... 114 7.5.1. Request ...................................................................................................................................... 114 7.5.2. Response ................................................................................................................................... 115 7.6. Transfer Request Confirmation .................................................................................................. 117 7.6.1. Request ...................................................................................................................................... 117 7.6.2. Response ................................................................................................................................... 118 8. PISP USE CASES (DECOUPLED APPROACH) ................................................ 120 8.1. Payment Request ......................................................................................................................... 120 8.1.1. Request ...................................................................................................................................... 120 8.1.2. Response ................................................................................................................................... 123 8.2. Payment Request Retrieval ......................................................................................................... 124 8.2.1. Request ...................................................................................................................................... 124 8.2.2. Response ................................................................................................................................... 125 8.3. Payment Request Confirmation ................................................................................................. 128 8.3.1. Request ...................................................................................................................................... 128 8.3.2. Response ................................................................................................................................... 129 8.4. Transfer Request .......................................................................................................................... 132 8.4.1. Request ...................................................................................................................................... 132 8.4.2. Response ................................................................................................................................... 134 8.5. Transfer Request Retrieval ......................................................................................................... 135 8.5.1. Request ...................................................................................................................................... 135 8.5.2. Response ................................................................................................................................... 136 8.6. Transfer Request Confirmation .................................................................................................. 138 8.6.1. Request ...................................................................................................................................... 138 8.6.2. Response ................................................................................................................................... 139 9. PISP USE CASES (EMBEDDED APPROACH) .................................................. 141 9.1. Payment Request ......................................................................................................................... 141 9.1.1. Request ...................................................................................................................................... 141 9.1.2. Response ................................................................................................................................... 144 9.2. Payment Request Retrieval ......................................................................................................... 145 9.2.1. Request ...................................................................................................................................... 145 9.2.2. Response ................................................................................................................................... 146 9.3. Payment Request Confirmation ................................................................................................. 149 9.3.1. Request ...................................................................................................................................... 149 9.3.2. Response ................................................................................................................................... 150 9.4. Transfer Request .......................................................................................................................... 153 9.4.1. Request ...................................................................................................................................... 153 9.4.2. Response ................................................................................................................................... 155 9.5. Transfer Request Retrieval ......................................................................................................... 156 9.5.1. Request ...................................................................................................................................... 156 9.5.2. Response ................................................................................................................................... 157 9.6. Transfer Request Confirmation .................................................................................................. 159 9.6.1. Request ...................................................................................................................................... 159 9.6.2. Response ................................................................................................................................... 160 1. Introduction 1.1. Context The revised Payment Service Directive (PSD2) points out some new roles providing services to a Payment Service User (PSU): - Third Party Providers (TPP) which can be subdivided into three categories o Account Information Service Providers (AISP) o Payment Initiation Service Providers (PISP) o Payment Issuer Instrument Service Providers (PIISP) - Account Servicing Payment Service Providers (ASPSP). Each Member Country has to transpose the PSD2, within its own national law. The PSD2 is completed by a set of documents provided by the European Banking Authority (EBA). Among these documents, the Regulatory Technical Standards (RTS) for Strong Customer Authentication (SCA) details some requirements, for instance on security principles: traceability, strong customer authentication… 1.2. Mission STET has been mandated by its shareholders in order to design and provide an open API (Aka STET PSD2 API) that would specify the different interactions between TPPs and ASPSPs for carrying out the different use cases of PSD2. This API could be extended to other (non-PSD2) use cases in the future but this extension is not part of the mandate. As the RTS for SCA are now finalised, this version of the API and its documentation takes into account the new constraints and rules that have been introduced. This version also includes - Items that have been identified and studied in common with the BERLIN GROUP, in a strategy of convergence of the different European API initiatives. - Evolvements linked to the change requests that have been received after public release of STET PSD2 API V1.2. The STET PSD2 API does not cover: - Interactions between PSUs and TPP - Interactions between PSUs and ASPSP - Registration information management The technical characteristics of this API are provided within a SWAGGER 2.0 file. The present document purpose is to provide extra-information on this API and to give some interaction samples. 1.3. Licence This specification is published under the following licence “Creative Commons – Attribution 3.0 France (CC BY 3.0 FR)” This work has been coordinated by STET with the following contributors: - BNP Paribas - Le Groupe BPCE - Le Groupe Crédit Agricole - La Banque Fédérative du Crédit Mutuel – CIC - La Banque Postale - La Société Générale - La Caisse des Dépôts et Consignations - Le Crédit Mutuel - ARKEA - HSBC France - L’OCBF