Creditor Implementation Guidelines Emandates – Business to Business

Creditor Implementation Guidelines eMandates – Business to Business

Document version 1.02

CONFIDENTIAL

December 2015

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Terms and conditions

Terms and conditions for provision of the eMandates Creditor Integration Guide:

1 Currence Services BV (also referred to as ‘Currence’) provides these eMandates Creditor Implementation Guidelines to Creditor Banks that distribute it to (potential) Creditors and Payment Service Providers to enable them to implement eMandates.

2 Currence reserves the right to deny access to the eMandates Creditor Implementation Guidelines to (potential) Creditors and Service Providers on reasonable grounds, in consultation with the Creditor Bank with which the Creditor/Service Provider has a contract.

3 These Implementation Guidelines are explicitly and exclusively provided for the purpose mentioned above, and no other use is permitted. No rights can be derived from the information provided in this document or the accompanying notes. Currence is in no way liable for the consequences of later changes to the eMandates Standards or the eMandates Creditor Implementation Guidelines. If banks or other interested parties take decisions and/or make investments on the basis of the information that they obtain via the eMandates Creditor Implementation Guidelines, Currence accepts no liability for this in any way.

4 These implementation Guidelines are based on the information in the eMandates Standards documents. In the event of any discrepancy between the eMandates Creditor Implementation Guidelines and the eMandates Standards documents, the text in the eMandates Standards documents prevails.

For any questions concerning this document or requests for further information, please contact your Bank or Payment Service Provider.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Contents

Terms and conditions ...... 2

Contents ...... 3

Tables ...... 8

Figures ...... 10

1 General Introduction ...... 11

1.1 Target audience ...... 11

1.2 Document structure ...... 11

1.3 Other references ...... 12

1.4 Notational conventions ...... 12

1.5 Definitions of online banking ...... 13

1.6 Revisions ...... 13

1.7 Changes from previous version ...... 13

2 eMandates Overview ...... 15

2.1 What is eMandates? ...... 15

2.2 What is eMandates Mobile? ...... 15

2.3 Design principles ...... 16

2.3.1 Technical principles ...... 16

2.3.2 Functional principles ...... 16

2.4 The four-corner model ...... 17

2.4.1 The relations between these roles ...... 18

2.5 Terminology ...... 19

3 eMandates protocol ...... 21

3.1 General ...... 21

3.1.1 Specific requirement eMandates Mobile: Redirect to Issuer can be diverted to mobile app or mobile web page of Issuer ...... 23

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

4 Functions of the solution ...... 24

4.1.1 Issuing a new eMandate ...... 24

4.1.2 Amending an existing eMandate ...... 24

4.1.3 Cancelling an existing eMandate ...... 24

4.2 Multiple signing ...... 25

4.3 Creditor Registration for eMandates ...... 26

4.3.1 Creditor preconditions ...... 26

4.3.2 Creditor registration ...... 26

4.4 ValidationReference ...... 27

4.5 Dispute management ...... 27

5 eMandates Message format ...... 28

5.1 General ...... 28

5.2 HTTP ...... 28

5.3 XML header ...... 28

5.4 Character set ...... 29

5.5 XML Namespace declaration ...... 29

5.6 Message attributes ...... 30

5.7 Conventions for empty fields ...... 30

5.8 Message validation ...... 30

6 eMandates Data dictionary ...... 31

6.1 eMandate IDs ...... 31

6.2 General data elements ...... 31

6.3 eMandates ISO pain message data elements ...... 33

6.3.1 Frequency ...... 35

7 eMandates Directory protocol ...... 36

7.1 General ...... 36

7.2 DirectoryRequest ...... 36

7.3 DirectoryResponse ...... 37

7.4 Presentation of the Debtor Bank selection list ...... 38

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

8 eMandates Transaction protocol ...... 40

8.1 General ...... 40

8.2 TransactionRequest ...... 40

8.2.1 Container content ...... 41

8.2.2 Content of container element for new eMandates ...... 41

8.2.3 Content of container element for eMandate amendments ...... 44

8.2.4 Content of container element for eMandate cancellations ...... 48

8.3 TransactionResponse ...... 51

8.4 Errors when executing Transaction Protocol ...... 52

8.5 Redirect to the online banking environment (issuerAuthenticationURL) ...... 52

8.5.1 Specific requirement eMandates Mobile: Redirect to Debtor Bank (no in-app browser) ...... 52

8.6 Redirect to the Creditor environment (merchantReturnURL) ...... 53

8.6.1 Requirements for eMandates Mobile: redirect to the Creditor environment...... 54

8.7 Errors during execution of the redirect to the Debtor Bank, approving the eMandate and/or the redirect to the Creditor environment ...... 54

8.8 Four different scenario’s for completion of eMandates Mobile transaction ...... 55

8.8.1 Debtor is redirected from the Creditor’s (mobile) web page to the Debtor Bank’s (mobile) web page...... 55

8.8.2 Debtor is redirected from the Creditor’s (mobile) web page to the Debtor Bank’s mobile banking app ...... 56

8.8.3 Debtor is redirected from the Creditor’s mobile app to the Debtor Bank’s (mobile) web page ...... 57

8.8.4 Debtor is redirected from the Creditor’s mobile app to the Debtor Bank’s mobile banking app ...... 57

8.9 Performance and time-out of transaction message ...... 58

8.10 Specific requirement eMandates Mobile: Print or e-mail confirmation message ...... 59

9 eMandates Status protocol ...... 60

9.1 General ...... 60

9.2 StatusRequest ...... 60

9.3 StatusResponse ...... 60

9.3.1 Content of container element for new eMandates, amendments or cancellations .. 61

9.4 Errors during execution of Status Protocol ...... 66

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

9.5 Collection duty ...... 66

9.6 Performance and time-out of status messages ...... 67

10 Error handling ...... 69

10.1 General ...... 69

10.2 ErrorResponse ...... 69

10.3 Non-availability ...... 71

11 Security and certificates ...... 72

11.1 General principles of certificates ...... 72

11.2 Signing eMandates messages ...... 72

11.2.1 Signing of the ISO pain.012 acceptance report ...... 73

11.3 Authentication of eMandates messages ...... 74

11.4 Creating a key pair ...... 74

11.4.1 Buying a certificate from a Certificate Authority ...... 75

12 Presentation ...... 76

12.1 General ...... 76

12.2 Incassomachtigen via uw bank-button ...... 76

12.3 Transaction flow ...... 76

12.4 Redirect to Debtor Bank ...... 76

12.5 Frames ...... 77

12.6 New Window ...... 77

12.6.1 Specific Requirements eMandates Mobile: New window or app ...... 77

12.7 Debtor Bank list ...... 77

12.8 ‘Incassomachtigen via uw bank’ banners and logo's ...... 77

12.9 Explaining eMandates to Debtors ...... 77

12.10 Creditor front-end ...... 78

12.11 Debtor Bank front-end ...... 79

13 eMandates and direct debit ...... 82

13.1 Initiating direct debits ...... 82

13.2 Relation with the Overstapservice ...... 83

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

APPENDIX A: Container content overview ...... 84

APPENDIX B: Error codes ...... 85

Categories ...... 85

Error codes ...... 85

APPENDIX C: Message examples ...... 88

A. DirectoryReq ...... 88

A’. DirectoryRes ...... 88

B. AcquirerTrxReq for new eMandate ...... 89

B. AcquirerTrxReq for eMandate amendment ...... 91

B. AcquirerTrxReq for eMandate Cancellation ...... 93

B’. AcquirerTrxRes ...... 94

F. AcquirerStatusReq ...... 95

F’. AcquirerStatusRes for new eMandate ...... 96

X’. AcquirerErrorRes ...... 99

X’. AcquirerErrorRes (with namespace prefixes, but without container element) ...... 100

APPENDIX D: iDx XML Schema ...... 102

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Tables

Table 1: References ...... 12

Table 2: Mapping of eMandates elements to xml elements ...... 19

Table 3: Message names and descriptions ...... 22

Table 4: eMandate IDs ...... 31

Table 5: Data elements in iDx messages ...... 32

Table 6: Used data formats in the data catalogue ...... 33

Table 7: Used character codes in the data catalogue ...... 33

Table 8: eMandates data elements ...... 35

Table 9: eMandate.FrequencyPeriod codes ...... 35

Table 10: Fields of the DirectoryRequest ...... 37

Table 11: Fields of the DirectoryResponse ...... 37

Table 12: Fields of the TransactionRequest ...... 41

Table 13: Pain.009 message (new eMandate) ...... 44

Table 14: Pain.010 message (amendment) ...... 48

Table 15: Pain.011 message (cancellation) ...... 51

Table 16: Fields of the TransactionResponse ...... 52

Table 17: Different scenario’s for the completion of an eMandates mobile transaction ...... 55

Table 18: Scenario: Redirect from Creditor (mobile) web page to the Debtor Banks (mobile) web page ...... 56

Table 19: Scenario: Redirect form Creditor (mobile) web page to the Debtor Banks mobile banking app ...... 57

Table 20: Scenario: Redirect from the Creditors mobile app to the Debtor Banks (mobile) web page ... 57

Table 21: Scenario: Redirect from the Creditors mobile app to the Debtor Banks mobile banking app . 58

Table 22: Performance requirements (for the 95th percentile*) ...... 58

Table 23: Fields of the StatusRequest ...... 60

Table 24: Fields of the StatusResponse ...... 61

Table 25: Pain.012 message (acceptance report) ...... 66

Table 26: Performance requirements (for the 95th percentile*) ...... 67

Table 27: Fields of the ErrorResponse ...... 69

Table 28: Pain.012 error response acceptance report ...... 71

Table 29: Mapping of pain.012 elements to pain.008 direct debit initiation message ...... 82

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Table 29: Container content for new eMandates ...... 84

Table 30: Container content for eMandate amendments ...... 84

Table 31: Container content for eMandate cancellations ...... 84

Table 32: Error code categories ...... 85

Table 33: Error codes ...... 86

Table 34: errorDetail ...... 86

Table 35: consumerMessage ...... 87

Table 36: Reject reason codes ...... 87

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Figures

Figure 1: Four-corner model ...... 19

Figure 2: Representation of the steps in an eMandates transaction ...... 21

Figure 3: Representation of the steps in an eMandates Mobile transaction ...... 23

Figure 4: Example of (open) dropdown list box showing the Debtor Bank list ...... 38

Figure 5: Example of one-off eMandate approval website or mobile app screen ...... 80

Figure 6: Example of one-off eMandate confirmation website or mobile app screen ...... 81

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

1 General Introduction

1.1 Target audience

This document provides a detailed description of the Dutch Banks’ eMandates B2B solution. It is intended for those requiring detailed information about this solution. These B2B Creditor Implementation Guidelines have been created as a delta document, using the Core Creditor Implementations Guidelines as the basis. Additions appear in blue, deletions appear in red, with strikethrough - like this. As a result of this, changes between this version of the Creditor Implementation Guidelines and the previous version are marked as change only in the related version of the Core Creditor Implementation Guidelines (see table 1.6 for related Core versions). The changes are also summarized in paragraph 1.7.

eMandate Creditors are organisations (Creditors) that want to use eMandates and have signed an eMandate contract with a bank. Creditors are required to have a direct debit contract.

This document is intended for Creditors that want to connect to the eMandate platform of their Creditor Bank. It provides a description of all messages that are exchanged between the Creditor and the Routing Service of his Creditor Bank. The messages that are exchanged between the Routing Service of the Creditor Bank and the Validation Service of the Debtor Bank are not of importance to the Creditor, and therefore will not be discussed in this document unless they have specific relevance.

This document is not bank specific, which means that only generic specifications are mentioned in this guide. Information concerning bank specific connections that are not standard and assistance that is provided by banks to connect to eMandates are not part of this guide. Please contact your Creditor bank for any information or support on a bank specific connection or implementation.

To further support Creditors, software libraries have been developed in .NET, PHP and Java. Please contact your bank about this for more information.

1.2 Document structure

• Chapter 2: Introduction to eMandates and an overview of all parties involved in eMandates. • Chapter 3: The various messages that are exchanged within the scope of an eMandates transaction and the overall structure of the exchanged messages • Chapter 4: Functions of the solution • Chapter 5: Message format • Chapter 6: Data dictionary • Chapter 7: Directory protocol: providing a list of participating Debtor Banks • Chapter 8: Transaction protocol: starting an eMandate transaction • Chapter 9: Status protocol: retrieving the status of the transaction and the eMandate • Chapter 10: Error handling • Chapter 11: Security and certificates • Chapter 12: Presentation of eMandates on the Creditor website • Chapter 13: Relation between eMandates and direct debit collection

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

• Appendices

1.3 Other references

Title Version Issued by

1.3.1.1.1.1 UNIFI (20022) ISO 1.3.1.1.1.2 SDD Implementation Guidelines 1.3.1.1.1.3 7.0 EPC

1.3.1.1.1.4 SDD Rulebook 1.3.1.1.1.5 7.0 EPC XML message for SEPA Direct Debit Initiation Implementation Guidelines for 7.0 BVN The Netherlands Available at http://www.betaalvereniging.nl/wp-uploads/2013/01/XML- Message-for-SDD-Version-7.0-February-2013.pdf Payments Mandate Urgent Maintenance and message XSD’s October 2014 ISO Available at http://www.iso20022.org/full_catalogue.page under ‘pain - payments initiation’

External Code Sets spreadsheet 13 june 2014 ISO The Base16, Base32, and Base64 Data Encodings July 2003 Network Working http://www.ietf.org/rfc/rfc3548.txt Group 1.3.1.1.1.6 Base64 Content-Transfer-Encoding November 1996 Network Working 1.3.1.1.1.7 http://tools.ietf.org/html/rfc2045iDxsection-6.8 Group Multilingual European Subset 2 (MES-2) 15 April 2000 CEN Unicode.org http://www.utf8-chartable.de/unicode-utf8-table.pl Open Web Application Security Project (OWASP) n.a. OWASP http://www.owasp.org XML Signature Syntax and Processing (Second Edition), W3C Second edition, World Wide Web Recommendation 10 June 2008 10 June 2008 Consortium http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/ (W3C) GUIDELINES ON ALGORITHMS USAGE AND KEY MANAGEMENT Version 1.1 EPC (EPC342-08) approved 23 February 2009 ITU-T RECOMMENDATION X.690 Information technology - ASN.1 encoding (07/2002) ITU-T rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER) http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf LC858 Use of encryption algorithms and key management systems for 7 January 2011 NVB banking applications and systems TLS Protocol version 1.0 http://www.ietf.org/rfc/rfc2246.txt 1.0, January IETF 1999

TLS Protocol version 1.1 http://www.ietf.org/rfc/rfc4346.txt 1.1, April 2006 IETF TLS Protocol version 1.2 http://www.ietf.org/rfc/rfc5246.txt 1.2, August 2008 IETF

Table 1: References

1.4 Notational conventions

Messages and redirects are printed like this, and data elements are printed like this.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

1.5 Definitions of online banking

In this document there are many references to Creditor websites and the Debtor’s online banking environment. To facilitate mobile use of the eMandates solution, these references must be supplemented with ‘….. or mobile website / mobile app’ and ‘….. or mobile banking website / mobile banking app’ where appropriate.

For every instance where internet or online related-terminology is used, please interpret this as including the mobile channel. Where mobile use of the eMandates solution leads to specific requirements for the eMandates solution, this is indicated separately in the text.

1.6 Revisions

Version Related Core Description Release date CIG version

1.0 1.02 Initial version 26 March 2015

1.01 1.03 • Updated the canonicalization method used for the 4 May 2015 digest to exclusive canonicalization • Clarified the requirements for saving the mandate • Clarified the format requirements of eMandateID • Clarified the use of the Creditor Address • Clarified that the DateTime in the pain.012 message is the moment of signing the eMandate.

1.02 1.04 • Added chapter 13, with information about the 31 december relation with direct debit initiation 2015 • Clarified the requirements for saving the mandate • The requirements for timestamps placed by the Creditor have been clarified • Added XML-tags to the XML element tables • Clarified that the electronic signature over the mandate needs to be verified by the Creditor • Clarified the formatting requirements for the maximum amount field

• Creditor is not allowed to use the field ‘Maximum Amount’ in pain.010 message (Change compared to previous version B2B CIG)

1.7 Changes from previous version

This paragraph summarizes the changes of previous versions of the Creditor Implementation Guidelines Core.

Changes since version 1.02 of Core CIG

1. The canonicalization method that is used for the calculation of the digest has been changed from inclusive canonicalization to exclusive canonicalization. This impacts both the calculation itself and the part of the XML message where the calculation process is described.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

2. The requirements for archiving the original eMandate (the ISO pain.012 message which includes the electronic signature and certificate information) have been clarified. The ISO pain.012 message can be archived after extracting it from the XML envelope, using exclusive canonicalization. Alternatively, Creditors may choose to simply archive the entire StatusResponse message. 3. The formatting requirements for the eMandateID have been clarified. Creditors must beware that eMandateID’s must be restricted to the SEPA Direct Debit character set, which is stricter than the MES-2 character set. 4. The use of the Creditor Address has been clarified. The Creditor must register his address using two address-lines, generally using the first line for information on street, number, postbus, add-ons and using the second line for postcode and city. 5. Clarified that the DateTime in the pain.012 message is the moment of signing the eMandate. The element eMandate.DateTimestamp has been placed in the pain.012 table to make this clear.

Changes since version 1.03 of Core CIG

1. Chapter 13 has been added, containing information about the relation between the product eMandates and the direct debit collection, as well as the relation with the Dutch Overstapservice. 2. Clarified that saving the message containing the mandate needs to be done without making any changes to the message, as this will invalidate the electronic signature. 3. The requirements for timestamps placed by the Creditor have been clarified. In timestamps, the Creditor may include zero to three decimals after the seconds, and is no longer obligated to always include three decimals. 4. The XML-tags have been added to the tables containing the XML elements in chapter 8 and 9. 5. If the StatusResponse message contains the status “success”, there is a pain.012 message present, containing the electronic signature over the mandate. This signature has to be validated, to ensure the validity of the mandate. 6. The requirements for the maximum amount field have been clarified; it should be an amount between 0.01 and 999999999.99 with no decimals, or two decimals separated by a dot.

Changes since version 1.01 of B2B CIG

1. For eMandate amendments, the Creditor is no longer allowed to propose a new value for maximum amount. The Creditor is not allowed to use the maximum amount field in the pain.010 message. When amending an eMandate, after the redirect to the Debtor Bank internet banking website, the Debtor Bank will show the current value of maximum amount to the Debtor. This value is taken from the bank’s mandate registration (direct debit collections are checked against this registration). If the Debtor wishes to do so, he can adjust the value of the maximum amount. The (adjusted) value for maximum amount will be part of the pain.012 mandate message which is retrieved and archived by the Creditor.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

2 eMandates Overview

2.1 What is eMandates?

eMandates was developed by the Dutch banking community in order to facilitate online processes for mandates. eMandates enables direct and secure real-time1 online issuing and amendment of eMandates by Debtors to Creditors.

The main characteristics of eMandates are:

• Real-time eMandates through accepted and trusted online banking that is already familiar to Debtors; • Real-time eMandate approval by the Debtor and real-time confirmation to the Creditor by the Creditor Bank. The Creditor receives the eMandate that has been signed by the Debtor Bank on behalf of the Debtor; • Officially recognised as valid mandates by the participating Debtor Banks; • For Business to Business Direct Debit collections, the Debtor Bank only processes the collection when it matches a pre-registered mandate. eMandate registrations are automatically created, amended or cancelled by the Debtor Bank as part of the eMandate process, which means the Creditor can almost immediately proceed with the direct debit collection. This can vastly reduce the mandate-to-collection lead-times compared to the current mandate-registration processes as well as the number of failed direct debits due to mandate registration entry-errors. • Offers the flexibility to receive mandates for many different purposes (e.g. magazine subscriptions, telephone/e-mail orders); • Supports multiple signing in the Debtor Bank domain in case this is required for specific Debtors.

In practice, nearly every Debtor that uses online banking with one of the Debtor Banks that support eMandates can use the eMandates service

2.2 What is eMandates Mobile?

Participating banks will also implement a mobile version of eMandates. This will be based on mobile banking services like mobile web sites or mobile apps. This is called eMandates Mobile.

The main characteristics of eMandates Mobile are:

• There are no changes in the messages sent between Debtor bank and Creditor bank and no changes in messages sent between Creditor and bank;

• Creditors and Debtors do not need to take extra steps for a mobile eMandate transaction. The redirecting of the Debtor to the mobile banking channel is done automatically by the Debtor’s bank. For banks that support eMandates in their mobile banking app, the Debtor

1 Real-time signing and issuing does not always apply when multiple signing is required for the specific Debtor.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

can choose whether to approve the eMandate using the mobile web browser or the mobile banking app.

• eMandates Mobile is based on the same mechanisms to ensure trust, security and convenience as used in a desktop environment. In cases mobile technology does not support the same technical security measures as a desktop computer the bank will implement alternative measures to compensate.

Every Debtor that uses online banking with one of the Debtor Banks that supports eMandates can also use eMandates on a mobile device (although it may be necessary for a Debtor to download and register a mobile application). Those Debtor Banks that do not (yet) have an eMandates Mobile implementation or that have an implementation that doesn’t reach the majority of Debtors will still be able to process transactions through their regular (desktop focussed) eMandate pages on a mobile device’s browser.

2.3 Design principles

2.3.1 Technical principles

eMandates is based on the following principles: - Use of existing online banking and mobile banking products. - Communication over the Internet. - Use of open-market standards, where possible. - Merchant implementation involving the least possible complexity. - Taking measures to improve reliability, where possible. - Use of the Multilingual European Subset 2 (MES-2) standard character set. - Debtor's selection of Debtor Bank (Issuer) based on Debtor Bank name. - Safety and reliability (stability).

2.3.2 Functional principles - The eMandates Implementation Guidelines described in this document are intended for the B2B SEPA Direct Debit. - The eMandates solution facilitates the issuing of new eMandates, amendment of existing eMandates and cancellation of existing eMandates. Creditors must offer both all three functionalities to their Debtors (issuing new eMandates, and amending existing eMandates and cancelling existing eMandates). - The only reasons for amending an eMandate is when the Debtor wishes to change his bank account number for Direct Debits, within the same bank or to a different bank, or to change the Maximum Amount of the direct debit. The amendment process is initiated on the Creditor’s website. After the redirect to the Debtor Bank internetbanking website, the Debtor can choose his preferred accuntnumber and/or adjust the value of the maximum amount. - The eMandates solution uses the ISO XML 20022 standard eMandates messages to convey eMandate- specific data. The following messages are used: pain.009.01.04 (new, also referred to as ‘issuing’), pain.010.01.04 (amendment), pain.011.01.04 (cancellation) and

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

pain.012.01.04 (acceptance report). The information inside the ISO XML 20022 acceptance report (pain.012) constitutes the actual eMandate. The ISO messages are placed inside the container element in the messages. The XSD’s for these ISO messages can be found at http://www.iso20022.org/full_catalogue.page, see pain – Payments initiation. - The eMandates solution is intended for both recurring and one-off mandates. - In the eMandates process, the eMandate information is shown to the Debtor for approval in the Debtor Bank domain. - Each eMandate has an eMandateID that uniquely identifies it within a given CreditorID. Each Creditor is responsible for issuing his own unique eMandateID’s. Creditors must beware that eMandateID’s must be restricted to the SEPA Direct Debit character set. - The Creditor is responsible for archiving2 the original eMandate (the ISO pain.012 message which includes the electronic signature and certificate information), together with any following amendment or cancellation information received from the Debtor (at a later stage). The ISO pain.012 message can be archived after extracting it from the XML envelope, using exclusive canonicalisation. Alternatively, Creditors may choose to simply archive the entire StatusResponse message. Archiving the message needs to be done without making any changes to the message, as this will invalidate the electronic signature. Even minor changes such as adjusting the message-formatting will render the signature invalid. - The element eMandate.Frequency has been included in the eMandate solution for future use. The Creditor MAY NOT include frequency information in any of the Mandate messages. - eMandates are used by the Debtor Bank to automatically update the Debtor’s mandate registration: o An approved new eMandate is added to the registration list o eMandate amendments (change of account number or maximum amount) are processed in the registration o Cancelled eMandates are removed from the registration list

2.4 The four-corner model

The eMandates system is based on the ‘four-corner’ model. Figure 1: Four-corner model shows the roles in this model, along with their mutual primary relationships in the context of eMandates. The roles are those of Debtor, Creditor, Creditor Bank, Debtor Bank, Routing Service and Validation Service:

- The Creditor is the company collecting Direct Debits. This can be the actual Creditor, or a Collecting Payment Service Provider collecting Direct Debits acting on behalf of another Creditor.

2 It is expected that in the future more strict requirements will appear for electronic archiving, especially related to protecting document integrity for a longer period of time. In the short future the regulation on electronic identification will address the topic of eArchiving and will create a legal framework underlying timestamping services. These guidelines will then be evaluated and used in these implementation guidelines.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

- The Debtor is a consumer or company holding a bank account at the Debtor Bank, from which B2B Direct Debits can be collected. - The Creditor Bank is the bank where the Creditor has his contract for eMandate services. - The Debtor Bank is the Bank where the Debtor hold’s the bank account that he wishes to use for eMandates. This bank account MUST be used by the Creditor for the collection of direct debits. - Routing Service: a technical role (routing of messages) that is fulfilled by a Creditor Bank or a third party endorsed by the Creditor Bank. Wherever the term ‘Routing Service’ is mentioned in this document, please read ‘Routing Service of the Creditor Bank’. - Validation Service: a technical role that is fulfilled by the Debtor Bank or by a third party endorsed by the Debtor bank. Wherever the term ‘Validation Service’ is mentioned, please read ‘Validation Service of the Debtor Bank’.

2.4.1 The relations between these roles Both contractual and technical relations exist between the roles. These are described below.

Contractual relations:

- Creditor – Creditor Bank: The Creditor has an eMandates contract with a Creditor Bank. The Creditor must also have a Direct Debit contract at (the same or another) Creditor Bank. - Debtor – Debtor Bank: The Debtor has a bank account with the Debtor Bank. The identity related to this account is used for approving eMandates and subsequently, but outside the scope of the eMandates solution, settling the Direct Debits. - Debtor - Creditor: The Debtor ‘mandates’ the Creditor by means of an eMandate. This allows the Creditor under SDD rules to withdraw funds from the Debtor’s bank account at a later stage using a Direct Debit (execution of the Direct Debit is outside the scope of the eMandates solution).

Technical relations:

- Creditor – Routing Service: The Creditor has a technical relation with the Routing Service. The Routing service offers the Creditor the possibility of sending eMandate proposals to a Validation Service. They exchange messages to this end. - Routing Service – Validation Service: The Routing Service and Validation Service have an eMandates solution relationship. They exchange messages in this context. - Debtor – Validation Service: The Validation Service offers the Debtor the possibility of issuing eMandates to Creditors, by approving eMandate proposals using an online banking product.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Figure 1: Four-corner model

2.5 Terminology

eMandates has been based partly on existing XML messages (of the so-called iDx standards) that are based on the iDEAL messages. To convey specific eMandates information, pain ISO messages are placed inside a container element in these existing iDx XML messages. Because the existing xml messages have some different terminology/element names, a mapping applies between the xml element names and the functional element names that are used in eMandates. Table 2 shows the mapping of functional eMandates element names to the terms used in the XML messages.

2.5.1.1.1.1 Nr. Functional eMandates element xml element names names 1. Creditor.CreditorBankID Acquirer.acquirerID 2. Debtor.DebtorBankID Issuer.issuerID 3. eMandate.ContractID Merchant.merchantID

4. eMandate.ContractSubID Merchant.subID 5. eMandate.DateTimestamp Transaction.statusDateTimestamp 6. eMandate.TransactionID Transaction.transactionID

Table 2: Mapping of eMandates elements to xml elements

As stated in the introduction, this document will only cover the messages that are exchanged between the Creditor and the Routing Service. However, the messages that are exchanged between the Routing Service (of the Creditor Bank) and the Validation Service (of the Debtor Bank) will be briefly explained if necessary to provide a good understanding of the entire transaction.

Besides the four parties mentioned that are always involved in a transaction, additional parties can be involved. The Creditor can, for example, use a Service Provider to establish the technical

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

connection with his Routing Service. When a Service Provider collects funds and then distributes these funds to the ultimate Creditor, this is called a “Collecting PSP” (CPSP).

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

3 eMandates protocol

3.1 General

A typical eMandates transaction comprises (request-/response-) XML messaging and browser redirects, which handle the initiation, and processing of the transaction in a particular sequence, with all parties involved being informed on the status of the transaction. The steps in this transaction are shown in Figure 2.

There are three request/response message pairs (also referred to as protocols) defined within an eMandates transaction:

1. The Directory protocol: used to retrieve the most recent Debtor Bank list from the Routing Service. 2. The Transaction protocol: encompasses the eMandates-transaction process from beginning to end. 3. The Status protocol: used to request the status of a transaction from the Validation Service (via the Routing Service).

Figure 2: Representation of the steps in an eMandates transaction

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

A specific name (letter) has been assigned to identify each message. The following table applies:

Message Message description A DirectoryRequest A’ DirectoryResponse B AcquirerTransactionRequest

B’ AcquirerTransactionResponse F AcquirerStatusRequest F’ AcquirerStatusResponse

X’ AcquirerErrorResponse Redirects: D Debtor redirect to Debtor Bank E Debtor redirect to Creditor

Table 3: Message names and descriptions

By using the Directory protocol, the Creditor sends a DirectoryRequest to the Routing Service. This is a request in XML format to obtain the list of participating Debtor Banks from the Routing Service. The Routing Service will provide this list to the Creditor by sending back the DirectoryResponse. The Creditor will show the list of banks, which were sent in the DirectoryResponse to the Debtor. The Debtor will choose his bank from this list at the beginning of the eMandate process. The Directory protocol is explained in more detail in chapter 7.

By using the Transaction protocol the Creditor sends a TransactionRequest to the Routing Service, containing the ID of the Debtor Bank chosen by the Debtor, mandate information and other transaction details. This message also contains the MerchantReturnURL. This URL is used by the Validation Service to redirect the Debtor back to the Creditor’s website when he has completed the eMandate transaction in his Debtor Bank domain. After the Routing Service has received the message from the Creditor, he adds some pre-registered Creditor details to the message and sends a message to the Validation Service of the Debtor Bank that was selected by the Debtor. In return, the Validation Service responds with a message that contains the issuerAuthenticationURL (and other data). The Routing Service passes this issuerAuthenticationURL together with a unique TransactionID back to the Creditor via the TransactionResponse message, which is the response to the TransactionRequest. The Creditor now redirects the Debtor to the issuerAuthenticationURL, which refers to the page of the online banking portal. This takes the Debtor to his internet-banking environment where he can continue the eMandate transaction. The Debtor Bank adds Debtor information (such as IBAN and Debtor Name) to the eMandate proposal. The Debtor approves the eMandate and receives a confirmation from the Issuer. The Debtor is then redirected back to the website of the Creditor via the merchantReturnURL. The entire Transaction protocol and the 2 redirects are further described in chapter 8.

Finally the Creditor initiates the Status protocol by sending a StatusRequest message to the Routing Service. The Routing Service will request the transaction status, if necessary, from the appropriate Issuer and returns the status to the Creditor. If all steps in the transaction were

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

successful this status message contains the eMandate and the signature for the Creditor. Chapter 9 contains more detailed information on the Status protocol.

Instead of a regular response to the messages mentioned above, it is also possible that an ErrorResponse is returned. This can be the case if the request contains an error, or if an error occurs during the processing of the request. The ErrorResponse messages are discussed in chapter 10.

Chapter 5 describes the general format of eMandates messages. The three protocols are discussed in more detail in chapters 7, 8 and 9.

3.1.1 Specific requirement eMandates Mobile: Redirect to Issuer can be diverted to mobile app or mobile web page of Issuer The Mobile transaction flow is almost identical to the transaction flow in a regular eMandates transaction. The only difference is the redirect to a ‘landing page’ (using the issuerAuthenticationURL) where the Debtor, using a mobile device, can choose to be redirected to the Issuer’s (mobile) web page or to the Issuer’s mobile banking app (if available).

Figure 3: Representation of the steps in an eMandates Mobile transaction

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

4 Functions of the solution

This part describes several specific functionalities of the eMandates-solution. All eMandate processes are initiated on the Creditor website by the Debtor. eMandate processes are never initiated from the Debtor Bank domain.

The eMandate (Issuing, amendment or cancellation) proposal is created by the Creditor. This eMandate proposal is not yet complete: it is completed by the Routing Service (with Creditor information) and Validation Service (with Debtor information) respectively.

4.1.1 Issuing a new eMandate Issuing a new eMandate is supported through the use of the ISO pain.009 message type. The Creditor enters the mandate information in the message and this information set is then completed with Creditor information by the Routing Service, and with Debtor information by the Validation Service until the complete eMandate proposal is approved by the Debtor. Upon approval, the Debtor Bank adds an electronic signature to the eMandate on behalf of the Debtor. The signed eMandate is then retrieved by the Creditor and must be archived.

4.1.2 Amending an existing eMandate Just like with new eMandates, the process is initiated by the Debtor on the Creditor website. The only relevant change for an eMandate is when the Debtor wishes to change his account number (within the same bank or to a different bank) or to change the maximum amount per Direct Debit. The process is almost identical to the process of issuing a new eMandate, but for amendments of existing eMandates, the ISO pain.010 message is used.

The ISO pain.010 message contains the same information as a pain.009 message, but it also included three referrals to the original (existing) eMandate: the original eMandateID, the Debtor IBAN and the Debtor Bank ID.

Amendments to eMandates may also be communicated by the Debtor to the Creditor through use of other channels than eMandates, but this is not recommended.

The Creditor is free to accept amendments to existing (paper) mandates through the use of the eMandates solution.

4.1.3 Cancelling an existing eMandate Just like with new eMandates and amendments, cancellations are initiated by the Debtor on the Creditor website. For B2B the cancellation process includes validation at the Debtor Bank (whereas for Core, it is a matter between Creditor and Debtor). For cancellation of existing eMandates, the ISO pain.011 message is used.

The cancellation message contains referrals to the original eMandate: eMandateID, Debtor IBAN and Debtor Bank ID. Cancellations, however, can only be done at the same bank where the eMandate has previously been issued/approved (that is, the bank where direct debits are being collected). The Creditor must make clear to the Debtor he must choose the same bank where the

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

eMandate has been issued. If the Debtor chooses a different bank, the transaction will be rejected by that bank.

The Creditor is free to accept cancellations to existing (paper) mandates through the use of the eMandates solution.

4.2 Multiple signing

For B2B eMandates, multiple signing may be required in the Debtor Bank domain when the Debtor is using a business account to approve the eMandate. This can’t always be done in a single session, which means the Debtor Bank has to store the eMandate proposal and make it accessible for further approval. Furthermore, multiple signing implies the following:

- Only the Debtor Bank can determine when multiple signing is required. - Only the initiator is allowed to be redirected to the Creditor website. This prevents other signers from taking over the initiator’s session at the Creditor website. - The initiator might not return to the Creditor website and hence wouldn’t receive online confirmation of the eMandate. The Creditors are therefore recommended to use other means of (offline) communication to inform the initiator the eMandate has (not) successfully been received.

When multiple signing is required, the transaction may need more time to enable other signers to approve the eMandate. However, it is not known beforehand (by the Creditor) whether multiple or single signing is required. Both situations need to be catered for. Therefore, the following principles apply to the use of expiration period3:

• By default, the Creditor should not set the expiration period to the transaction. In that case, the standard expiration period is 30 minutes. • When the first Debtor logs into the Debtor Bank domain within 30 minutes, the Debtor Bank is able to determine whether multiple signing is required. When multiple signing is indeed required, the Debtor Bank automatically sets the expiration period to 7 days. In all other cases, the expiration period remains 30 minutes. • The Creditor may always assume the expiration time to be 30 minutes and can perform a status request after 30 minutes (assuming the redirect to the Creditor has not occurred so there has not been a trigger to request the status yet) • When multiple signing is required, the transaction gets the status ‘Pending’. The Creditor may then request the status of the transaction once every day. After 7 days, the status of the transaction becomes final (Expired) if not all required signers have approved the eMandate transaction.

3 Expiration period is the amount of time the Debtor has to approve the eMandate in his Debtor Bank domain before it expires.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

• If a Creditor has an urgent need to ensure a stricter expiration period, he may choose to set the expiration period to his preferred timeframe, with a maximum of 7 days and a minimum of 1 minute. The Debtor Bank then always adheres to this expiration period (even when multiple signing is required). A possible consequence of setting the expiration period is that Debtors for which multiple signing is required may not have enough time for all signers to complete the transaction. We therefore strongly recommend Creditors to not set a specific expiration time.

4.3 Creditor Registration for eMandates

4.3.1 Creditor preconditions Each Creditor that wants to use the eMandates solution must have an eMandates-contract. As a pre-condition for getting this contract, a Creditor must be in possession of a Direct Debit contract at a (same or different) Creditor Bank. Only after establishing that a Creditor has a Direct Debit contract will the Creditor Bank enter into an eMandates-contract with this Creditor.

A Creditor that acts as a Collecting Payment Service Provider can collect Direct Debits for other companies. In this case, the eMandates must also be in the name and CreditorID of this CPSP (because the eMandate must be issued to the company that is collecting the Direct Debits). To make sure the Debtor recognises the eMandate, the name of the company being serviced (the ultimate Creditor) must also be mentioned on the eMandate. This is done using the element Creditor.TradeName. In the Debtor Bank domain, for approval by the Debtor this would be phrased as the eMandate being issued to ‘Creditor.Name regarding Creditor.TradeName’.

Likewise, a Creditor may have a company structure using different company labels (names) and addresses. As with the example of the Collecting Payment Service Provider, the labels can be shown on the eMandate as a tradename. In case of more than one company address, the correct address is also selected by the Routing Service for approval of the eMandate.

The Creditor registration process at the Creditor Bank facilitates selecting the right Creditor information for the eMandate by the Routing Service.

4.3.2 Creditor registration When registering for eMandates, the Creditor Bank issues an eMandate.ContractID to the Creditor. The Creditor also gets an eMandate.ContractSubID if this is required to distinguish between Creditor tradenames and/or addresses. The Creditor must register his address using two address-lines, generally using the first line for information on street, number, postbus, add- ons and using the second line for postcode and city. The exact details of the registration (process) are determined by your Creditor Bank and/or the Routing Service acting on its behalf.

In the eMandate process, the eMandate.ContractID and eMandate.ContractSubID are sent to the Routing Service by the Creditor in the eMandates request message. The Routing Service then adds specific Creditor information to this proposal based on the contractID (and when relevant also on the SubID). The Routing Service selects the right Creditor.Name, Creditor.CreditorID, Creditor.TradeName, Creditor.AddressLine1 and

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Creditor.AddressLine2 to add to the eMandates proposal. The Creditor is not allowed to fill out any of these elements.

4.4 ValidationReference

When the eMandate is approved by the Debtor in his Debtor Bank domain, the Validation Service generates a reference number (the ValidationService.ValidationReference). This reference is sent to the Creditor as part of the eMandate. This reference must be added to the Direct Debit collection information from the Creditor to his Creditor Bank. This reference is used by the Debtor Bank to retrieve eMandates validation information in case of a Debtor dispute.

4.5 Dispute management

In case of a dispute, the Debtor Bank has the role to check the integrity and authenticity of the eMandate. Therefore, in case of a dispute (MOI):

- The Creditor must supply either the ISO pain.012 message that represents the actual eMandate (in exclusively canonicalized form), or the entire XML file that was received in the StatusReponse (message F’). The Creditor must also supply any additional amendment information in case any changes were made outside the eMandates protocol. An example of such information is the message that you receive from your bank if one of your customers has transferred to a new bank using the Dutch Overstapservice. - The Creditor sends this information to his Creditor bank by email. The Creditor Bank forwards this information to the Debtor Bank. - The Debtor Bank uses the certificate information to verify the electronic signature. Thereby determining authenticity and integrity of the eMandate.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

5 eMandates Message format

5.1 General

This chapter contains a description of the general message structure for the Directory protocol, the Transaction protocol and the Status protocol. The subsequent sections will describe the specific fields within the XML messages for each protocol in more detail.

Each message described in this section is an XML message conforming to the XML Schema in APPENDIX D.

A list of the ID’s and fields used and the format can be found in the data dictionary in chapter 6.

The following conventions are used to indicate whether a message element is mandatory: − Yes The element must occur exactly once. − No The element may be left out or may occur exactly once. − Yes (1..∞) The element must occur one or more (unlimited) times.

5.2 HTTP

The following HTTP header must be used for all messages:

Data element Mandatory Explanation

content-type Yes Defines how the remainder of the content is to be interpreted. Contains the value: text/xml; charset=”utf-8”.

All messages must comply with the HTTP 1.1 standard, as defined in RFC 2616 of W3C.

For more information: http://www.w3.org/Protocols/rfc2616/rfc2616.html

Each XML request message must be sent as the body of a HTTP POST message.

Each XML response message must be sent as the body of a HTTP 200 OK message.

5.3 XML header

The following XML header must be used for all messages:

Example:

2001-12-17T09:30:47.571Z 1234123456 0

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

VW+VjenRyZVFCNfBTeoxDflQ4yfR8KYFvwPVinVPqBs= IELLwKSGFMk64US23YrpZ8//hJ8DeJEtYht5knlxJvBOr8dcI+aJTBq+YtyzP9ClcK62Obs5aynHBE/GPHZShu Mw+8WHq4fCMInOwKURgwjDOz8UYaIMqG0Ojiz8dFYGn+dH2lL0QVss4jmIIAD8MCijb27oqij6PclXw9Y9veI= 7D665C81ABBE1A7D0E525BFC171F04D276F07BF2

5.4 Character set

In all eMandates messages the Unicode character set must be used. Only the MES-2 subset must be supported.

Encoding must be used as indicated in the HTTP and XML headers UTF-8 (Unicode Transformation Format).

The use of characters that are not part of the Unicode character set will not lead to a refusal of a batch or post, but the character may be changed to a space, question mark or asterisk in transit.

The Byte Order Mark (BOM) must not be used. The UTF-8 representation of the BOM is the byte sequence 0xEF,0xBB,0xBF.

5.5 XML Namespace declaration

The namespace for all messages described in this document is as follows:

http://www.betaalvereniging.nl/iDx/messages/Merchant-Acquirer/1.0.0

All message instances must declare this namespace. Namespace declaration can be done in any way allowed by the XML standards (default namespace declaration or namespace

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

qualification/prefixes). All parties must be able to receive and process messages that use either of the two namespace declaration methods.

5.6 Message attributes

All XML messages must contain attributes in the root element, as shown in the table below.

Attribute Mandatory Explanation

version Yes Value must be: 1.0.0

productID Yes Value refers to the product for which the eMandates protocol is used. Must be NL:BVN:eMandatesB2B:1.0

Beware: These attributes are not specified in each message separately.

5.7 Conventions for empty fields

In eMandates an XML tag for an optional or conditional field is either:

− Present (in which case, the tag must be filled with a valid value).

− Not present at all.

− In general, XML tags without content are not allowed and will result in an error message.

o An exception to this rule are several tags that are mandatory in the ISO pain messages, even though they are empty.

5.8 Message validation

All messages must be validated against the eMandates XML Schema. The schema also references the XML Digital Signature Schema that must be used to validate the Signature element. The XML Digital Signature Schema is available from W3C at the following URL: http://www.w3.org/2000/09/xmldsig#.

The eMandate messages in the container element must be validated against the pain message’s XML schema.

Attention: There are eMandate elements in the pain messages for which we use stricter requirements when it comes to being mandatory and formatting than the ISO XSD’s. These requirements can be found in the data dictionary and in the tables specifying how the ISO messages are used (e.g. in Table 13).

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

6 eMandates Data dictionary

This chapter describes the data-elements and ID’s that are used in the eMandates solution.

6.1 eMandate IDs

The eMandates solution relies on the identifiers described in Table 4.

6.1.1.1.1.16.1.1.1.1.2 Nr. Element 6.1.1.1.1.3 Description 6.1.2 6.1.2.1.1.1Messages Formatting rules

1. Creditor.CreditorBankID Creditor Bank identifier number A’, B’, F’ 4 digit-number

2. Debtor.DebtorBankID BIC of the Debtor Bank 6.1.2.1.1.2B BIC (ISO 9362) 3. eMandate.ContractID eMandates Contract registration A,B,F 10 digit-number: Unique number of the Creditor. four-digit This ID uniquely identifies the Creditor.CreditorBan Creditor to the Creditor Bank in the kID, combined with a context of the contract they have unique combination of six for the eMandate service. numbers (issued by Creditor Bank)

4. eMandate.ContractSubID eMandate contract registration A,B,F A number from 0 to and number Sub of the Creditor including 999999 in which The subID that uniquely defines each value is related to a the name and address of the separate instance Creditor to be used for the registered with the Creditor eMandate Bank. The default value is ‘0’.

Table 4: eMandate IDs

6.2 General data elements

The table below contains all XML data elements that appear in messages relevant to the Creditor, together with information about the format and permitted values.

Data element Attribute Messages Format Values, explanation

Root element version All AN..8 1.0.0 Root element productID All AN..35 NL:BVN:eMandatesB2B:1.0

Data element Sub-element Messages Format Values, explanation createDateTimestamp All DT ISO-8601

Directory directoryDateTimestamp A' DT ISO-8601

Directory countryNames A' AN..128 Directory Issuer issuerID A' ANS..max 11 BIC, ISO9362

Directory Issuer issuerName A' AN..max 35

Error consumerMessage X’ AN..max 512

Error container X’ Any

Error errorCode X’ CL AN..6 See Appendix B

Error errorMessage X’ AN..max 128

Error errorDetail X’ AN..max 256

Error suggestedAction X’ AN..max 512 Issuer issuerAuthenticationURL B' AN..max 512

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Data element Attribute Messages Format Values, explanation

Merchant merchantReturnURL B AN..max 512 Determined by Creditor SignedInfo Exclusive All http://www.w3.org/2001/10/xml- CanonicalizationMethod exc-c14n#

SignedInfo Signaturemethod All http://www.w3.org/2001/04/xmldsi g-more#rsa-sha256

SignedInfo Reference URI All Must be empty

SignedInfo Reference Transforms All http://www.w3.org/2000/09/xmldsi g#enveloped-signature

SignedInfo Reference Transforms http://www.w3.org/2001/10/xml- exc-c14n#

SignedInfo Reference DigestMethod All http://www.w3.org/2001/04/xmlen c#sha256

SignedInfo Reference DigestValue All Base64

SignatureValue All Base64

KeyInfo KeyName All Fingerprint of certificate

Transaction container B, F’ Any To be filled with eMandate ISO pain message

Transaction entranceCode B ANS..max 40 Determined by Creditor Transaction expirationPeriod B RDT ISO 8601 Determined by Creditor

Transaction language B CL AN..2 ISO 639-1 Determined by Creditor

Transaction status F' CL AN..max 9 Open, Success, Failure, Cancelled, Expired Pending

Transaction statusDateTimestamp F' DT ISO 8601

Transaction transactionID B’, F, F’ PN..16 Determined by Routing Service Transaction transactionCreateDateTime B’ DT ISO 8601 stamp Determined by Routing Service

Table 5: Data elements in iDx messages

Notation Meaning AN Alphanumeric, free text

ANS Alphanumeric, strict (letters and numbers only) N Numerical PN Numerical (padded), the contents are extended to the maximum length by leading zeros

..max # Maximum number of positions for alphanumeric and numerical values ..# Fixed number of positions for alphanumeric and numerical values

CL Code list, enumeration DT Date time field in UTC (no daylight saving time):

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

YYYY-MM-DDThh:mm:ss.sssZ • In messages originating from the Routing Service Provider this value will always be filled with milliseconds. Creditors are allowed to use zero to three decimals after the seconds. • YYYY refers to the calendar year • hh must be in 24 hour-notation. 12 hour-notation is not allowed. RDT Relative date time field: PnYnMnDTnHnMnS DEC(#1,#2) Decimal, #1 total digits, #2 fraction digits: DEC(6,2) can be 1234.56 for example

Table 6: Used data formats in the data catalogue

Message Message description

A DirectoryRequest A’ DirectoryResponse B AcquirerTransactionRequest B’ AcquirerTransactionResponse F AcquirerStatusRequest F’ AcquirerStatusResponse X’ AcquirerErrorResponse Redirects: D Debtor redirect to Debtor Bank E Debtor redirect to Creditor

Table 7: Used character codes in the data catalogue

The characters C, G and Y are used in eMandates to refer to specific messages between the Validation Service and Routing Service. Because these are not relevant for the Creditor they are omitted from the table above.

6.3 eMandates ISO pain message data elements

Table 8 describes the data elements that are used in the eMandates ISO pain messages (009, 010, 011 and 012), together with their formatting rules. Attention: several of these elements are added to the eMandate by the Routing Service and Validation Service. These elements are therefore not part of the Transaction Request the Creditor sends to the Routing Service. Please see chapter 8.2 for an overview of the information that is part of the Transaction Request.

6.3.1.1.1.1Nr. eMandates name 6.3.1.1.1.2 Description 6.3.1.1.1.3 Formatting rules

1. Creditor.AddressLine1 The Creditor’s address – line 1 Max70Text • P.O. Box or street name + building + add-on (if any)

2. Creditor.AddressLine2 The Creditor’s address – line 2 Max70Text • Postcode • City 3. Creditor.Country Country of the postal address of the [A-Z]{2,2} Creditor

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

6.3.1.1.1.1Nr. eMandates name 6.3.1.1.1.2 Description 6.3.1.1.1.3 Formatting rules

4. Creditor.CreditorID Direct Debit ID of the Creditor As described in AT-02 (Identifier (NL: IncasantID) of the Creditor) in the EPC SDD Implementation Guidelines.

You will receive this from your Creditor Bank.

5. Creditor.Name Name of the Creditor Max70Text 6. Creditor.TradeName Name of the company (or daughter- Max70Text company, or label etc) for which the Creditor is processing eMandates. May only be used when meaningfully different from Creditor.Name 7. DateTime Date and time DT (see table 6)

8. Debtor.AccountName Account holder name of the account that Max70Text is used for the eMandate

9. Debtor.DebtorBankID BIC of the Debtor Bank 6.3.1.1.1.4 BIC (ISO 9362)

10. Debtor.IBAN Debtor’s bank account number IBAN (ISO 13616) 11. Debtor.SignerName Name of the person(s) signing the Max70Text eMandate. May end with ‘e.a.’ in case more than 70 characters are needed for multiple signer names. 12. eMandate.AmendmentReason The reasoncode for amending the Must be ‘MD16’ eMandate Means that amendment was requested by Debtor. 13. eMandate.DateTimestamp Date and time at which the eMandate DT (see table 6) has been approved by the Debtor in the Debtor Bank domain 14. eMandate.DebtorReference Reference ID that identifies the Debtor to Max35Text the Creditor. Issued by the Creditor 15. eMandate.eMandateID ID that uniquely identifies the Mandate Max35Text and is issued by the Creditor. Must be restricted to the SEPA character set 16. eMandate.FrequencyCount The number of Direct Debit collections Maximum 18 digit number. No during a specific fractional digits allowed. eMandate.FrequencyPeriod. Not allowed in current implementations 17. eMandate.FrequencyPeriod Period for the number See code list in Table 9. (eMandate.FrequencyCount) of Direct Debit collections 6.3.1.1.1.4.1 Not allowed in current implementations 18. eMandate.MaxAmount The maximum amount per Direct Debit. An amount of 0.01 or more and Not allowed in current 999999999.99 or less with no implementations fractional digits, or two fractional digits separated by a dot. ActiveCurrencyCode: EUR ’EUR’

19. eMandate.PurchaseID A purchaseID that acts as a reference Max35Text from eMandate to the purchase-order. Creditors are recommended to only use this element when it is meaningfully different from eMandate.Reason

20. eMandate.Reason Indicates the reason of the mandate Max70Text 21. eMandate.SequenceType Indicates type of eMandate: one-off ‘OOFF’ or ‘RCUR’ Direct Debit or recurring.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

6.3.1.1.1.1Nr. eMandates name 6.3.1.1.1.2 Description 6.3.1.1.1.3 Formatting rules

22. eMandate.TransactionID eMandateTransaction ID. The value for 16 digit number this ID is taken from the Transaction.transactionID 23. Message.NameID Refers to the type of validation request 3 values: that preceded the acceptance report - Issuing - Amendment - Cancellation

24. ValidationService.Valida The reference to the eMandate validation Max128Text tionReference log of the Validation Service. This reference is created by the Validation Service. This reference must be used by the Creditor to fill out the element ‘Electronic Signature’ in the Direct Debit Collection message (outside the scope of this document)

Table 8: eMandates data elements

6.3.1 Frequency Frequency is defined as the number of Direct Debit collections for a specific eMandateID per period. In the eMandate message, this is done by entering a specific number (eMandate.FrequencyCount) and a period (eMandate.FrequencyPeriod).

The following table shows the codes that can be used to indicate the period of the Direct Debit collections. NB: since Frequency is not allowed to be used in this implementation of eMandates, the permitted period-code list and definitions in Table 9 will be reviewed and adjusted after it is decided that Frequency will be used.

eMandate.FrequencyPeriod Definition Code ADHO Event takes place on request or as necessary DAIL Event takes place every day FRTN Event takes place every two weeks INDA Event takes place several times a day MIAN Event takes place every six months or two times a year MNTH Event takes place every month or once a month QURT Event takes place every three months or four times a year

WEEK Event takes place once a week YEAR Event takes place every year or once a year

Table 9: eMandate.FrequencyPeriod codes

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

7 eMandates Directory protocol

7.1 General

The Directory protocol allows a Creditor to retrieve an up to date list of participating Debtor Banks from his Routing Service, which can be presented to the Debtor. In case of changes in the list of Debtor Banks, the Directory protocol will supply the Creditor with the update of this list.

It is not allowed to perform the Directory protocol for each transaction. Since the list of Debtor Banks only changes occasionally, it is sufficient to execute the Directory protocol on a weekly basis and check if the list has changed based on the directoryDateTimestamp. If the Debtor Bank list has changed, the latest version has to be saved and used for any subsequent transaction. Routing Services will normally also inform all Creditors (e.g. by email) about changes in their Debtor Bank list. The Directory protocol should at least be executed once a week.

The Directory protocol (like the Transaction protocol and the Status protocol) consists of a HTTP POST request from the Creditor to the Routing Service, followed by a HTTP response. The DirectoryRequest is sent to the URL that is provided to the Creditor by the Routing Service for this specific purpose. This URL can be different from the one that is used for the TransactionRequest and the StatusRequest, but it can also be the same URL.

The Routing Service validates the authenticity of the message sent by the Creditor by verifying the signature in the message. To do this, the Routing Service needs the Creditor’s Certificate, including the public key. The way in which the public part of the Creditor certificate is communicated with the Routing Service varies per bank.

Please refer to Chapter 11 for more information on authentication and security.

7.2 DirectoryRequest

The DirectoryRequest consists of an XML message that is sent to the Routing Service with HTTP POST.

Table 10 shows all fields and formatting of the DirectoryRequest:

Field Name Description Format createDateTimestamp Date and time at which the directory request message was created. DT

merchantID eMandate.ContractID as supplied to the Creditor by the Creditor Bank. PN...10 If the eMandate.ContractID has less than 10 digits leading zeros are used to fill out the field.

subID eMandate.ContractSubID, as supplied to the Creditor by the Creditor N..max 6 Bank, if the Creditor has requested to use this. A Creditor can request permission from the Creditor Bank to use one or more subIDs. In this way the Creditor.Tradename and relevant Creditor.Address belonging to the SubID will also be shown on the eMandate, next to the Creditor.Name. (Creditor.Name, on behalf of Creditor.TradeName). Unless agreed otherwise with the Creditor Bank, the Creditor has to use 0 (zero) as subID by default (if no subIDs are used).

SignedInfo This element contains information about the signature as described in W3C * XMLdsig specifications See chapter 11 for more information

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

SignatureValue Contains the electronic signature as described in W3C XMLdsig * specifications. See chapter 11 for more information KeyInfo 7.2.1.1.1.1 Contains information (fingerprint) about the certificate that is used for * generating the digital signature, so the receiver can use the right public key for validating the signature as described in W3C XMLdsig specifications. 7.2.1.1.1.2 See chapter 11 for more information

Table 10: Fields of the DirectoryRequest

* SignedInfo, SignatureValue and KeyInfo are XML Signature data elements that are defined in the XML-Signature Syntax and Processing (Second Edition) W3C Recommendation 10 June 2008. The signature is described in more detail in Chapter 11. The XML Schema for XML Signatures is available from W3C at the following URL: http://www.w3.org/TR/2002/REC- xmldsig-core-20020212/xmldsig-core-schema.xsd.

APPENDIX C shows an example of a DirectoryRequest and all other messages that are described in this document.

7.3 DirectoryResponse

The Creditor will receive the DirectoryResponse as a reply to the DirectoryRequest. This XML message contains a list of Debtor Bank names with their corresponding Debtor BankID (BIC). Debtor Banks are grouped by country. The Debtor Banks in the Creditor’s country of choice may be presented at the top in the Debtor Bank selection list, the rest are sorted alphabetically by country, then by name. Table 11 shows all fields that appear in the DirectoryResponse message.

Name Description Format createDateTimestamp Date and time at which the response message was created. DT acquirerID Unique four-digit identifier of the Creditor Bank PN..4 (Creditor.CreditorBankID) within eMandates. directoryDateTimestamp The date and time on which the Directory was updated by the Routing DT Service.

countryNames Contains the countryNames in the official languages of the country, separated by a ‘/’ symbol (e.g. ‘België/Belgique’)4.

issuerID Debtor.DebtorBankID: Bank Identifier Code (BIC) of the Debtor ANS..max Bank 11 issuerName The name of the Debtor Bank (as this should be displayed to the Debtor AN..max in the Creditor’s Debtor Bank list). 35

SignedInfo See 7.2 and 11.2

SignatureValue See 7.2 and 11.2 KeyInfo See 7.2 and 11.2

Table 11: Fields of the DirectoryResponse

An example of the DirectoryResponse is shown in APPENDIX C.

4 Country names need only be displayed if there are Debtor Banks from more than one country on the Debtor Bank list. If all Debtor Banks in the list are from the same country, the country name can be omitted.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

7.4 Presentation of the Debtor Bank selection list

To ensure that the Debtor experience of an eMandates transaction is consistent and recognisable through all Creditor websites; all Creditors have to comply with certain presentation standards.

All Debtor Banks in the DirectoryResponse have to be shown in a “dropdown list box”. The first element in this list is “Kies uw bank…” (Eng. “Choose your bank…”), and is selected by default. Subsequently the name of the Creditor’s country of choice is shown (either the Creditor’s own country or the country the Debtor is (expected to be) from). The names of all Debtor Banks that belong to the Creditor’s country of choice are presented next in separate elements, in the same (alphabetical) order as they are presented in the DirectoryResponse. Following this the names of other available countries are presented alphabetically, within each country the banks from that country are sorted alphabetically, in the same order as presented in the DirectoryResponse. The Creditor should generate an error message whenever one of the elements “Kies uw bank…” and countryNames elements is selected by the Debtor.

It is recommended to configure the HTML “value” field of the items in the list box to be the Debtor BankID (BIC) of the corresponding Debtor Bank, because this value is necessary for subsequent messages. An example of the Debtor Bank selection list is shown in Figure 4.

Figure 4: Example of (open) dropdown list box showing the Debtor Bank list

Creditors are not permitted to remove Debtor Banks temporarily from the Debtor Bank selection list or to grey them out.

If a Creditor learns via the eMandates Notification System (Central Reporting tool for eMandates Validation Services and Routing Services to state system non-availability) or via error messages received from the Acquiring bank that a particular Validation Service is currently not available, the Creditor may display a message on its website informing Debtors that the particular bank is not

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

available. In other words, it is permissible to display a message conveying such information but it is not permissible to temporarily remove or grey out the Debtor Bank concerned from the Debtor Bank selection list.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

8 eMandates Transaction protocol

8.1 General

The Transaction protocol initiates the exchange of messages of the actual eMandates process. After the Debtor has chosen eMandates as a transaction method and has selected his bank, the Creditor sends a TransactionRequest to the Routing Service. Within the eMandates standards this message is referred to as the AcquirerTransactionRequest. The Routing Service replies to the TransactionRequest with a TransactionResponse. This TransactionResponse will also (among other fields) contain the issuerAuthenticationURL. This URL will redirect the browser of the Debtor to the Debtor Bank in order to let him authorise the transaction.

8.2 TransactionRequest

The XML message sent by the Creditor to the Routing Service to initiate the transaction contains the fields shown in Table 12. The eMandate information (ISO message) is put inside the container element in the Transaction Request. The definition of the ISO message for a new eMandate request (ISO pain.009.001.004) is shown in table 13. The definition of the ISO message for an eMandate amendment request (ISO pain.010.001.004) is shown in Table 14. The definition of the ISO message for an eMandate cancellation request (ISO pain.011.004) is shown in Table 15.

Name Description Format createDateTimestamp Date and time at which the TransactionRequest message was created. DT issuerID The ID (BIC) of the Debtor Bank selected by the Debtor, as stated in the ANS..max Debtor Bank list in the Directory response (Debtor.DebtorBankID). 11

merchantID eMandate.ContractID as supplied to the Creditor by the Creditor Bank. PN..10 If the eMandate.ContractID has less than 10 digits leading zeros are used to fill out the field.

merchantReturnURL Valid Creditor URL (not necessarily beginning with http:// or https://) which AN..max must redirect the Debtor from the Debtor Bank back to the Creditor website 512 after authorisation of the transaction by the Debtor. Example: https://www.webshop.nl/processtransaction

expirationPeriod Optional: The period of validity of the transaction request as stated by the RDT Creditor measured from the receipt by the Debtor Bank. The Debtor must approve the eMandate within this period. Otherwise the Debtor Bank sets the status of the transaction to ‘Expired’. Value period according to ISO 8601: PnYnMnDTnHnMnS. Minimum value: PT1M or PT60S (1 minute); maximum value: P7D, PT168H, PT10.080M (7 days). The Creditor is recommended to leave this field empty. language This field enables the Debtor Bank’s site to select the Debtor’s preferred CL AN..2 language (e.g. the language selected on the Creditor’s site), if the Debtor

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Bank's site supports this. Code list in accordance with ISO 639-1. (Dutch = ‘nl’, English = ‘en’) If a non-supported or non-existing language is entered the standard language of the Debtor Bank is used. It is recommended to use ‘nl’ by default since not all Debtor Banks support other languages.

entranceCode The Transaction.entranceCode is an 'authentication identifier' to facilitate ANS..max continuation of the session between Creditor and Debtor, even if the existing 40 session has been lost. It enables the Creditor to recognise the Debtor associated with a (completed) transaction. The Transaction.entranceCode is sent to the Creditor in the Redirect. The Transaction.entranceCode must have a minimum variation of 1 million and should comprise letters and/or figures (maximum 40 positions). The Transaction.entranceCode is created by the Creditor.

Container This container contains the ISO pain messages. This can be a pain.009 (new eMandate), pain010 (amendment) or pain 011 (cancellation) message. See paragraphs 8.2.2 and, 8.2.3 and 8.2.4 for details.

SignedInfo See 7.2 and 11.2 SignatureValue See 7.2 and 11.2

KeyInfo See 7.2 and 11.2

Table 12: Fields of the TransactionRequest

8.2.1 Container content As explained, the mandate ISO pain messages are put in the container element. The ISO message is a standardised message, so it contains elements that are not used in the eMandates solution. In the following tables, only mandatory and recommended optional elements for the eMandates solution are mentioned. The table’s columns contain the following information:

• Column 1 is the index. This index is specific for this document. • Column 2 gives the name of the message element as defined in the ISO 20022 XML standard. When an element contains sub-elements these are indented to the right and noted with a plus sign (+) per level. • Column 3 specifies whether the element is Mandatory or Optional

8.2.2 Content of container element for new eMandates The following table describes which elements the Creditor sends to the Routing Service in the TransactionRequest, for a new eMandate. Complex types are elements that don’t have an actual value themselves. They function as containers for sub-elements that hold the actual values.

Index ISO Message Element eMandates Requirement

1 + Message root Mandatory

2 + Group Header Mandatory. Complex type

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

3 ++ Message Identification Mandatory Max35Text Format: maxLength: 35, minLength: 1

4 ++ Creation Date Time Mandatory

DateTime

5 + Mandate Mandatory

6 ++ Mandate Identification Mandatory eMandate.eMandateID

7 ++ Mandate Request Identification Mandatory 8.2.2.1.1.1 Must be: NOTPROVIDED

8 ++ Type Mandatory, Complex type

9 +++ Service Level Mandatory, Complex type

10 ++++ Code Mandatory The identification code of the Scheme Usage Rule: Only ‘SEPA’ is allowed.

11 +++ Local Instrument Mandatory, Complex type

12 ++++ Code Mandatory Specifies the local instrument Usage Rule: Only ‘B2B’ is allowed to indicate a B2B direct debit.

13 ++ Occurrences Mandatory, Complex type

14 +++ Sequence Type Mandatory eMandate.SequenceType

15 +++ Frequency Optional Usage rule: Not allowed in current implementation

16 ++++ Type Not allowed

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

17 ++++ Period Mandatory (if Frequency is provided), Complex type

18 +++++ Type Mandatory (if Frequency is provided) eMandate.FrequencyPeriod

19 +++++ CountPerPeriod Mandatory (if Frequency is provided) eMandate.FrequencyCount

20 ++ Maximum Amount Optional element eMandate.MaxAmount Usage rule: Not allowed in current implementation

21 ++ Reason Optional, Complex type

22 +++ Code Not allowed

23 +++ Proprietary Mandatory (if Reason is provided) eMandate.Reason

24 ++ Creditor Mandatory Must be empty Usage rule: Intentionally not filled further by the Creditor, as the Creditor information will be added by the Routing Service

25 ++ Debtor Mandatory, Complex type Must be empty if eMandate.DebtorReference is not used

26 +++ Identification Optional , Complex type

27 ++++ Private Identification Optional, Complex type

28 +++++ Other Optional, Complex type

29 ++++++ ID Optional eMandate.DebtorReference

30 ++ Debtor Agent Mandatory, Complex type

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

31 +++ Financial Institution Identification Mandatory, Complex type

32 ++++ BICFI Mandatory Debtor.DebtorBankID

33 ++ Referred Document Optional, Complex type Usage rule: only one occurrence is allowed

34 +++ Type Mandatory (if Referred Document is provided), complex type

35 ++++ Code Or Proprietary Mandatory (if Referred Document is provided), complex type

36 +++++ Code Not allowed

37 +++++ Proprietary Mandatory (if Referred Document is provided), eMandate.PurchaseID

Table 13: Pain.009 message (new eMandate)

8.2.3 Content of container element for eMandate amendments A Debtor can amend the Debtor account number or maximum amount of an existing eMandate through the eMandate solution. The website-process is the same as with new eMandates, but in this case the Debtor indicates which existing eMandate (eMandateID) he wishes to adjust. The original Debtor Bank ID and the original Debtor IBAN are also included in the amendment request.

The following table describes which elements the Creditor sends to the Routing Service in the TransactionRequest, for an eMandate amendment.

Index ISO Message Element eMandates Requirement

1. + Message root Mandatory

2. + Group Header Mandatory, Complex type

3. ++ Message Identification Mandatory

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

Max35Text Format: maxLength: 35, minLength: 1

4. ++ Creation Date Time Mandatory

8.2.3.1.1.1 DateTime

5. + Underlying amendment details Mandatory, Complex type

6. ++ Amendment Reason Mandatory, Complex type

7. +++ Reason Mandatory, Complex type

8. ++++ Code Mandatory eMandate.AmendmentReason

9. ++ Mandate Mandatory, Complex type

10. +++ Mandate Identification Mandatory eMandate.eMandateID

11. +++ Mandate Request Identification Mandatory Must be: NOTPROVIDED

12. +++ Type Mandatory, Complex type

13. ++++ Service Level Mandatory, Complex type

14. +++++ Code Mandatory The identification code of the Scheme Usage Rule: Only ‘SEPA’ is allowed.

15. ++++ Local Instrument Mandatory, Complex type

16. +++++ Code Mandatory Specifies the local instrument Usage Rule: Only ‘B2B’ is allowed to indicate a B2B direct debit.

17. +++ Occurrences Mandatory, Complex type

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

18. ++++ Sequence Type Mandatory eMandate.SequenceType

19. ++++ Frequency Optional Usage rule: Not allowed in current implementation

20. +++++ Type Not allowed

21. +++++ Period Mandatory (if Frequency is provided), Complex type

22. ++++++ Type Mandatory (if Frequency is provided) eMandate.FrequencyPeriod

23. ++++++ CountPerPeriod Mandatory (if Frequency is provided) eMandate.FrequencyCount

24. +++ Maximum Amount Not allowed

25. +++ Reason Optional, Complex type

26. ++++ Code Not allowed

27. ++++ Proprietary Mandatory (if Reason is provided) eMandate.Reason

28. +++ Creditor Mandatory Must be empty Usage rule: Intentionally not filled further by the Creditor, as this will be filled by the Routing Service

29. +++ Debtor Mandatory, Complex type Must be empty if eMandate.DebtorReference is not used

30. ++++ Identification Optional, Complex type

31. +++++ Private Identification Optional, Complex type

32. ++++++ Other Optional, Complex type

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

33. +++++++ ID Optional eMandate.DebtorReference

34. +++ Debtor Agent Mandatory, Complex type

35. ++++ Financial Institution Identification Mandatory, Complex type

36. +++++ BICFI Mandatory Debtor.DebtorBankID This ID differs from Debtor.DebtorBankID in nr 53, in case of a bankswitch

37. +++ Referred Document Optional, Complex type Usage rule: only one occurrence is allowed

38. ++++ Type Mandatory (if Referred Document is provided), complex type

39. +++++ Code Or Proprietary Mandatory (if Referred Document is provided), complex type

40. ++++++ Code Not allowed

41. ++++++ Proprietary Mandatory (if Referred Document is provided) eMandate.PurchaseID

42. ++ Original Mandate Mandatory, Complex type This element contains several mandatory elements of the original eMandate

43. +++ Original Mandate identification Not allowed

44. +++ Original Mandate Mandatory, Complex type

45. ++++ Mandate identification Mandatory Usage rule: This is to specify the original eMandate identification and must be identical to data element 10. eMandate.eMandateID

46. ++++ Creditor Mandatory, Complex type (empty)

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

47. ++++ Debtor Mandatory, Complex type (empty)

48. ++++ Debtor Account Mandatory, Complex type

49. +++++ Identification Mandatory, Complex type

50. ++++++ IBAN Mandatory Debtor.IBAN Usage Rule: Must contain the IBAN of the original (e)Mandate

51. ++++ Debtor Agent Mandatory, Complex type

52. +++++ Financial Institution Identification Mandatory, Complex type

53. ++++++ BICFI Mandatory Debtor.DebtorBankID

8.2.3.1.1.1.1 Usage Rule: Must contain the Debtor Bank ID of the bank of the original (e)Mandate

Table 14: Pain.010 message (amendment)

8.2.4 Content of container element for eMandate cancellations A Debtor can cancel an eMandate through the eMandate solution. The website-process is the same as with new eMandates, but in this case the Debtor indicates which existing eMandate (eMandateID) he wishes to cancel AND the Debtor can only cancel his eMandate at the bank where the eMandate is currently registered. The Creditor must make this clear to the Debtor (to prevent the Debtor from choosing the wrong bank).

The following table describes which elements the Creditor sends to the Routing Service in the TransactionRequest, for an eMandate Cancellation.

Index ISO Message Element eMandates Requirement

1. + Message root Mandatory

2. + Group Header Mandatory, Complex type

3. ++ Message Identification Mandatory

Max35Text Format: maxLength: 35, minLength: 1

4. ++ Creation Date Time Mandatory

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

DateTime

5. + Underlying cancellation details Mandatory, Complex type

6. ++ Cancellation Reason Mandatory, Complex type

7. +++ Reason Mandatory, Complex type

8. ++++ Code Mandatory

eMandate.CancellationReason

9. ++ Original Mandate Mandatory, Complex type

This element contains the original eMandate

10. +++ Original Mandate identification Not allowed

11. +++ Original Mandate Mandatory, Complex type

This element contains the original eMandate

12. ++++ Mandate Identification Mandatory

8.2.4.1.1 eMandate.eMandateID

13. ++++ Mandate Request Identification Mandatory

Must be: NOTPROVIDED

14. ++++ Type Mandatory, Complex type

15. +++++ Service Level Mandatory, Complex type

16. ++++++ Code Mandatory

The identification code of the Scheme

Usage Rule: Only ‘SEPA’ is allowed.

17. +++++ Local Instrument Mandatory, Complex type

18. ++++++ Code Mandatory

The identification code of the Local Instrument

Usage Rule: Only ‘B2B’ is allowed to indicate a B2B direct

debit.

19. ++++ Occurrences Mandatory, Complex type

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

20. +++++ Sequence Type Mandatory

eMandate.SequenceType

21. +++++ Frequency Optional Usage rule: Not allowed in current implementation

22. ++++++ Type Not allowed

23. ++++++ Period Mandatory (if Frequency is provided), Complex type

24. +++++++ Type Mandatory (if Frequency is provided) eMandate.FrequencyPeriod

25. +++++++ CountPerPeriod Mandatory (if Frequency is provided) eMandate.FrequencyCount

26. ++++ Maximum Amount Optional

eMandate.MaxAmount

27. ++++ Reason Optional, Complex type

28. +++++ Code Not allowed

29. +++++ Proprietary Mandatory (if Reason is provided) eMandate.Reason

30. ++++ Creditor Mandatory

Usage rule: Must be empty. Intentionally not filled further by

the Creditor, as this will be filled by the Routing Service

31. ++++ Debtor Mandatory, Complex type

Usage rule: May be empty

32. +++++ Identification Optional , Complex type

33. ++++++ Private Identification Optional, Complex type

34. +++++++ Other Optional, Complex type

35. ++++++++ ID Optional

eMandate.DebtorReference

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

36. ++++ Debtor Account Mandatory, Complex type

37. +++++ Identification Mandatory, Complex type

38. ++++++ IBAN Mandatory

Debtor.IBAN

39. ++++ Debtor Agent Mandatory, Complex type

Mandatory, Complex type 40. +++++ Financial Institution Identification

41. ++++++ BICFI Mandatory

Debtor.DebtorBankID

42. ++++ Referred Document Optional, Complex type Usage rule: only one occurrence is allowed

43. +++++ Type Mandatory (if Referred Document is provided), complex type

44. ++++++ Code Or Proprietary Mandatory (if Referred Document is provided), complex type

45. +++++++ Code Not allowed

46. +++++++ Proprietary Mandatory (if Referred Document is provided), eMandate.PurchaseID

Table 15: Pain.011 message (cancellation)

8.3 TransactionResponse

If everything goes well the Routing Service will reply to the TransactionRequest with the TransactionResponse. Table 16 shows all fields of the TransactionResponse message. The TransactionResponse has no container, so there is no ISO message in this response (this is different in case of an ErrorResponse, see Chapter 10 on error handling).

Name Description Format createDateTimestamp Date and time at which TransactionResponse message was created. DT acquirerID Unique four-digit identifier of the Creditor Bank PN..4 (Creditor.CreditorBankID) within eMandates. issuerAuthenticationURL The complete Debtor Bank URL to which the Debtor shall be redirected AN..max 512 by the Creditor for authentication and authorisation of the transaction. transactionID Unique 16-digit number within eMandates. PN..16 The number consists of the Creditor.CreditorBankID (first four positions) and a unique number generated by the Routing Service (12

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

positions). This number uniquely defines each eMandate transaction. It is re- used in the StatusRequest to identify for which transaction the status is requested.

transactionCreateDate Date and time at which the transaction was first registered by the DT Timestamp Routing Service. This time can be used by Creditor, Routing Service and Validation Service for reporting on the transaction.

SignedInfo See 7.2 and 11.2 SignatureValue See 7.2 and 11.2 KeyInfo See 7.2 and 11.2

Table 16: Fields of the TransactionResponse

8.4 Errors when executing Transaction Protocol

A number of errors may occur when executing the eMandates Transaction Protocol. These may be related to unavailability or an error within your own web environment (Creditor), the Routing Service environment or the Validation Service environment.

The following situations may occur: 1. The eMandates transaction cannot successfully be initiated. 2. You receive an error response (message ‘X’) from your Routing Service within the set time-out period. 3. You do not receive any response within the set time-out period.

In all of the above cases, the transaction protocol cannot be successfully executed. This means it is not possible for the eMandates transaction to take place at that time. Error handling is explained in more detail in chapter 10.

8.5 Redirect to the online banking environment (issuerAuthenticationURL)

After receiving the TransactionResponse the Creditor has to redirect the Debtor to the issuerAuthenticationURL of the selected Debtor Bank, as stated in the TransactionResponse message. If the Creditor’s page contains HTML frames, these will be removed by the Debtor Bank (‘frame busting’). If and when the Debtor returns to the Creditor’s website (with the merchantReturnURL), the Creditor will have to completely rebuild its own page to show confirmation of eMandate reception.

8.5.1 Specific requirement eMandates Mobile: Redirect to Debtor Bank (no in-app browser) The Creditor needs to provide the redirect to the Debtor Bank from the browser window or Creditor app where the Debtor selected the Debtor bank. If it is not possible to keep the Debtor in the same browser window then this should be communicated to the Debtor (e.g.: “You will now be redirected to the app or (mobile) website of your bank”).

In case of a transaction initiated in the mobile Creditor app, it is not allowed to present the Debtor Bank approval screens in a web view component within the Creditor’s own app (in-app browser). The complete transaction flow, up to the redirect back to the Creditor’s app, must take place in an app that is trusted by the Debtor, either the Debtor’s chosen browser or the Debtor Bank’s mobile

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

app. Thus, the issuerAuthenticationURL must, for execution, be offered to the mobile operating system at all times. During the transaction flow it must not be possible for the Debtor to initiate another transaction through the Creditor’s original app.

Relevant details about the redirect from the Creditor to the Debtor Bank’s mobile channel:

- The Debtor Bank decides which Debtors to redirect to which channel. For example, some Debtor Banks may treat users of tablet devices the same as mobile users, while others will treat them like PC users;

- The Creditor should not intervene with the redirect, there is only one issuerAuthenticationURL for the Creditor to use in all transactions, not a separate URL for mobile eMandates transactions. The issuerAuthenticationURL should be executed by the operating system at all times;

- If the Debtor bank has integrated eMandates mobile in its mobile banking app, the Debtor is offered the option, on a ‘landing page’, to open the app or approve the eMandate via the (mobile) web page. On this ‘landing page’ the Debtor might be offered the option to download the latest version of the mobile banking app, if it is not yet installed on the Debtor’s device.

8.6 Redirect to the Creditor environment (merchantReturnURL)

After the Debtor has performed the necessary steps at the Debtor Bank he will be presented with a ‘Continue’ button that must redirect him back to the website of the Creditor with the merchantReturnURL as supplied in the TransactionRequest.

Two GET parameters are appended to this URL: the entranceCode (see paragraph 8.2) with ‘ec’ as GET parameter name, and the transactionID (see paragraph 0) with ‘trxid’ as GET parameter name. It is also possible for a Creditor to add additional parameters. For example, if the Creditor defines the merchantReturnURL as follows:

http://www.webshop.nl/processtransaction?producttype=electronics

The final URL will look something like:

http://www.webshop.nl/processtransaction?producttype=electronics&trxid= 0010123456789012&ec=4hd7TD9wRn76w6gGwGFDgdL7jEtb

The entranceCode field should contain a unique value, with the object of preventing message ‘sniffing’. Use of the same entranceCode each time would allow malevolent individuals to intercept the data from the merchantReturnURL and make fraudulent use of this information. This is why using unique values for the entranceCode is extremely important.

Note that a Debtor may not always use the redirect back to the Creditor environment that is offered by the Debtor Bank. Also note that in exceptional cases the Debtor Bank may be unable to match the transactionID in its system or another error occurs, which makes it impossible to redirect the Debtor back to the Creditor. In all other cases the Debtor is redirected with the parameters defined above, regardless of the final status of the transaction (success, cancelled, failed). The Creditor must then use the Status protocol (see chapter 9) to determine the status of the transaction.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

8.6.1 Requirements for eMandates Mobile: redirect to the Creditor environment. After the Debtor has been authenticated in either the mobile or regular channel and has approved the transaction, he is redirected back to the Creditor as normal (using the merchantReturnURL). The merchantReturnURL usually starts with ‘https’, redirecting the Debtor back to a page on the mobile device’s browser. If the Debtor has initiated the transaction from the Creditor’s mobile app, the merchantReturnURL can be an app handler, which will redirect the Debtor directly to the Creditor app. An app handler is a call that can be used to start an app and request it to initiate a specific action. For example a Creditor’s app handler can start with ‘nl.companyname.eMandates://’ and this will open the Creditor’s app.

NB: the merchantReturnURL should always direct to a web page or app of the Creditor (or party acting on behalf of the Creditor).

8.7 Errors during execution of the redirect to the Debtor Bank, approving the eMandate and/or the redirect to the Creditor environment

The following errors may occur during execution of the redirect to the online banking environment (Debtor Bank), the execution of the eMandate transaction at the Debtor Bank and/or the redirect back to your (Creditor) environment: • The bank page is unavailable as a result of which the Debtor cannot approve the eMandate, but the Debtor can’t be properly redirected to your confirmation page either

• The bank page is available but the Debtor cannot (after approving the eMandate or otherwise) be properly redirected to your confirmation page.

In both situations the Debtor cannot (as the result of a disturbance) return to your confirmation page in the normal way. In that case the Debtor can return to your website by using the ‘back’ button or entering the URL, for example.

If the Debtor can be identified (for example because he or she has logged into the Creditor environment or via the browser session), the advice in these situations is to check the status of the eMandates transaction (via the Status protocol) and notify the Debtor.

If the Debtor can be identified and the status can be checked but is found to still be 'open', we recommend that the Debtor is shown the following message: We haven’t received the confirmation of your eMandate from your bank yet. We will inform you as soon as we have received the confirmation.

If the Debtor can’t be identified upon return, your system should check the status of the eMandate transaction at the end of the expiration period.

In such situations, we also recommend that the status of the eMandate is reported to the Debtor – as soon as it has become final – in one of the ways indicated below: • By e-mail.

• On your website, for example in the account of the Debtor or via the Debtor's browser session.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

8.8 Four different scenario’s for completion of eMandates Mobile transaction

To give an overview of all the possible process steps and important notes when dealing with eMandates Mobile transactions, we have specified four different scenarios. There are four different scenarios because either the Debtor Bank or the Creditor or both can use a (mobile) web page or a mobile app.

Because these scenarios (could) differ from the regular (non-mobile) eMandates transactions they will be illustrated in the following paragraphs. Paragraph Creditor Issuing Bank

8.8.1 (Mobile) web page (Mobile) web page

8.8.2 (Mobile) web page Mobile banking app

8.8.3 Mobile app (Mobile) web page

8.8.4 Mobile app Mobile banking app

Table 17: Different scenario’s for the completion of an eMandates mobile transaction

8.8.1 Debtor is redirected from the Creditor’s (mobile) web page to the Debtor Bank’s (mobile) web page. This is currently the most common eMandates mobile scenario, as it is identical to the regular desktop eMandates transaction flow. As such there are no specific notes for use in a mobile setting, but this scenario has been added for reasons of completeness.

The Debtor starts the transaction on the Creditor’s mobile page and follows these steps: Step Description Important note 1 The Debtor selects eMandates as the payment method. 2 The Debtor selects his Debtor Bank. 3 The Debtor is redirected to the Debtor Bank of his choice. 4 The Debtor Bank presents the Debtor Bank ‘landing page’ to the Debtor, which offers the option to complete the eMandates transaction in the Debtor Bank’s mobile banking app or in the Debtor Bank’s (mobile) web page. 5 The Debtor selects the (mobile) web page. 6 The Debtor is redirected to the Debtor Bank’s (mobile) web page where he can log in and authorize the eMandates transaction. After completion of the transaction the Debtor Bank shows the complete eMandate to the Debtor.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

7 The Debtor is redirected back by the The merchantReturnURL usually starts with https:// and Debtor Bank, to the Creditor’s contains two parameters (entranceCode and (mobile) web page using the transactionID) that can be used to correctly identify the merchantReturnURL, which was Debtor upon his return. received from the Creditor. 8 The Creditor shows the Debtor the result of the eMandates transaction.

Table 18: Scenario: Redirect from Creditor (mobile) web page to the Debtor Banks (mobile) web page

8.8.2 Debtor is redirected from the Creditor’s (mobile) web page to the Debtor Bank’s mobile banking app The Debtor starts his customer journey on the Creditors (mobile) web page and follows the following steps:

Step Description Important note 1 The Debtor selects eMandates as the payment method. 2 The Debtor selects his Issuing Bank. 3 The Debtor is redirected to the Debtor Bank of his choice. 4 The Debtor Bank presents the Debtor Bank ‘landing page’ to the Debtor, which offers the option to complete the eMandates transaction in the Debtor Bank’s mobile banking app or in the Debtor Bank’s (mobile) web page. 5 The Debtor selects the mobile banking app. 6 The Debtor is redirected to the Debtor Bank’s mobile banking app where he can authorize the eMandates transaction. After completion of the transaction the Debtor Bank shows the complete eMandate to the Debtor. 7 The Debtor is redirected back by the Because the transaction takes place in the bank’s app, Debtor Bank, to the Creditor’s outside of the web-browser setting, the browser session (mobile) web page using the may be lost. This means the Creditor may not be able to merchantReturnURL, which was recognize the Debtor using the browser session. received from the Creditor. Next to this, when redirecting the Debtor back to the Creditor from the bank-app, the merchantReturnURL is handled by the Operating System of the mobile device. The OS uses the native (default) browser to handle this URL. This discontinues the original browser session if the transaction was initiated in a non-native browser. The merchantReturnURL starts with https:// and contains two parameters (entranceCode and transactionID) that can be used to correctly identify the Debtor upon his return. 8 The Creditor shows the Debtor the

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Step Description Important note result of the eMandates transaction.

Table 19: Scenario: Redirect form Creditor (mobile) web page to the Debtor Banks mobile banking app

8.8.3 Debtor is redirected from the Creditor’s mobile app to the Debtor Bank’s (mobile) web page The Debtor starts his customer journey on the Creditors mobile app and follows the following steps: Step Description Important note 1 The Debtor selects eMandates as the payment method. 2 The Debtor selects his Debtor Bank. 3 The Debtor is redirected to the Debtor It is mandatory for the Creditor to let the Operating Bank of his choice. System, which is installed on the Debtor’s mobile device, handle the issuerAuthenticationURL. See paragraph 8.5.1 for more information. 4 The Debtor Bank presents the Debtor Bank ‘landing page’ to the Debtor, which offers the option to complete the eMandates transaction in the Debtor Bank’s mobile banking app or in the Debtor Bank’s (mobile) web page. 5 The Debtor selects the (mobile) web page. 6 The Debtor is redirected to the Debtor Bank’s (mobile) banking page where he can log in and authorize the eMandates transaction. After completion of the transaction the Debtor Bank shows the complete eMandate to the Debtor. 7 The Debtor is redirected back by the The merchantReturnURL contains an app handler and Debtor Bank, to the Creditor’s app two parameters (entranceCode and transactionID) that using the merchantReturnURL, which can be used to correctly identify the Debtor upon his was received from the Creditor. return. See paragraph 8.6 for more information. 8 The Creditor shows the Debtor the result of the eMandates transaction.

Table 20: Scenario: Redirect from the Creditors mobile app to the Debtor Banks (mobile) web page

8.8.4 Debtor is redirected from the Creditor’s mobile app to the Debtor Bank’s mobile banking app The Debtor starts his customer journey on the Creditors mobile app and follows the following steps: Step Description Important note 1 The Debtor selects eMandates as the payment method.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

2 The Debtor selects his Debtor Bank. 3 The Debtor is redirected to the Debtor It is mandatory for the Creditor to let the Operating Bank of his choice. System, which is installed on the Debtor’s mobile device, handle the issuerAuthenticationURL. See paragraph 8.5.1 for more information. 4 The Debtor Bank presents the Debtor Bank ‘landing page’ to the Debtor, which offers the option to complete the eMandates transaction in the Debtor Bank’s mobile banking app or in the Debtor Bank’s (mobile) web page. 5 The Debtor selects the mobile banking app. 6 The Debtor is redirected to the Debtor Bank’s banking app where he can log in and authorize the eMandates transaction. After completion of the transaction the Debtor Bank shows the complete eMandate to the Debtor. 7 The Debtor is redirected back by the The merchantReturnURL contains an app handler and Debtor Bank, to the Creditor’s app two parameters (entranceCode and transactionID) that using the merchantReturnURL, which can be used to correctly identify the Debtor upon his was received from the Creditor. return. See paragraph 8.6 for more information. 8 The Creditor shows the Debtor the result of the eMandates transaction.

Table 21: Scenario: Redirect from the Creditors mobile app to the Debtor Banks mobile banking app

8.9 Performance and time-out of transaction message

The performance of the Debtor Bank and Routing Service systems has a direct influence on the Debtor’s user experience. Therefore eMandates sets a target time and time-out for the transaction response message. For a Creditor the relevant target time and time-out concerning the communication with its eMandates Routing Service:

Communication Target time (in seconds) Time-out (in seconds)

TransactionRequest à TransactionResponse 2.0 7.6

Table 22: Performance requirements (for the 95th percentile*)

The target time is the time (in seconds) within which the Creditor should receive a TransactionResponse message after sending a TransactionRequest. The time-out is the length of time after which the Creditor should no longer expect a response (most likely an error has occurred) and should act accordingly (for example by displaying an appropriate error message to the Debtor).

*95th percentile is a statistical term indicating that 95% of transactions in a tested sample should be within the set target time.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

8.10 Specific requirement eMandates Mobile: Print or e-mail confirmation message

After a successful regular eMandates transaction the Debtor Bank will always give the Debtor the option to print the confirmation of the eMandate. However in a mobile transaction environment printing will often not be possible, so this requirement is expanded to include alternatives such as e-mailing or downloading the confirmation to/by the Debtor.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

9 eMandates Status protocol

9.1 General

To verify whether an eMandate transaction was successful the Creditor will start the Status protocol by sending a StatusRequest to the Routing Service. Within the eMandates standards this message is referred to as the AcquirerStatusRequest.

To avoid unnecessary system load status requests should not be made unnecessarily, see 9.5 for more details on what is allowed. The StatusRequest message can be sent after the return of the Debtor to the Creditor’s website (after the redirect from the Debtor Bank), or after a specified amount of time as soon as the expiration period has expired (for example 5 or 10 minutes after the default expirationPeriod of 30 minutes has expired). As explained in paragraph 4.2 on Multiple signing, if the status is ‘pending’, this means the eMandate still needs to be signed by other Debtors. The Creditor may then execute the Status protocol on a daily basis. If the eMandates isn’t completed within 7 days, the status will be set to ‘expired’ by the Validation Service.

9.2 StatusRequest

Table 23 contains all fields that are part of the StatusRequest XML message. The Creditor sends this message to the Routing Service. Please refer to the clarification in paragraph 7.2 for the abbreviations in the Format column.

Name Description Format createDateTimestamp Date and time at which the StatusRequest message was created. DT

merchantID eMandate.ContractID as supplied to the Creditor by the Creditor PN...10 Bank. If the eMandate.ContractID has less than 10 digits leading zeros are used to fill out the field.

subID eMandate,ContractSubID, as supplied to the Creditor by the N..max 6 Creditor Bank, if the Creditor has requested to use this. A Creditor can request permission from the Creditor Bank to use one or more subIDs. In this way the Creditor.Tradename and relevant Creditor.Address belonging to the SubID will also be shown on the eMandate, next to the Creditor.Name. On the eMandate, this is shown as: Creditor.Name, on behalf of Creditor.TradeName. Unless agreed otherwise with the Creditor Bank, the Creditor has to use 0 (zero) as subID by default (if no subIDs are used). transactionID Unique 16-digit number within eMandates. PN..16 The number consists of the Creditor.CreditorBankID (first four positions) and a unique number generated by the Routing Service (12 positions). SignedInfo See 7.2 and 11.2

SignatureValue See 7.2 and 11.2 KeyInfo See 7.2 and 11.2

Table 23: Fields of the StatusRequest

9.3 StatusResponse

The reply to the StatusRequest is the StatusResponse. This message is created by the Validation Service and sent to the Creditor by the Routing Service. The StatusResponse contains the fields

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

listed in Table 24. This message communicates the status of the transaction (related to the transactionID which was sent in the StatusRequest) to the Creditor. If the status equals “Success”, the container element is included in the response. Inside the container element are the approved eMandate (the ISO pain.012 message) and the signature on the eMandate.

Name Description Format

createDateTimestamp Date and time at which the StatusResponse message was created. DT acquirerID Unique four-digit identifier of the Routing Service within eMandates. PN..4

transactionID Unique 16-digit number within eMandates. PN..16 The number consists of the Creditor.CreditorBankID (first four positions) and a unique number generated by the Routing Service (12 positions). status Indicates whether the eMandate transaction has been successful with one of CL the following statuses: AN..max 9 • Success: Positive result; the eMandate has been approved by the Debtor • Cancelled: Negative result due to cancellation by Debtor; no transaction has been made. • Expired: Negative result due to expiration of the transaction; no transaction has been made. • Failure: Negative result due to other reasons; no transaction has been made. • Open: Final result not yet known. A new StatusRequest is necessary to obtain the status. • Pending: Transaction has not yet been completed and is awaiting multiple signing. Status may be requested daily. statusDateTimestamp Present If Status = Success, Cancelled, Expired or Failure (not present DT when status = Open or Pending) This is the date and time at which the Debtor Bank established the Transaction.status for this transaction and recorded it as part of the transaction details. container 9.3.1.1.1.1 If Transaction.status is ‘Success’, this field is included in the StatusResponse. For all other values of Transaction.status, this field is not included. If this field is included, it contains the eMandate ISO message and the signature from the Validation Service. Both must be archived by the Creditor. SignedInfo See 7.2 and 11.2 SignatureValue See 7.2 and 11.2 KeyInfo See 7.2 and 11.2

Table 24: Fields of the StatusResponse

9.3.1 Content of container element for new eMandates, amendments or cancellations The following table specifies the eMandate elements in the ISO pain.012 message that is placed inside the container. The Validation Service signature is also placed inside the container, in the supplementary data of the ISO message. Please see paragraph 11 for more information. It is essential that the Creditor stores both the ISO pain.012 message and the signature (including the certificate information), at least until 13 months after the last direct debit collection related to the eMandate. The pain.012 message is nearly identical for new eMandates, amendments and cancellations. The only difference is in the field ‘Message Name Identification’; this element gets

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

the value ‘Issuing’ when the original TransactionRequest contained a pain.009 message. It gets the value ‘Amendment’ when the original TransactionRequest contained a pain.010 message. It gets the value ‘Cancellation’ when the original TransactionRequest contained a pain.011 message.

Index ISO Message element eMandates Requirement

1. + Message root Mandatory

2. + Group Header Mandatory, Complex type

3. ++ Message Identification Mandatory Max35Text Format: maxLength: 35, minLength: 1

4. ++ Creation Date Time Mandatory eMandate.DateTimestamp

5. ++ Authorisation Mandatory, Complex type

6. +++ Proprietary Mandatory ValidationService.ValidationReference

7. + Underlying Acceptance Details Mandatory, Complex type

8. ++ Original Message Information Mandatory, Complex type

9. +++ Message Identification Mandatory Message Identification from the original pain.009, pain.010 or pain.011 message in the TransactionRequest.

10. +++ Message Name Identification Mandatory Message.NameID Specifies the message name identifier to which the message refers (will have the value ‘Issuing’, ‘Amendment’ or ‘Cancellation’)

11. ++ Acceptance Result Mandatory, Complex type

12. +++ Accepted Mandatory Result of the Debtor validation

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message element eMandates Requirement

Usage rule: will be 1 or technical equivalent

13. ++ Original Mandate Mandatory, Complex type

14. +++ Original Mandate Mandatory

15. ++++ Mandate Identification Mandatory eMandate.eMandateID

16. ++++ Mandate Request Identification Mandatory eMandate.TransactionID

17. ++++ Type Mandatory, Complex type

18. +++++ Service Level Mandatory, Complex type

19. ++++++ Code Mandatory The identification code of the Scheme, will be ‘SEPA’

20. +++++ Local Instrument Mandatory, Complex type

21. ++++++ Code Mandatory Specifies the Local Instrument, will be ‘B2B’

22. ++++ Occurrences Mandatory, Complex type

23. +++++ Sequence Type Mandatory eMandate.SequenceType

24. +++++ Frequency Optional Usage rule: Not used in current implementation

25. ++++ Maximum Amount Optional Usage rule: Not used in current implementation

26. ++++ Reason Optional, Complex type

27. +++++ Proprietary Mandatory (if Reason is provided) eMandate.Reason

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message element eMandates Requirement

28. ++++ Creditor Scheme Identification Mandatory, Complex type

29. +++++ Identification Mandatory, Complex type

30. ++++++ Private Identification Mandatory, Structure element, Complex type

31. +++++++ Other Mandatory, Structure-element, Complex type

32. ++++++++ Identification Mandatory Creditor.CreditorID

33. ++++++++ Scheme Name Mandatory, Complex type

34. +++++++++ Code Mandatory Will be ‘SEPA’

35. ++++ Creditor Mandatory, Complex type

36. +++++ Name Mandatory Creditor.Name Usage Rule: ‘Name’ is limited to 70 characters in length.

37. +++++ Postal Address Mandatory, Complex type

38. ++++++ Country Mandatory Creditor.Country

39. ++++++ Address Line Mandatory Creditor.AddressLine1

40. ++++++ Address Line Mandatory Creditor.AddressLine2

41. ++++ Ultimate Creditor Optional, Complex type

42. +++++ Name Optional Creditor.TradeName Usage Rule: ‘Name’ is limited to 70 characters in length.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message element eMandates Requirement

43. ++++ Debtor Mandatory, Complex type

44. +++++ Name Mandatory Debtor.AccountName Usage Rule: ‘Name’ is limited to 70 characters in length.

45. +++++ Identification Optional, Complex type

46. ++++++ Private Identification Optional, Complex type

47. +++++++ Other Optional eMandate.DebtorReference

48. ++++ Debtor Account Mandatory, Complex type

49. +++++ Identification Mandatory, Complex type

50. ++++++ IBAN Mandatory Debtor.IBAN

51. ++++ Debtor Agent Mandatory, Complex type

52. +++++ Financial Institution Identification Mandatory, Complex type

53. ++++++ BICFI Mandatory Debtor.DebtorBankID

54. ++++ Ultimate Debtor Mandatory, Complex type

55. +++++ Name Mandatory Debtor.SignerName

56. ++++ Referred Document Optional, Complex type Usage rule: only one occurrence is allowed

57. +++++ Type Mandatory (if Referred Document is provided), complex type

58. ++++++ Code Or Proprietary Mandatory (if Referred Document is provided), complex type

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message element eMandates Requirement

59. +++++++ Proprietary Mandatory (if Referred Document is provided) eMandate.PurchaseID

60. + Supplementary Data Mandatory, Complex type

61. ++ Envelope Mandatory. Usage rule: contains element containing enveloped Signature over entire pain.012 . Enveloped XML signature

Table 25: Pain.012 message (acceptance report)

9.4 Errors during execution of Status Protocol

When using the Status Protocol to fetch the eMandate status, errors can occur as a result of which it is impossible for you to obtain the status of the transaction at that moment. It is therefore not possible to show the Debtor the final status of the transaction at that moment.

Recommended messages to show to Debtors are defined further on in this document.

In addition to this, we recommend informing your customer how he or she will be notified of the transaction status when it is known or where he or she can obtain that information (online).

You can then try to obtain the status through your Routing Service, in accordance with the guidelines. As soon as a definitive status has been received, you can notify the Debtor of the status of transaction in the following ways, for example: • By e-mail. • On your website, for example in the account of the Debtor or via the Debtor's browser session.

9.5 Collection duty

The Creditor has to initiate a StatusRequest when the Debtor returns to the page to which he was redirected by the Debtor Bank (the merchantReturnURL from the TransactionRequest). However, it is possible for the Debtor to close his browser before returning to this merchantReturnURL. It is mandatory for Creditors to perform a StatusRequest for every transaction, also in case the Debtor does not return to the Creditor’s website. The eMandates protocol prescribes a so called “collection duty” for the result of every transaction. The Creditor can comply with this “collection duty” by performing a StatusRequest for every transaction when the expiration period has passed and no final status has been retrieved yet.

If the retrieved status of a transaction is “Open”, the StatusRequest for this transaction has to be repeated after a short period of time. If the status of a transaction is “Pending”, this means the transaction is awaiting multiple signing in the Debtor Bank domain. The status can then be requested once per day.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

All other statuses (Cancelled, Expired, Success and Failure) are final statuses. Since these statuses cannot change anymore, it is not necessary (and not allowed) to perform another StatusRequest. To avoid unnecessary load on the eMandates systems, Creditors shall not perform unnecessary StatusRequests.

The following actions are never allowed: • Request the status of a transaction more than 5 times before the expiration period has passed; • Perform repeated StatusRequests with a time interval shorter than 60 seconds. The following actions are not allowed after the expiration period has passed: • Perform repeated StatusRequests with a time interval shorter than 60 minutes; • Request the status of a transaction more than 5 times per day; • Perform StatusRequests for transactions with a timestamp older than 14 days; • Request the status of a transaction after the final status of the transaction has been received; • Stop requesting the status of a transaction before the final status of the transaction has been received or before the timestamp is more than 14 days old.

Usually one of the final statuses or ‘Pending’ should be returned shortly after the expiration period. If the “Open” status is still returned after the expiration period, this can indicate a system failure. If this failure is not solved within 24 hours, please contact the Routing Service and stop sending StatusRequests.

Also when a Debtor does not return to your website because he does not appropriately complete or cancel the eMandates transaction, the Creditor must perform the Status Protocol after the expiration time has ended, to collect the final status at the eMandates Acquiring bank. As long as the returned status is “Open”, the status request must be repeated at least once or several times during the day (see guidelines stated above).This will provide the Creditor the opportunity to update the order status.

When the returned status is “Success” the Creditor will be able to continue the transaction with the Debtor (e.g. deliver an ordered product or service) When the Debtor returns to your website inappropriately (e.g. using browser buttons to get back from the Debtor Bank’s eMandate screens to the Creditor website) and decides to start a new eMandates transaction request, the Creditor must first try to collect the final status of the eMandates transaction that was initiated earlier, before sending a new TransactionRequest to the Routing Service.

9.6 Performance and time-out of status messages

The performance of the Debtor Bank/Validation Service and Routing Service systems has a direct influence on the Debtor’s user experience. Therefore eMandates sets a target time and time-out for the status response message. For a Creditor the relevant target time and time-out concern the communication with its eMandates Routing Service:

Communication Target time (in seconds) Time-out (in seconds)

StatusRequest à StatusResponse 2.0 7.6

Table 26: Performance requirements (for the 95th percentile*)

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

The target time is the time (in seconds) within which the Creditor should receive a StatusResponse message after sending a StatusRequest. The time-out is the length of time after which the Creditor should no longer expect a response (most likely an error has occurred) and should act accordingly (for example by displaying an appropriate error message to the Debtor).

*95th percentile is a statistical term indicating that 95% of transactions in a tested sample should be within the set target time.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

10 Error handling

10.1 General

If an error occurs while processing a DirectoryRequest, TransactionRequest or StatusRequest, for example because a request contains a invalid value, an ErrorResponse will be returned instead of the regular response. The ErrorResponse has the same structure for all three types of requests.

10.2 ErrorResponse

Instead of the regular response (DirectoryResponse, TransactionResponse of StatusResponse) the Routing Service will return an ErrorResponse if an error occurs during the reception or processing of the request, or if the request contains values that are not allowed or do not comply with the required format. Table 27 lists the fields that appear in the ErrorResponse. The error code list, errorDetail and consumerMessage can be found in APPENDIX B: Error codes.

Name Description Format createDateTimestamp Date and time at which the ErrorResponse message was DT created. errorCode Unique characteristic of the occurred error within the CL AN..6 eMandates system. Please refer to APPENDIX B for the error code list. errorMessage Descriptive text accompanying the ErrorCode. AN..max 128 errorDetail Details of the error. As determined and described by the AN..max 256 Routing Service. suggestedAction Suggestions aimed at resolving the problem. AN..max 512 consumerMessage A Routing Service can include a (standardised) message AN..max 512 here, which the Creditor should show to the Debtor. container This element is used if the Routing Service detects an error inside the pain message of a Transaction Request. It will then contain the pain.012 error acceptance report. In this case, the errorCode will have the value AP3000. The pain.012 error acceptance report will contain more information about the specifics of the error (see Table 28). The errorDetail may contain more information about which element in the pain message is causing the error. SignedInfo See 7.2 and 11.2 SignatureValue See 7.2 and 11.2 KeyInfo See 7.2 and 11.2

Table 27: Fields of the ErrorResponse

If the Routing Service detects an error inside the pain message (009, 010 or 011) in the container of the Transaction Request, the ErrorResponse will contain an ISO Pain.012 error response acceptance report. This message is shown in table 28. In this case, the errorCode in Table 27 will have the value AP3000. The pain.012 error acceptance report will have the status ‘rejected’ and it will also have a Reject Reason code. See APPENDIX B: Error codesAPPENDIX B for possible Reject Reasons.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Index ISO Message Element eMandates Requirement

1. + Message root Mandatory

2. + Group Header Mandatory, Complex type

3. ++ Message Identification Mandatory Max35Text Format: maxLength: 35, minLength: 1

4. ++ Creation Date Time 10.2.1.1.1.1 Mandatory DateTime

5. + Underlying Acceptance Details Mandatory, Complex type

6. ++ Original Message Information Mandatory, Complex type

7. +++ Message Identification Mandatory Message Identification from original message.

8. +++ Message Name Identification Mandatory

9. ++ Acceptance Result Mandatory, Complex type

10. +++ Accepted Mandatory Result of the Debtor validation Usage rule: will be ‘0 or technical equivalent’

11. +++ Reject Reason Mandatory, Complex type

12. ++++ Code Usage rule: only codes from Appendix B are used

13. +++ Additional Reject Reason Information Usage rule: will be present if Reject Reason is MD02.

14. ++ Original Mandate Mandatory, Complex type

15. +++ Original Mandate Identification Mandate Identification from original message. eMandate.eMandateID

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Table 28: Pain.012 error response acceptance report

10.3 Non-availability

It might be possible that one of the Debtor Banks is temporarily unavailable. In this case transactions that have to be processed by this Debtor Bank will generate an ErrorResponse (see previous paragraph). When the Routing Service has determined unavailability at a Debtor Bank it will communicate this to the Debtor Bank immediately. This means that Creditor will never have to contact the Debtor Bank directly.

It might also be possible that the Routing Service itself is temporarily unavailable. In this case, unless the Creditor has more than one Routing Service, no eMandate transactions can be processed and the Routing Service will generate an ErrorResponse or time-out.

When the Creditor confirmation page is not working properly, we recommend displaying a clear error message to the Debtor.

Subsequently, we also recommend you to report the status of the eMandate transaction to the Debtor in one of the ways indicated below: • By e-mail. • On your website, in the Debtor's account • On your website, as part of the session information of the order.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

11 Security and certificates

11.1 General principles of certificates

For asymmetric encryption two keys are used: one public key and one private key. The public key is linked to the certificate and can be shared with anyone. The private key must be kept confidential by the owner of the certificate. The specific characteristics of the private and public part of the certificates will allow the encryption of a message with the public part while the result can be decrypted with the private part, and vice versa. It is not possible to decrypt a text with the same key that was used to encrypt it.

These specific characteristics enable two applications of certificate:

1. Encryption of a message. By encrypting a message with the public key of the receiving party the information can only be read by the recipient (who has sole knowledge of the private key).

2. Creating an electronic signature of a message. By encrypting the (hash of a) message with the private key, the recipient can determine the authenticity of the (sender of the) message by successfully decrypting the signature with the public part of the certificate. The recipient will also verify the integrity of the message to make sure the contents of the message was not changed by a third party.

The one-sided TLS connection that is used within eMandates between the Creditor and the Routing Service is based on the first application. The TLS connection uses at least 128-bit encryption based on a server side certificate of the Routing Service.

Since eMandates does not put any constraints on the communication between the Debtor and the Creditor, this can be either with or without a TLS connection. Creditors are advised, however, to always use TLS on the transaction pages of their website. The eMandates standard also uses electronic signatures to ensure the authenticity, integrity and non- repudiation of all messages with the exception of redirects. The electronic signature of the Routing Service in the StatusResponse message, for example, enables the Creditor to verify the authenticity of the transaction confirmation.

11.2 Signing eMandates messages

All messages that are sent by the Creditor to the Routing Service (DirectoryRequest, TransactionRequest and StatusRequest) have to be signed by the Creditor. Messages are signed in accordance with the "XML Signature Syntax and Processing (2nd Edition) W3C Recommendation” of 10 June 20085, with the following settings and restrictions applied: 1. The entire XML message6 must be signed.

5 http://www.w3.org/TR/xmldsig-core/ 6 XML Signature reference to the signed info URI is left blank, see example messages in APPENDIX C

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

2. For the purpose of generating the digest of the main message, the exclusive7 canonicalization algorithm must be used. 3. For the purpose of generating the signature value, the exclusive8 canonicalization algorithm must be used. 4. The syntax for an enveloped9 signature must be used. The signature itself must be removed from the XML message using the default transformation prescribed for this purpose. 5. For hashing purposes the SHA-25610 algorithm must be used. 6. For signature purposes the RSAWithSHA25611 algorithm must be used. RSA keys must be 2,048 bits long. 7. The public key must be referenced using a fingerprint of an X.509 certificate. The fingerprint must be calculated according to the following formula HEX(SHA-1(DER certificate)) 12.

Note: According to Base64 specifications line breaks are allowed to be inserted after each 76 characters using a CR/LF13.

In general Creditors don’t need to have extensive knowledge of RSA since most programming languages have libraries available that implement XML Digital Signature processing. It is strongly recommended to use these standard libraries. Standard functionality for creation and verification of RSAWithSHA256 digital signatures is available in commonly used software platforms, from the following versions and higher: PHP version 5.3.0, Microsoft .NET version 3.5 sp1 and Java version 1.6 u18.

This functionality may also be available in earlier versions of these platforms and in other platforms (e.g. Python, Ruby).

For information about creating the public and private key pair please refer to paragraph 11.4.

11.2.1 Signing of the ISO pain.012 acceptance report Next to the regular signing of the entire XML message, the ISO message (that is placed inside the container element) is separately signed by the Debtor Bank (only for the status ‘Success’). This Debtor Bank signature remains in place during the lifespan of the eMandate, as it is the signature that can be checked to verify integrity and authenticity of the eMandate by the Debtor Bank at a later time in case of a dispute. It is essential that this remains the Debtor Bank’s signature, as the Debtor Bank has signed the eMandate ‘on behalf of the Debtor’.

- This signing follows the same requirements that apply to signing of the entire xml message, except for the following: Instead of referring to the certificate to be used for verifying the signature by fingerprint, the entire certificate is included in the Signature in the

7 http://www.w3.org/2001/10/xml-exc-c14n 8 http://www.w3.org/2001/10/xml-exc-c14n 9 http://www.w3.org/TR/xmldsig-core/#sec-EnvelopedSignature 10 http://www.w3.org/2001/04/xmlenc#sha256 11 http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/#sec-SHA256 12 See example messages in APPENDIX C 13 http://tools.ietf.org/html/rfc2045#section-6.8

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

X509Certificate element that is contained in the X509Data element in the KeyInfo element. This is done to guarantee availability of the certificate to check the signature in case of a dispute after many years. - The signature can only be validated when the ISO message is taken out of the XML container element, using exclusive canonicalization. Validation will fail when the ISO message is still embedded. Reason for this is the implicit reference from the signature to the element.

11.3 Authentication of eMandates messages

To ensure the status of a transaction, the Creditor has to verify the signature of the Routing Service in the Response messages. If the status is “success” the electronic signature in the pain.012 message should also be verified, to ensure the validity of the message.

To verify the signature in the SignatureValue field, it is recommended that Creditors use standard XML Digital Signature libraries, which are available in most (web) programming languages.

11.4 Creating a key pair

If you want to use a so-called “self signed certificate” this paragraph will explain how to do so. It is also possible to purchase a certificate at a company specialized in this field (Certificate Authority), see paragraph 11.4.1.

In order to create a public and a private key execute the following steps:

1. Download the “OpenSSL Library” from http://www.openssl.org. You can find more information on the “certificate generating utility” at: http://www.openssl.org/docs/apps/req.html. You may also generate the key pair using other software. If so please use the manual that comes with your software.

2. Generate an “RSA private key” using the following command (choose your own password for the field [privateKeyPass]):

openssl genrsa –aes-128 –out priv.pem –passout pass:[privateKeyPass] 2048

3. Create a certificate based on the “RSA private key” (use the same password as in the previous step for the field [privateKeyPass]):

openssl req –x509 –sha256 –new –key priv.pem –passin pass:[privateKeyPass] -days 1825 –out cert.cer

4. The previous OpenSSL command will generate a certificate in X.509 format, with a validity period of 5 years (1825 days), the maximum for eMandates signing certificates.

5. The file priv.pem contains the private key. The file cert.cer contains the certificate with the public key. The Creditor has to keep the priv.pem file private, which is used in the RSA encryption. The cert.cer file has to be communicated to the Routing Service. The method of communication will depend on the Routing Service.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

11.4.1 Buying a certificate from a Certificate Authority When buying a certificate from a Certificate Authority (CA), rather than generating the certificate yourself it is important to note the following: the CA signing certificate (and the rest of the certificate chain) must use hashing algorithms and key lengths that are at least as secure or better than those of the Creditor certificate.

Therefore CA-certificates used to sign certificates for electronic signatures must use at least SHA-256 for hashing and 2,048 bits for RSA keys.

Signing certificates should also have a maximum validity period of 5 years.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

12 Presentation

12.1 General

There are some requirements regarding the presentation of eMandates on the Creditor’s website. The main purpose of these requirements is to create a uniform user experience for Debtors whenever they use eMandates, regardless which Creditor’s website they use. The requirements are further explained in the following paragraphs.

The front-end communication to the Debtor is based on the following primary relationships and responsibilities:

- A Debtor chooses to ‘mandate’ the Creditor for a one off or recurring B2B SEPA Direct Debit by means of an eMandate. - The Creditor offers the Debtor the possibility to choose eMandates as a method to ‘mandate’ the Creditor to execute a (one off or recurring) Direct Debit. - The Validation Service of the Debtor Bank offers the Debtor the ability to authenticate himself and to approve the eMandate. The Debtor Bank bears primary responsibility for the eMandate approval process and for the related communication to the Debtor.

A Creditor that accepts eMandates has to place the eMandates payment method in its list of offered payment methods, in such a way that it is a logical step in the Creditor’s online process.

The eMandates payment method must be presented in the list of payment methods in such a way that it receives at least the same amount of attention as other payment methods.

12.2 Incassomachtigen via uw bank-button

It must be clear for the Debtor how and when eMandates has been chosen by the Debtor. This is achieved by displaying an eMandates button, generally on that part of the page where one of the payment methods is normally selected. It must be very clear to the Debtor that he is using Business to Business eMandates, instead of a regular Core eMandate. The eMandates button must have the text: ‘Zakelijk Incassomachtigen via uw bank’.

12.3 Transaction flow

When the ‘Incassomachtigen via uw bank’ button is clicked, the Debtor should immediately be presented with the Debtor Bank selection list without any intermediate screens being displayed by the Creditor (e.g. Debtor login and/or registration screens). And when the Debtor has selected the required Debtor bank, he should be immediately redirected to the online bank environment of the selected Debtor Bank (based on the issuerAuthenticationURL the Creditor has received in the TransactionResponse).

12.4 Redirect to Debtor Bank

The Creditor needs to perform the redirect to the Debtor Bank, from the browser window where the Debtor selected the Debtor Bank. The complete page of the Creditor shall be replaced by the complete page of the selected bank. Therefore it is not allowed to open the redirect to the Debtor

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

Bank in a new browser window. It is however allowed to open a new window, with visible address bar, before the Debtor selects his bank from the Debtor Bank list.

12.5 Frames

Frames used on the Creditor’s site are allowed. The page of the Debtor Bank will remove these frames using a frame busting technique. This will allow the Debtor to verify whether the transaction is really taking place at the bank chosen from the Debtor Bank list. After the redirect to the Creditor the Creditor shall completely rebuild the Creditor page to show the Creditor’s confirmation of reception of the (amended) eMandate.

12.6 New Window

The eMandates transaction may take place in a new browser window, as long as the Creditor will have this window appear at (or before) the moment the Debtor chooses the transaction method. A new window is only allowed if initiated by the Debtor (no pop-ups are allowed). The complete transaction flow must take place in this window, including the Creditor’s confirmation of receiving the eMandate. The new window must also contain an address bar that allows the Debtor to check the Internet address URL and SSL-certificate of the Debtor Bank. During the transaction flow it should not be possible for the Debtor to initiate another transaction through the Creditor’s original browser window.

12.6.1 Specific Requirements eMandates Mobile: New window or app The Mobile eMandate process may redirect the Debtor to a different mobile page or app as part of the transaction. The Creditor should strive to keep the Debtor on one browser page as much as possible but it is not allowed to make use of an in-app browser in the Creditor app (see Chapter 6 for more details). In those cases where changing to another app or window is necessary (such as the redirect to the Debtor Bank) the Debtor should be informed beforehand in order to avoid confusion (e.g.: “You are being redirected to the (mobile) web site or the app of your bank”).

12.7 Debtor Bank list

The Debtor Bank list has to be presented as described in paragraph 7.4.

12.8 ‘Incassomachtigen via uw bank’ banners and logo's

The eMandates logo can be found in the eMandates style guide, available at http://www.incassomachtigen.nl/wp-uploads/HandleidingHuisstijl_2_1.pdf.

12.9 Explaining eMandates to Debtors

Merchants that want to provide specific help and instructions to Debtors regarding Business to Business eMandates are advised to use the following text:

How does ‘Zakelijk Incassomachtigen via uw bank’ work?

A few simple steps is all it takes to pay using ‘Incassomachtigen via uw bank’:

• Place your order

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

• Select ‘Zakelijk Incassomachtigen via uw bank’ as your payment method

• Select your bank

• This opens the familiar (mobile) banking environment or mobile app of your own bank

• The relevant details of your eMandate will already be shown

• You approve the eMandate in the way you are accustomed to at your bank

• Your bank confirms your eMandate and you can email it or download it • You return to this website – eMandate accepted and you can continue shopping

Dutch version

Hoe werkt ‘Zakelijk Incassomachtigen via uw bank?

U kunt in een paar eenvoudige stappen betalen met ‘Incassomachtigen via uw bank’

• U bestelt een product of dienst

• Selecteer ‘Zakelijk Incassomachtigen via uw bank’ als uw betaalmethode

• Selecteer de bank waar u de rekening heeft waar u de machtiging op wilt afgeven

• U komt direct in de (mobiele) bankieromgeving of app van uw bank

• De relevante gegevens van uw machtiging zijn al ingevuld

• Op de voor u bekende manier keurt u de machtiging goed

• Uw bank bevestigt de Incassomachtiging en u kunt het emailen of downloaden • U keert terug naar deze website. De machtiging is geaccepteerd en u kunt weer verder winkelen

12.10 Creditor front-end

The Creditor bears primary responsibility for initiating the Business to Business eMandate process and for the communication to the Debtor regarding the status of the eMandate.

- A Creditor must make sure in the design of his implementation that the eMandates solution and the start of an eMandate process are recognisable as such. The Creditor must also distinguish clearly between the process of issuing, amending or cancelling an eMandate - Creditors who accept eMandates must include the eMandates solution in their lists of payment methods (if any). - The eMandates solution must be presented in the list of methods in such a way that it receives at least the same amount of attention as other payment methods. - It must be clear for the Debtor that an eMandates transaction is going to start.

The Creditor must offer the Debtor three eMandate-functionalities:

1. Issuing a new eMandate

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

A new eMandate can be issued for example when the Creditor gets a new customer (Debtor) or when an existing customer (Debtor) needs to issue a new mandate due to additional (new) products or services. 2. Amending an existing eMandate Amending an existing eMandate is done only when the Debtor wishes to change his account number (within the same Bank or to a different Bank) or to change the maximum amount per Direct Debit. Other Debtor changes (such as address changes) and Creditor changes are not relevant to the eMandate. 3. Cancelling an existing eMandate The Debtor can choose to cancel an existing eMandate. The Creditor must notify the Debtor to choose the bank at which the eMandate is currently registered. The Debtor is redirected to the Debtor Bank to validate the cancellation.

The Creditor must clearly indicate to the Debtor whether he is issuing a new eMandate, or amending/cancelling an existing eMandate.

12.11 Debtor Bank front-end

All eMandate related information (i.e. eMandate information, Debtor information, Creditor information and Signer information), with the exception of the Debtor Reference number (klantnummer), is presented to the Debtor for approval by the Validation Service.

In detail, the following information is shown to the Debtor for approval:

Creditor information

- Creditor.Name - Creditor.TradeName (optional) - Creditor.AddressLine1 - Creditor.AddressLine2 - Creditor.Country - Creditor.CreditorID

Debtor information - Debtor.IBAN - Debtor.AccountName

eMandate information

- eMandate.eMandateID - eMandate.Reason (optional) - eMandate.SequenceType - eMandate.FrequencyCount(optional & not in current version) - eMandate.FrequencyPeriod (optional & not in current version

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

- eMandate.MaxAmount14 - eMandate.PurchaseID (optional) - The term SEPA must be mentioned on the eMandate

Signer-information - Debtor.SignerName

The following screenshots show examples of Validation Service eMandate approval website or mobile app screen for one-off eMandates, with Creditor.TradeName (Figure 5), and an example of the confirmation screen following approval of the eMandate proposal by the Debtor (figure 6). Please note that these are example screens and are for illustration purposes only.

Figure 5: Example of one-off eMandate approval website or mobile app screen

14 For new eMandates, If the Creditor hasn’t included a maximum amount in the eMandate transactionrequest, the Debtor Bank allows the Debtor to fill out a maximum amount. This maximum amount is added to the ISO pain.012 message. For eMandate amendments, the Creditor is not allowed to include a maximum amount in the pain.010 message. The Debtor Bank shows the maximum amount value from it’s registration list and allows the Debtor to adjust this value..

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

After approval, the Validation Service shows the complete eMandate to the Debtor. The Debtor can print, email or save the eMandate to his computer (Figure 6). Upon the redirect from Debtor Bank to the Creditor’s website, the Creditor shows a message to the Debtor indicating whether the eMandate process was successful (e.g. “We have successfully received the eMandate / We hebben uw machtiging succesvol ontvangen” or “We have not yet received confirmation of the eMandate / We hebben nog geen bevestiging van het eMandate ontvangen”). There is no obligation for the Creditor to show the eMandate contents to the Debtor at this point.

Figure 6: Example of one-off eMandate confirmation website or mobile app screen

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

13 eMandates and direct debit

In this chapter the relation between eMandates and the collection of Business to Business direct debits is explained, as well as the relation with the Dutch Overstapservice (Debtors can use this service to change the accountnumber for all of their mandates at once). .

13.1 Initiating direct debits

It is important to note that eMandates is not a means of pre-notification; this still needs to take place.

The document “XML message for SEPA Direct Debit Initiation Implementation Guidelines for The Netherlands” of the Dutch Payments Association describes the requirements to the pain.008 XML message that is used to initiate direct debits.

When a Business direct debit collection is based on an eMandate, the direct debit contains several values from the pain.012 status response (the eMandate). The elements from the pain.012 status response that are used are:

• eMandate.eMandateID - The eMandateID that is determined by the Creditor • Debtor.AccountName - The name of the accountholder as it is known at his bank. • Debtor.IBAN - The account number of the Debtor, which the Creditor is authorized to collect directs debits from. • ValidationService.ValidationReference - Reference to the signing of the eMandate by the Debtor, generated by the Debtor Bank. • eMandate.DateTimestamp – The timestamp of signing of the eMandate by the Debtor, generated by the Debtor Bank. Note: In the pain.008 direct debit collection message only the date of the eMandate.DateTimestamp must be included.

Chapter 9.3.1 shows where the relevant elements can be found in the pain.012 message. Table 29 shows where in the pain.008 direct debit initiation message these elements are placed.

Element in pain.012 Pain.008 index and message item eMandate.eMandateID 2.48 MandateIdentification

The date from eMandate.DateTimestamp 2.49 DateOfSignature

Debtor.IBAN 2.73 IBAN ValidationService.ValidationReference 2.62 ElectronicSignature

Debtor.AccountName 2.72 Name

Table 29: Mapping of pain.012 elements to pain.008 direct debit initiation message

In the event that an eMandate is amended via the eMandates amendment process, this is processed in the direct debit collection message in the same manner as when a paper mandate would be amended.

Business direct debits are checked against the Debtor Bank’s mandate registration. When the Debtor issues/amends/cancels an eMandate, the Debtor Bank immediately uses this information to update the mandate registration. This way, Creditors can initiate the direct debit collection process immediately upon reception of the pain.012 message.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

13.2 Relation with the Overstapservice

When the Debtor uses the Overstapservice, the Creditor is informed of the change of the Debtor’s account number. The Creditor saves the transfer data together with the original eMandate. The Debtor does not have to issue a new eMandate, nor amend the existing eMandate. The Debtor does have to re-register each mandate at his new Debtor Bank.

Alternatively, Instead of using the Overstapservice, a Debtor can also choose to use the amendment-functionality of eMandates. This allows the Debtor to change each eMandate invididually. In this case, the eMandate is automatically added to the eMandate registration of the new Debtor Bank.

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

APPENDIX A: Container content overview

The eMandate information is in the ISO messages that are put inside the information container element. The following tables give an overview of the ISO pain message content in the container of the messages for new eMandates and for eMandate amendments.

Message Container content B. AcquirerTrxReq pain.009.001.04

F’ AcquirerStatusRes pain.012.001.04 B’ (X) AcquirerErrorRes pain.012.001.04 (Error response version)

Table 30: Container content for new eMandates

iDx Message eMandates specific content B. AcquirerTrxReq pain.010.001.04

F’ AcquirerStatusRes pain.012.001.04 B’ (X) AcquirerErrorRes pain.012.001.04 (Error response version)

Table 31: Container content for eMandate amendments

iDx Message eMandates specific content B. AcquirerTrxReq pain.011.001.04 F’ AcquirerStatusRes pain.012.001.04 B’ (X) AcquirerErrorRes pain.012.001.04 (Error response version)

Table 32: Container content for eMandate cancellations

Creditor Implementation Guidelines – eMandates B2B Document version 1.02 - CONFIDENTIAL

APPENDIX B: Error codes