MonetaWeb 2.0 January 2018

Transcription

1 January 2018

2 INDEX 1.INTRODUCTION USE OF SPECIFICATIONS OF SERVICES...6 SPECIFICATIONS FOR API CALLS...6 SPECIFICATIONS FOR THE RESPONSE...6 CERTIFICATES PAYMENT PROTOCOLS PROTOCOL FOR MO.TO. AND NOT SECURE E-COMMERCE PAYMENTS...7 TRANSMISSION OF PAYMENT MESSAGE...7 RECEIPT OF OUTCOME MESSAGE...8 ERROR CASES XML HOSTED 3D SECURE PROTOCOL...10 PAYMENT INITIALISATION...12 PAYMENT OUTCOME NOTIFICATION...13 ERROR CASES D SERVER-TO-SERVER XML PROTOCOL...17 VERIFY ENROLLMENT D SECURE AUTHENTICATION, REDIRECTION OF CARDHOLDER...23 VERIFY PARES...24 PAY PAYTHREESTEP MYBANK PAYMENT (SEPA CREDIT TRANSFERT)...28 MYBANK PAYMENT INITIALISATION...29 PAYMENT OUTCOME NOTIFICATION...31 ERROR CASES PAYPAL PAYMENT...34 PAYMENT INITIALISATION...35 PAYMENT OUTCOME NOTIFICATION...37 ERROR CASES MASTERPASS PAYMENTS...41 PAYMENT INITIALISATION...42 PAYMENT OUTCOME NOTIFICATION...43 ERROR CASES MONETAWALLET (TOKENIZATION) - RECURRING PAYMENTS ACTIVATION SUBSEQUENT PAYMENTS...47 SPECIFICATIONS FOR SUBSEQUENT ONLINE PAYMENTS...47 SPECIFICATIONS FOR SUBSEQUENT BATCH PAYMENTS DELETION...48 TRANSMISSION OF WALLET DELETION MESSAGE...48 RECEIPT OF WALLET DELETION OUTCOME MESSAGE...48 Technical Documentation 2 January 2018

3 4.4.FAILURE OUTCOME NOTIFICATION ERROR MESSAGE NOTIFICATION ACCOUNTING AND REVERSAL PROCESSES PAYMENT MANAGEMENT SERVICES PAYMENT CONFIRMATION (POSTING REQUEST)...51 TRANSMISSION OF PAYMENT CAPTURE MESSAGE...51 RECEIPT OF CONFIRMATION OUTCOME MESSAGE...52 ERROR CASES ACCOUNTING REVERSAL...53 TRANSMISSION OF ACCOUNTING REVERSAL MESSAGE...53 RECEIPT OF ACCOUNTING REVERSAL OUTCOME MESSAGE...54 ERROR CASES AUTHORISATION CANCELLATION...56 TRANSMISSION OF AUTHORISATION CANCELLATION MESSAGE...56 RECEIPT OF AUTHORISATION CANCELLATION OUTCOME MESSAGE...56 ERROR CASES FORCED VOID AUTHORIZATION...58 TRANSMISSION OF FORCED VOID AUTHORIZATION MESSAGE...58 RECEIPT OF FORCED VOID AUTHORIZATION OUTCOME MESSAGE...58 ERROR CASES INQUIRY, QUERY BY TRANSACTION...60 TRANSMISSION OF INQUIRY MESSAGE...60 RECEIPT OF INQUIRY OUTCOME MESSAGE...61 ERROR CASES...63 APPENDIX...64 A. TEST ENVIRONMENT...64 TEST CARDS TEST ENVIRONMENT CREDENTIALS...65 CREDENTIALS FOR PAYPAL OF THE TEST ENVIRONMENT...66 CREDENTIALS FOR MASTERPASS OF THE TEST ENVIRONMENT...66 MYBANK PAYMENT UNDER TESTING...67 B. TRINIZ FORMAT...68 FILE STRUCTURE...69 MSG TRINIZ START OF TRANSMISSION...70 MSG COINIZ START OF ENTRY...71 MSG DETAIL DETAIL RECORD...72 MSG COFINE END OF ENTRY...72 MSG TRFINE END OF TRANSMISSION...73 MSG DETAIL DETAIL RECORD FOR ACCOUNTING FOR ENTRY ACKNOWLEDGEMENT FOR POSTING VIA FILE..73 MSG DETAIL DETAIL RECORD FOR RECURRING PAYMENTS...74 MSG DETAIL DETAIL RECORD FOR AUTHORISATIONS FOR POSTING VIA FILE...76 C. STATUS CONTRACT/WALLET ID MANAGEMENT AND CARDS ALIGNMENT FORMAT..79 FILE STRUCTURE...81 Technical Documentation 3 January 2018

4 HEAD RECORD TAIL RECORD DETAIL RECORD STATUS CONTRACT/WALLET ID MODIFICATION...83 DETAIL RECORD CARDS ALIGNMENT...84 D. ADMITTED CURRENCIES LIST...87 E. GRAPHICS RESOURCES (BUTTONS AND LOGOS)...88 F. ISO RESPONSE CODE...89 G. MONETAWEB ERROR CODES...91 H. MONETAWALLET (TOKENIZATION) - RECURRING PAYMENTS ERROR CODES...93 Technical Documentation 4 January 2018

5 1. Introduction MonetaWeb is a next-generation virtual POS designed for who, through an internet site, wants to sell goods or services by managing online payments with credit card. Choosing our service will have the following benefits: Ease of integration Flexibility, management of online payments through main international circuits. Any extension to circuits American Express, Diners Club and JCB may be assessed at the request of the Client; Security, thanks to compliance with the security standards set by the international circuits (Verified by Visa and Mastercard Secure Code for the circuit); Transparency, the traditional hardcopy reports are accompanied by an online-report through the website. MonetaWeb 2.0 is an electronic payment platform that provides clients with a suite of payment protocols and a set of payment methods according to specific needs. All transmissions of sensitive information involving the merchant, Setefi's systems and the end customer, are encrypted according to the HTTPS protocol, in line with the security standards imposed by the International Circuits. Setefi's Systems are also subjected to regular security checks and constantly updated to protect against any vulnerabilities detected for standard protocols. Since 2014 Setefi has been certified PCI-DSS. This document is intended as a guide for developers, it does not mention the functional aspect. Below we will analyze in detail the various protocols that MonetaWeb provides, as well as procedures for the activation, acknowledgment, authorization and reversal of payments, the file structure used for batch procedures (TRINIZ), the ISO ResponseCode and error codes returned by the platform. This technical documentation is everything you need to understand online payment protocols and be able to test them in total autonomy. Technical Documentation 5 January 2018

6 2. Use of Specifications of Services The services published by MonetaWeb support the HTTP protocol with channel encryption and use the NVP format for the request and XML format for the response. Here are the technical details for sending messages: SPECIFICATIONS FOR API CALLS Protocol HTTPS Method POST Content-Type application/x-www-form-urlencoded TEST URL PRODUCTION URL SPECIFICATIONS FOR THE RESPONSE The response messages to the call to one of synchronous services use the XML format. Within the paragraph of each payment protocol, examples are shown with the correct path. CERTIFICATES Ensure you have installed certificates for TEST and PRODUCTION environments, as follows: TEST Certificate for test.monetaonline.it Root Certificate: Thawte Primary Root CA Serial Number: 34 4e d d5 ed ec 49 f4 2f ce 37 db 2b 6d CA Intermediate: Thawte SSL CA G2 Serial Number: d6 88 6d e d bf 11 bf PRODUCTION Certificate for Root Certificate: VeriSign Class 3 Public Primary Certification Authority G5 Serial Number: 18 da d1 9e 26 7d e8 bb 4a cd cc 6b 3b 4a CA Intermediate: Symantec Class 3 EV SSL CA G3 Serial Number: 7e e1 4a 6f 6f ef f2 d3 7f 3f ad 65 4d 3a da b4 Technical Documentation 6 January 2018

7 3. Payment Protocols 3.1. Protocol for MO.TO. and not secure E-commerce payments The acronym MO.TO. (Mail Order/Telephone Order) refers to the Server-to-Server payments, in which the cardholder's 3D Secure authentication is not requested. In these cases, the payment phase is completed by sending to MonetaWeb a message in POST containing all the data required to perform the payment and receipt of a response in synchronous mode containing the payment outcome. In those cases where the holder submit data on their credit card directly to the Merchant's system, he is subject to PCI regulations; Setefi reserves the right to request a document proving the certification. TRANSMISSION OF PAYMENT MESSAGE Example of HTTP payment message: id= &password= &operationtype=pay&amount=1.00&currencycode=978&merc hantorderid=trackingno12345&description=description&cardholdername=namesurname&card= &cvv2=123&expiryMonth=09&expiryYear=2015&customField=customField Call parameters of HTTP payment message: Name Description Type Length id id associated with terminal char 8 password Terminal id password varchar 50 operationtype pay varchar 50 amount currencycode merchantorderid Transaction amount using the point as decimal separator (e.g. 1428,76 = " "). The decimal portion may vary depending on the currency. Currency numeric code (optional default '978' [euro]) Transaction reference (can contain only letters and numbers and must be absolutely unique) decimal 18.4 varchar 3 varchar 18 description Payment description (optional) varchar 255 cardholdername Cardholder name varchar 125 card Credit card number varchar 19 cvv2 Credit card security code varchar 4 expirymonth Credit card expiry month (mm) char 2 expiryyear Credit card expiry year (yyyy) char 4 customfield Custom field (optional) varchar 255 Technical Documentation 7 January 2018

8 RECEIPT OF OUTCOME MESSAGE Example of XML message with payment outcome: <response> <result>approved</result> <authorizationcode>123456</authorizationcode> <paymentid> </paymentid> <merchantorderid>trackingno12345</merchantorderid> <customfield>customfield</customfield> <rrn> </rrn> <responsecode>000</responsecode> <description>description</description> <cardcountry>italy</cardcountry> <cardtype>visa</cardtype> (only if the terminal is enabled for the function) </response> Parameters of response to payment message: paymentid result responsecode Name Description Type Length authorizationcode merchantorderid rrn Unique identifier of the MonetaWeb authorization request Transaction outcome: - APPROVED, transaction authorised - NOT APPROVED, transaction rejected - CAPTURED, transaction confirmed Response code (e.g. 000 if the transaction is authorised, in all other cases the transaction is rejected) Authorisation code, which is entered only if the transaction has been authorised Transaction Reference sent to the merchant in Initialisation phase (can contain only letters and numbers and must be absolutely unique) Unique transaction reference generated by the Authorisation System (to be used in case of explicit posting via file) varchar 18 varchar 20 char 3 varchar 6 varchar 18 varchar 12 description Payment description (optional) varchar 255 customfield Custom field sent to the merchant in Initialisation phase varchar 255 cardcountry Nationality of the used credit card char 255 cardtype Circuit and type of credit card used (upon request) - ['Amex', 'Diners', 'Maestro', 'Mastercard', 'Moneta', 'Visa', 'BAPAYPAL', 'PAYPAL'] varchar 10 Technical Documentation 8 January 2018

9 ERROR CASES Behaviour of the system in case of error in payment phase When incorrect parameters are sent (e.g. unknown terminal, incorrect password, invalid amount, ) MonetaWeb responds with an error message in XML format. This message includes: - an error code - a mnemonic description of the error Example of error message in Initialisation phase: <error> <errorcode>xyz123</errorcode> <errormessage>invalid amount</errormessage> </error> Technical Documentation 9 January 2018

10 3.2. XML Hosted 3D Secure Protocol The XML Hosted 3DSecure protocol provides for the possibility to perform safe mode payments at all steps of the transaction; In fact, the protocol allows to pay in compliance with the latest security protocols (Verified by Visa and MasterCard SecureCode) that guarantee non-repudiation of most transactions, and the standards of PCI (Payment Card Industry) DSS (Data Security Standards) Security. The payment page of MonetaWeb is available in both Web and Mobile version with automatic calling device recognition. The supported mobile operating systems are: ios for ipad and iphone version 4 and above Android version 4 and above Windows Phone for versions starting from 7 The page provides two levels of customization: Display Merchant's logo Customize CSS files, they can be downloaded through the respective url: [Web]: phoenix.css [Mobile]: phoenix-mobile.css Both the customized logo and CSS files must be sent by mail to the E-Commerce support service for the validation and publication. The logo must be in graphical format (jpeg or png) and with a maximum size of 350 pixels in width and no height restriction. The cookies generated by the payment page during navigation is technical, and used only for statistical purposes and not commercial. For further details, please click below: Technical Documentation 10 January 2018

11 1. The cardholder makes a purchase on the merchant's site; payment data is transmitted to the Merchant's server 2. The Merchant's server initialises the payment with an HTTP Post message 3. MonetaWeb validates Initialisation 4. MonetaWeb returns the PaymentID, a security token and the URL of the Hosted Payment Page 5. The Merchant's server redirects the cardholder to the HPP using the PaymentID as parameter 6. The cardholder fills in the form with the credit card sensitive data 7. MonetaWeb logs payment data 8. MonetaWeb sends a Verify Enrollment Request (VEReq) to the Directory Servers of the Circuits 8A. The Directory Servers of the Circuits draft the request to the Issuer 8B. The Issuer replies to the Directory Servers of the Circuits with the enrollment outcome and the URL of the Access Control Server (ACS) 9. The Directory Servers of the Circuits respond with a Verify Enrollment Response (VERes) 9A. MonetaWeb redirects the cardholder to the ACS of the Issuer with the Payment Authentication Request (PAReq) 9B. The ACS responds with the Payment Authentication Response (PARes) 10. MonetaWeb sends the payment outcome in server to server mode to the Merchant's ResponseURL 11. MonetaWeb reads the ResultURL dynamically returned by the Merchant within the ResponseURL page 12. MonetaWeb redirects the cardholder to the ResultURL For the following transactions follow the specifications of the Server-to-Server messages provided in the following chapters: payment confirmation accounting reversal authorisation cancellation inquiry Technical Documentation 11 January 2018

12 PAYMENT INITIALISATION The first phase of the payment consists og transmitting the preliminary payment data to MonetaWeb, such as amount, currency, order reference and url to continue the payment. After receiving this data, MonetaWeb returns an output in XML format, a unique PaymentId, a security token, and the page url to enter the credit card details Example of HTTP Payment Initialisation message: id= &password= &operationtype=initialize&amount=1.00&currencycode=978& language=ita&responsetomerchanturl= recoveryurl= n& cardholdername=namesurname&cardholder =name@domain.com& customfield=customfield Call parameters of HTTP payment message for Payment Initialisation: Name Description Type Length id terminal id char 8 password Terminal id password varchar 50 operationtype 'initialize' varchar 50 amount currencycode language responsetomerchanturl recoveryurl merchantorderid description Transaction amount using the point as decimal separator (e.g. 1428,76 = " "). The decimal portion may vary depending on the currency. Currency numeric code (optional default '978' [euro]) Language in which the Hosted Page will be displayed: 'DEU' for GERMAN, 'FRA' for FRANCE, 'ITA' for ITALIAN, 'POR' for PORTUGUESE, 'RUS' for RUSSIAN, 'SPA' for SPANISH, 'USA' for ENGLISH Url to which the transaction outcome must be notified Url to which the holder must be redirected if you cannot obtain a resulturl in notification phase (optional) Transaction reference (can contain only letters and numbers and must be absolutely unique) Payment description that will be displayed on the payment page at the homonymous field (optional) decimal 18.4 varchar 3 varchar 3 varchar 2048 varchar 2048 varchar 18 varchar 255 cardholdername Cardholder name (optional) varchar 125 Technical Documentation 12 January 2018

13 cardholder customfield Cardholder's address to which the payment outcome must be notified (optional) Custom field that will be returned in notification phase (optional) varchar 125 varchar 255 Example of XML message for Payment Initialisation response: <response> <paymentid> </paymentid> <securitytoken>80957febda6a467c82d34da0e0673a6e</securitytoken> <hostedpageurl> </hostedpageurl> </response> Parameters of response to Payment Initialisation message: Name Description Type Length paymentid Id associated to the payment session varchar 18 securitytoken Security token varchar 32 hostedpageurl Payment page url to which the cardholder is directed varchar 255 Cardholder redirection to payment page: After receiving an initialisation message response, the web session of the cardholder must be redirected to the url specified in the hostedpageurl tag to which the paymentid parameter must be appended. This url must not be set as fixed parameter for redirection but must be retrieved dynamically for every payment from the appropriate tag. Once the cardholder is on the payment page, he will enter the data for his credit card and, if the card is part of the 3D Secure program, he will also be prompted to enter the relevant 3D Secure password. PAYMENT OUTCOME NOTIFICATION If credit card details are entered correctly by the cardholder, payment is processed by MonetaWeb and the Merchant receives a notification about the payment outcome. The notification is made through HTTP posts in NVP (NameValue Pair) format on the url specified in the responsetomerchanturl parameter. The securitytoken is, among the various passed-in-post parameters, a security quantity generated by MonetaWeb and notified to the Merchant both upon initialisation response, and upon outcome notification; for security purposes, it is recommended to make sure that the value of the securitytoken received corresponds with anything received during initialisation. In order to redirect the web session of the cardholder to a new page containing the transaction outcome, the Merchant must reply to the notification message, which was newly received from MonetaWeb with the url of its outcome page containing the 'paymentid' as parameter. This url may be enriched with parameters to be able to display the outcome correctly. Pay attention: the response must not contain HTML code. Technical Documentation 13 January 2018

14 Upon notice of a hosted payment to the merchant URL response, once the connection has started, our services wait for 20 seconds to receive the final URL for the redirection. At the end of the timeout, the socket is closed. In case the response URLs a self-signed certificate or issued by a secondary CA, you must provide the support of MonetaWeb the full chainwheel in PEM format encoded in X509, sorrow, outcome notification failure. Import requests into environment PRODUCTION must be scheduled at least one month before. Should the notification of the url for holder redirection fail (unavailability of the responsetomerchanturl page, invalid content of the responsetomerchanturl page, response timeout or the certificate is not recognized) MonetaWeb will redirect the holder to the recoveryurl page, which is notified by the Merchant through the appropriate parameter of the Initialisation message. If the recoveryurl parameter was not filled in in, MonetaWeb will redirect the holder to a courtesy page, published directly on MonetaWeb server. By the detail page of the transaction, from the Back-Office portal, you can see errors with notification of its causal. MonetaWeb courtesy page will appear as shown below: Example of payment outcome message: Approved authorisation: authorizationcode=85963&cardcountry=italy&cardexpirydate=0115&cardtype=visa& customfield=some custom field&maskedpan=483054******1294& merchantorderid=trck0001&paymentid= &responsecode=000& result=approved&rrn= &securitytoken=80957febda6a467c82d34da0e0673a6e&t hreedsecure=s Payment cancelled by cardholder: Technical Documentation 14 January 2018

15 paymentid= , result=canceled, threedsecure=n Parameters of HTTP message for payment outcome notification: paymentid result Name Description Type Length responsecode authorizationcode merchantorderid threedsecure rrn maskedpan cardtype Unique identifier of the order generated by MonetaWeb that corresponds to the same field received in response during the Initialisation phase Transaction outcome: - APPROVED, transaction authorised - NOT APPROVED, transaction rejected - CAPTURED, transaction confirmed - CANCELED, the cardholder cancelled the transaction. The response will just contain paymentid, result and threedsecure parameters. Response code (e.g. 000 if the transaction is authorised, in all other cases the transaction is rejected) Authorisation code, which is entered only if the transaction has been authorised Transaction Reference sent to the Merchant in Initialisation phase (can contain only letters and numbers and must be absolutely unique) Transaction security level: 'S' (Full Secure transaction), 'H' (Half Secure transaction), 'N' (Not Secure transaction) Unique transaction reference generated by the Authorisation System (to be used in case of explicit posting via file) Masked PAN of the used credit card (in the form xxxxxx7890) Circuit and type of the used credit card (upon request)- ['Amex', 'Diners', 'Maestro', 'Mastercard', 'Moneta', 'Visa', 'BAPAYPAL', 'PAYPAL'] varchar 18 varchar 20 char 3 varchar 6 varchar 18 char 1 varchar 12 varchar 19 varchar 10 cardcountry Nationality of the used credit card varchar 255 cardexpirydate customfield Expiration date of the used credit card (in the format mmaa) Custom field sent to the Merchant in Initialisation phase varchar 4 varchar 255 securitytoken Security token varchar 32 ERROR CASES Initialisation phase When incorrect parameters are sent (e.g. unknown terminal, incorrect password, invalid amount, ) MonetaWeb responds with an error message in XML format. This message includes: Technical Documentation 15 January 2018

16 - an error code - a mnemonic description of the error Example of error message in Initialisation phase: <error> <errorcode>xyz123</errorcode> <errormessage>invalid amount</errormessage> </error> Initialisation phase When a payment can not be completed (e.g. 3DSecure authentication failed) MonetaWeb notifies the Merchant an error message in NVP format. This message includes: - an error code - a mnemonic description of the error - a payment id Example of error message in Notification phase: errorcode=gv00004, errormessage=gv00004-pares status not successful, paymentid= Technical Documentation 16 January 2018

17 3.3. 3D Server-To-Server XML Protocol The XML Server to Server 3D Secure Protocol allows the Merchant to have complete control of the transaction by invoking synchronous services call and at the same time benefit from the protection offered by the 3D secure protocol. The protocol provides that the holder submit data on their credit card directly to the Merchant's system, who is then subject to PCI regulations; Setefi reserves the right to request a document proving the certification. Enrolled case 1. The cardholder makes a payment via the Merchant's site; payment data are transmitted to the Merchant's server 2. The Merchant's server sends a VerifyEnrollment message to MonetaWeb to verify participation of the card in the 3D Secure protocol 3. MonetaWeb send a VEReq (Verify Enrollment Request) to the Visa/Mastercard interoperability domain 3A. Visa/Mastercard forwards the request to the Issuer 3B. The Issuer replies to e Visa/Mastercard with the outcome and the URL of the ACS (Access Control Server) 4. Visa/Mastercard responds with the VERes (Verify Enrollment Response) 5. Once the authentication is completed, MonetaWeb send to the Merchant's server the outcome of verifying participation of the card in the 3D Secure protocol and the PAReq (Payment Authentication Request) 6. The Merchant's server redirects the cardholder to the ACS of the Issuer together with the PAReq Technical Documentation 17 January 2018

18 7. The ACS redirects the holder to the Merchant's return page passing the PARes (Payment Authentication Response) as parameter 8. The Merchant's Server sends to MonetaWeb the authentication outcome (PARes) via a verifypares message 9. MonetaWeb sends the data that are necessary to process a 3D Secure authorisation request. If authentication fails, the payment will be aborted. 10. The Merchant sends to Setefi an authorisation request (operationtype=paythreestep) containing all the details (order details, card details, 3D Secure authentication details) 11. MonetaWeb processes the authorisation request and returns the outcome to the Merchant. Not enrolled case 1. The cardholder makes a payment via the Merchant's site; payment data are transmitted to the Merchant's server 2. The Merchant's server sends a VerifyEnrollment message to MonetaWeb to check the card for participation in the 3D Secure protocol 3. MonetaWeb sends VEReq (Verify Enrollment Request) message to Visa/Mastercard interoperability domain 3A. Visa/Mastercard forwards the request to the Issuer 3B. The Issuer replies to Visa/Mastercard with the verification outcome 4. Visa/Mastercard responds with the VERes (Verify Enrollment Response) message 5. MonetaWeb replies to the Merchant reporting that the card must not perform authentication. 6. The Merchant sends to Setefi an authorisation request (operationtype=paythreestep) containing all the details (order details, card details, ECI flag) Technical Documentation 18 January 2018

19 7. MonetaWeb processes the authorisation request and returns the outcome to the Merchant. Not supported case 1. The cardholder makes a payment via the Merchant's site; payment data are transmitted to the Merchant's server 2. The Merchant's server sends a VerifyEnrollment message to MonetaWeb 3. MonetaWeb checks the card for participation in the 3D Secure protocol 4. MonetaWeb replies to the Merchant reporting that the card is not supported 5. The Merchant sends to Setefi an authorisation request (operationtype=pay) containing all the details (order details, card details,...) 6. MonetaWeb processes the authorisation request and returns the outcome to the Merchant. For the following transactions follow the specifications of the Server-to-Server messages provided in the following chapters: payment confirmation accounting reversal authorisation cancellation inquiry VERIFY ENROLLMENT As part of the flow for Server-to-Server payments, this is the servlet exposed to verify card enrollment; it receives in input the payment data, including the sensitive data related to the credit card and returns in output the unique id associated with the payment, the outcome of the 3D Secure verification and, in the event of enrolled card, the PaReq message and the url of the ACS. Example of request: id= &password= &operationtype=verifyenrollment&card= &c vv2=892&expiryyear=2018&expirymonth=02&cardholdername=member&amount=0.1&currencyco de=978&description=description&customfield=customdata&merchantorderid=order001 Technical Documentation 19 January 2018

20 Request parameters: Name Description Type Length id id associated with terminal char 8 password Terminal id password varchar 50 operationtype verifyenrollment varchar - amount currencycode merchantorderid Transaction amount; the point is used as decimal separator (e.g. 1428,76 = " "). The decimal portion may vary depending on the currency. Currency numeric code (optional default '978' [euro]) Transaction reference (can contain only letters and numbers and must be absolutely unique) decimal 18.4 varchar 3 varchar 18 description Payment description (optional) varchar 255 cardholdername Cardholder name (optional) varchar 125 card Credit card number varchar 19 cvv2 Credit card security code varchar 4 expirymonth Credit card expiry month (mm) char 2 expiryyear Credit card expiry year (yyyy) char 4 customfield Custom field sent to the Merchant in Initialisation phase varchar 255 Technical Documentation 20 January 2018

21 Example of response: Enrolled case <response> <result>enrolled</result> <paymentid> </paymentid> <customfield>customdata</customfield> <description>description</description> <merchantorderid>order001</merchantorderid> <PAReq>eJxVkt1u4jAQhV8Fcb(...)</PAReq> <url> </response> Not enrolled case <response> <result>not ENROLLED</result> <paymentid> </paymentid> <customfield>customdata</customfield> <description>description</description> <merchantorderid>order001</merchantorderid> <eci>01</eci> </response> Not Supported case (Circuit not participating) <response> <result>not SUPPORTED</result> <customfield>customdata</customfield> <description>description</description> <merchantorderid>order001</merchantorderid> </response> Technical Documentation 21 January 2018

22 Response parameters: Name Description Type Length result Outcome of verification of participation in the 3D Secure protocol: ENROLLED = the card is enrolled in the 3D Secure protocol and is provided with authentication credentials NOT ENROLLED = the card is enrolled in varchar 20 the 3D Secure protocol, but is not provided with authentication credentials NOT SUPPORTED = the card is enrolled in the 3D Secure protocol paymentid Id associated to the payment session varchar 18 customfield Custom field (optional) varchar 255 description Payment description (optional) varchar 255 merchantorderid eci PaReq url Transaction Reference chosen by the Merchant (can contain only letters and numbers and must be absolutely unique) Electronic Commerce Indicator: security level indicator for the transaction; it is only returned in the NOT ENROLLED case For ENROLLED result only: encrypted message to be sent to the authentication system of the card issuer (ACS) URL of the authentication page exposed by the Issuing Bank (for the ENROLLED case only) varchar 18 char 2 varchar max varchar 2083 Technical Documentation 22 January 2018

23 3D SECURE AUTHENTICATION, REDIRECTION OF CARDHOLDER In the event of enrolled card, the Merchant must redirect the holder to the URL of the authentication page exposed by the Issuing Bank; below is a construction example of the form: <form name="redirect" action="<%=acsurl%>" method="post"> <input type=hidden name="pareq" value="<%=pareq%>" > <input type=hidden name="termurl" value="<%=termurl%>" > <input type=hidden name="md" value="<%=paymentid%>" > </form> POST parameters: Name Description Type Length PaReq encrypted message containing payment data varchar max TermUrl Return url to which the Bank's ACS will return the outcome. varchar 2083 MD Id associated to the payment session (paymentid) varchar 18 After completing authentication, the holder will be redirected to the TermUrl and receive two parameters: MD, authentication session identifier and PaRes (Payer Authentication Response), authentication encrypted outcome. The PaRes will have to be forwarded to Setefi for validation, decoding, and extraction of the values required to submit the authorisation request in full/half secure mode. Technical Documentation 23 January 2018

24 VERIFY PARES As part of the flow for Server-to-Server payments, this is the servlet exposed to validate the PaRes message validation and return the 3D Secure parameters associated to the payment signature; it receives in input the PaRes message, returned by the ACS and containing the authentication outcome, and returns in output their decrypted and simplified versions. Example of request: id= &password= &operationtype=verifypares&paymentid= &pares=eJydWFmzosqyfudXdKzzSPRmVGGHvU4UMyoIMolvTDKDCgry60+pPazdu(...) Request parameters: Name Description Type Length id id associated with terminal char 8 password Terminal id password varchar 50 paymentid Id associated to the payment session varchar 18 operationtype verifypares varchar 50 PaRes Encrypted message obtained in response by the authentication system of the card issuer (ACS) varchar max Example of response: <response> <paymentid> </paymentid> <cavv>aaacbsmafqaaaaaaaaavaaaaaaa=</cavv> <cavvalgo>2</cavvalgo> <eci>05</eci> <merchantacquirerbin>494330</merchantacquirerbin> <currency>978</currency> <xid>eftyu1m8owlhszcmowhnkczxzf4=</xid> <purchasedate> :07:33</purchasedate> <purchaseamount>100</purchaseamount> <exponent>2</exponent> <time> :07:33</time> <status>y</status> <pan> </pan> <vendorcode>123456</vendorcode> <version>1.0.2</version> </response> Technical Documentation 24 January 2018

25 Response parameters: Name Description Type Length paymentid Id associated to the payment session varchar 18 cavv Payment signature varchar 255 cavvalgo Cavv encryption algorithm char 2 eci Electronic Commerce Indicator: security level indicator of the transaction char 02 merchantacquirerbin Acquirer Identification Code char 6 currency Currency char 3 xid Unique Id associated with the 3D Secure process varchar 255 purchasedate Purchase date (yyyymmdd hh:mm:ss) date - purchaseamount Amount decimal - exponent Number of decimal numbers int 1 time Timestamp (yyyymmdd hh:mm:ss) date - status Authentication outcome: Y, authentication successfully completed N, authentication failed A, Enrollment during payment U, technical problem during authentication char 1 pan Masked pan varchar 19 vendorcode Vendor MPI identification code varchar 255 version Version of 3D Secure protocol varchar 10 Expected behaviour depending on the authentication outcome Status Pares Required action Y Authorisation request in 3D (Full Secure) mode N Abort payment A Authorisation request in 3D (Half Secure) mode U Authorisation request in NO 3D (eci 07) mode PAY As part of the flow for Server-to-Server payments, this is the servlet exposed for authorisation request in case of 3D Secure not participating schemes (verifyenrollment with result = [NOT SUPPORTED]); it receives in input all payment details: order details, card details (eci, if present, must me equal to '07'); it returns in output the payment outcome. Technical Documentation 25 January 2018

26 PAYTHREESTEP As part of the flow for Server-to-Server payments, this is the servlet exposed for authorisation request in case of [ENROLLED, NOT ENROLLED] cards; it receives in input all payment details: order details, card details, 3D Secure details, if any; it returns in output the payment outcome. Example of request: id= &password= &operationtype=paythreestep&paymentid= &amount=0.1&currencycode=978&merchantorderid=order001&description= description&cardholdername=member&card= &expiryyear=2018&expirymonth =02&cvv2=123&customfield=customdata&eci=05&xid=eFtyU1M8OWlhSzcmOWhNKCZXZF4=&cavv= AAACBSMAFQAAAAAAAAAVAAAAAAA= Request parameters: Name Description Type Length id id associated with terminal char 8 password Terminal id password varchar 50 operationtype paymentid amount currencycode merchantorderid Pay for NOT SUPPORTED result cases only Paythreestep for ENROLLED, NOT ENROLLED result cases only Id associated with the payment session (returned by Verify Enrollment), to use for PAYTHREESTEP cases only Transaction amount; use the point as decimal separator (e.g. 1428,76 = " "). The decimal portion may vary depending on the currency. Currency numeric code (optional default '978' [euro]) Transaction reference (can contain only letters and numbers and must be absolutely unique) varchar - varchar 18 decimal 18.4 varchar 3 varchar 18 description Payment description (optional) varchar 255 cardholdername Cardholder name (optional) varchar 125 card Credit card number varchar 19 cvv2 Credit card security code varchar 4 expirymonth Credit card expiry month (mm) char 2 expiryyear Credit card expiry year (yyyy) char 4 customfield Custom field (optional) varchar 255 eci xid Electronic Commerce Indicator: security level indicator of the transaction. Unique Id associated with the 3D Secure process, to use for PAYTHREESTEP cases only (if returned in PaRes) char 2 varchar 255 Technical Documentation 26 January 2018

27 cavv Payment signature, to use for PAYTHREESTEP cases only if returned in PaRes) varchar 255 The ECI must be filled in with the value received in the verifyenrollment in the event of NO 3D and with the value received in the verifypares in the event of secure transaction (FULL or HALF). Example of response: <response> <result>approved</result> <authorizationcode>695683</authorizationcode> <paymentid> </paymentid> <merchantorderid>order001</merchantorderid> <rrn> </rrn> <responsecode>000</responsecode> <cardcountry>italy</cardcountry> <description>description</description> <customfield>customdata</customfield> </response> Response parameters: Name Description Type Length result authorizationcode paymentid merchantorderid rrn responsecode cardtype Transaction outcome: APPROVED, transaction authorised NOT APPROVED, transaction rejected CAPTURED, transaction confirmed Authorisation code, which is entered only if the transaction has been authorised Id associated to the payment session (in PAYTHREESTEP case, it corresponds to the value returned by the Verify Enrollment) Transaction Reference chosen by the Merchant (can contain only letters and numbers and must be absolutely unique) Unique transaction reference generated by the Authorisation System (to be used in case of explicit posting via file) Response code (e.g. 000 for approved transaction, otherwise not approved) Circuit and type of credit card used (upon request) - ['Amex', 'Diners', 'Maestro', 'Mastercard', 'Moneta', 'Visa', 'BAPAYPAL', 'PAYPAL'] varchar 20 varchar 6 varchar 18 varchar 18 varchar 12 char 3 varchar 10 cardcountry Nationality of credit card used char 255 description Description varchar 255 Technical Documentation 27 January 2018

28 customfield Custom field sent to the Merchant in Initialisation phase varchar MyBank payment (SEPA Credit Transfert) MyBank is an online payment service promoted by the EBA Clearing and supported by major European banks, including Intesa Sanpaolo. MyBank is a solution designed to facilitate the use of online SEPA payment instruments in the operations of e-commerce and e-government. It is based on an operational mode that conveys electronic authorizations (e-authorization), on payments for e-commerce, through the SEPA Credit Transfer Scheme. MyBank allows the online seller to provide immediate confirmation of the credit transfer order. The payment details of the purchase will be automatically displayed on the online banking system of the own bank and the customer can confirm the details of the transaction authorizing the credit transfer. The buyer electronic authorization will be considered irrevocable immediately allowing the shipment of goods or the provision of the service. 1. The Buyer makes a purchase on the Merchant's site choosing MyBank as payment instrument 2. The Merchant's server initialises the payment 3. MonetaWeb validates Initialisation 4. MonetaWeb returns to the Merchant the PaymentID, a security token and the URL of the Bank selection page 5. The Merchant's server redirects the Buyer to the page chosen by the Bank 6. The Buyer chooses the Bank from among available banks 7. MonetaWeb contacts EBA Routing Service Technical Documentation 28 January 2018

29 8. The Routing Service returns the MyBank id and the bank's URL 9. The Buyer is redirected to the internet banking of the selected Bank 10. The Buyer authenticates and finds a pre-completed SEPA credit transfer, confirms the payment 11. The Buyer receives the outcome of the transfer from the Bank in real time 12. The Bank redirects the Payer to MonetaWeb 13. MonetaWeb contact the Routing Service of EBA to find out the outcome of the credit transfer 14. The Routing Service of EBA sends the requested outcome to MonetaWeb 15. MonetaWeb sends the payment outcome in server to server mode to the ResponseURL via the Merchant's server 16. The Merchant sends the Merchant's ResultURL over the same socket 17. MonetaWeb redirects the Buyer to the merchant's outcome page (ResultURL) MYBANK PAYMENT INITIALISATION The first phase of the payment consists in transmitting the preliminary payment data to MonetaWeb, such as amount, transaction reference etc. After receiving these data, MonetaWeb returns in output in XML format, a unique PaymentId, a security token, and the page url chosen by the Bank Example of HTTP Payment Initialisation message: id= &password= &operationtype=mybank&amount=1.00&responsetomerchant Url= recoveryurl= n& cardholdername=namesurname&cardholder =name@domain.com& customfield=customfield Technical Documentation 29 January 2018

30 Call parameters of HTTP payment message for Payment Initialisation: Name Description Type Length id id associated with terminal char 8 password Terminal id password varchar 50 operationtype 'initializemybank' varchar 50 amount responsetomerchanturl recoveryurl merchantorderid Transaction amount using the point as decimal separator (e.g. 1428,76 = " "). The decimal portion may vary depending on the currency. Url to which the transaction outcome must be notified Url to which the holder must be redirected if you cannot obtain a resulturl in notification phase (optional) Transaction reference (can contain only letters and numbers and must be absolutely unique) decimal 18.4 varchar 2048 varchar 2048 varchar 18 description Payment description (optional) varchar 255 cardholdername Cardholder name (optional) varchar 125 cardholder Cardholder's address to which the payment outcome must be notified (optional) varchar 125 customfield Custom field (optional) varchar 255 Example of XML message for Payment Initialisation response: <response> <paymentid> </paymentid> <securitytoken>80957febda6a467c82d34da0e0673a6e</securitytoken> <hostedpageurl> </response> Parameters of response to Payment Initialisation message: Name Description Type Length paymentid Id associated to the payment session varchar 18 securitytoken Security token varchar 32 hostedpageurl Url of the page chosen by the Bank varchar 255 Technical Documentation 30 January 2018

31 Payer redirection to the page chosen by the Bank: After receiving an initialisation message response, the web session of the payer must be redirected to the url specified in the hostedpageurl tag to which the paymentid parameter must be appended. This url must be considered as a fixed value. However, for every payment, it must be retrieved dynamically from the appropriate tag After accessing this page, the payer must select the Bank to which the credit transfer is performed. If the Payer does not find his own bank in the list of participants ones, It is possible to switch to credit card payment. In this case, the response notification path will be the card payment one. You can inhibit the switching to credit card payment, by sending a request to the E-Commerce support. PAYMENT OUTCOME NOTIFICATION After authentication on the home banking, the payer will find a pre-completed SEPA credit transfer that may be confirmed. The payer will receive the credit transfer outcome from the Bank and, in order to continue, must click the button prepared by the Bank and will be directed to a MonetaWeb transition page. Here the Merchant is provided with a notification of the payment outcome. The notification is made through HTTP posts in NVP (NameValue Pair) format on the url specified in the responsetomerchanturl parameter. The securitytoken is, among the various passed-in-post parameters, a security quantity generated by MonetaWeb and notified to the Merchant both upon initialisation response, and upon outcome notification; for security purposes, it is recommended to make sure that the value of the securitytoken received corresponds with anything received during initialisation. In order to redirect the web session of the payer to a new page containing the transaction outcome, the Merchant must reply to the notification message, which was newly received from MonetaWeb with the url of its outcome page hanging the 'paymentid' up as parameter. This url may be enriched with custom parameters to be able to display the outcome correctly. Upon notice of a hosted payment to the merchant URL response, once the connection has started, our services wait for 20 seconds to receive the final URL for the redirection. At the end of the timeout, the socket is closed. Should the notification of the url for holder redirection fail (unavailability of the responsetomerchanturl page, invalid content of the ToMerchantUrl response page and response timeout) MonetaWeb will redirect the holder to the recoveryurl page, which is notified by the Merchant through the appropriate parameter of the Initialisation message. If the recoveryurl parameter was not filled in in, MonetaWeb will redirect the holder to a courtesy page, published directly on MonetaWeb server. If, during payment Initialisation, the recoveryurl parameter was not filled in in, MonetaWeb will redirect the payer to a courtesy page, published directly on MonetaWeb server. MyBank protocol, defined by the EBA consortium, provides that the response to the Merchant will be sent only after the Payer (Account Holder) has returned from the bank page he chose to make the transfer. In cases where the Payer does not return from the Bank's own page and then terminates the payment process as by protocol, the gateway offers the possibility, through the inquiry tool, to know at any time the status of the transaction. MyBank integration is subject to certification and therefore adheres to the EBA consortium protocol. Technical Documentation 31 January 2018

32 Parameters of HTTP message for payment outcome notification: Name Description Type Length paymentid result description Unique identifier of the order generated by MonetaWeb that corresponds to the same field received in response during the Initialisation phase Transaction outcome: AUTHORISED: credit transfer authorised by the payer's Bank ERROR: credit transfer not completed because it was denied by the payer's Bank AUTHORISINGPARTYABORTED: credit transfers aborted by the payer (after acces to the portal of the Bank CANCELED: payment abandoned or cancelled by the payer (before access to the portal of the Bank). The response will just contain paymentid and result parameters. Payment description sent by Merchant during initialization phase varchar 18 varchar 32 varchar 255 authorizationcode End-to-end payment ID varchar 35 merchantorderid mybankid customfield Transaction Reference sent to the Merchant in Initialisation phase (can contain only letters and numbers and must be absolutely unique) Unique identifier of the payment released by mybank's circuit Custom field sent to the Merchant in Initialisation phase varchar 18 numeric 35 varchar 255 securitytoken Security token varchar 32 MyBank transactions automatic update: All MyBank payments assume PENDING status (on Setefi's systems) waiting for the Bank to receive the outcome of the credit transfer. The payer has 15 minutes, from the beginning of the transaction, to confirm the credit transfer. Beyond this limit, the payment status will be set to TIMEOUT by the Bank. If the credit transfer is authorised (AUTHORISED) or denied (ERROR) by the Bank or cancelled (AUTHORISINGPARTYABORTED) by the payer on the homebanking page, the status will be updated accordingly. When the payer does not reach or does not return from the page of the Bank, the status will remain PENDING on Setefi's systems, but Merchant will not receive any notification. Technical Documentation 32 January 2018

33 An automatic batch updates every 8 minutes, questioning MyBank services, the status of any pending payments. Update the status of pending payments is possible at any time through the service inquirymybank. Payment may assume the CANCELED status in the following scenarios: whether associating a final status to a payment is not possible (batch update, the Merchant will not receive any notification) whether the payer should leave the session before choosing the Bank (batch update, the Merchant will not receive any notification) whether the payer should click "Cancel Transaction" from the choose Bank page (The Merchant will receive appropriate notification) ERROR CASES Behaviour of the system in case of error in Initialisation phase When incorrect parameters are sent (e.g. unknown terminal, incorrect password, invalid amount, ) MonetaWeb responds with an error message in XML format. This message includes: - an error code - a mnemonic description of the error Example of error message in Initialisation phase: <error> <errorcode>xyz123</errorcode> <errormessage>invalid amount</errormessage> </error> Technical Documentation 33 January 2018

34 3.5. PayPal payment Paypal is a money transfer service born to achieve safer online transactions for both Debtors and sellers. It allows to send and receive money safely without providing the credit card numbers but only the address. By clicking on PayPal Guide you can download the guide containing the instructions for configuring the profile and publishing of payment button, preparatory activities for integration with MonetaWeb. For the PRODUCTION environment release, you must provide to E-Commerce. To trace back to your PayPal Merchant Account Code, while you are logged on to the PayPal web site, under the My Account tab, select the Profile menu. This should display a submenu with a choice My Personal Information. Select this option to see your Merchant Account Code. 1. The cardholder makes a purchase on the Merchant's site choosing PayPal as payment method; payment data are transmitted to the Merchant's server 2. The Merchant's server initialises the payment with an HTTP Post message 3. MonetaWeb initialises the payment to PayPal 4. PayPal returns a session tocken 5. MonetaWeb returns to the Merchant the PaymentID, the security token and the URL for holder redirection 6. The Merchant's server redirects the cardholder to the PayPal login page 7. The cardholder enters his/her PayPal credentials, chooses the payment instrument and the shipping address and authorises the payment. 8. PayPal returns the user's session to MonetaWeb 9. MonetaWeb sends a payment request to PayPal Technical Documentation 34 January 2018

35 10. PayPal processes the payment and returns an outcome to MonetaWeb 11. MonetaWeb sends the payment outcome in server to server mode to the Merchant's ResponseURL 12. The Merchant responds to MonetaWeb by sending the ResultURL 13. MonetaWeb redirects the cardholder to the ResultURL to display the final outcome. PAYMENT INITIALISATION The first phase of the payment consists in transmitting the preliminary payment data to MonetaWeb, such as amount, currency, order reference and url to continue the payment. After receiving these data, MonetaWeb returns in output in XML format, a unique PaymentId, a security token, and the page url to which the holder must be redirected Example of HTTP Payment Initialisation message: id= &password= &operationtype=initializepaypal&amount=1.00&responsetome rchanturl= recoveryurl= n& cardholdername=namesurname&cardholder =nome@dominio.com& customfield=customfield Call parameters of HTTP payment message for Payment Initialisation: Name Description Type Length id id associated with terminal char 8 password Terminal id password varchar 50 operationtype 'initializepaypal' varchar 50 amount ResponseToMerchantUrl recoveryurl merchantorderid Transaction amount using the point as decimal separator (e.g. 1428,76 = " "). The decimal portion may vary depending on the currency. Url to which the transaction outcome must be notified Url to which the holder must be redirected if you cannot obtain a resulturl in notification phase (optional) Transaction reference (can contain only letters and numbers and must be absolutely unique) decimal 18.4 varchar 2048 varchar 2048 varchar 18 description Payment description (optional) varchar 255 cardholdername Cardholder name (optional) varchar 125 Technical Documentation 35 January 2018

36 cardholder Cardholder's address to which the payment outcome must be notified (optional) varchar 125 customfield Custom field (optional) varchar 255 shippingname * shippingstreet * shippingcity * shippingstate * shippingzip * shippingcountry * shippingphone * Name of the person associated with the address (recommended for shipping case) Shipping address (recommended for shipping case) Name of the town (recommended for shipping case) Name of the State or province (recommended for shipping case) Name of the postal (ZIP) code of the shipping country (recommended in the United States and in the countries where it is required, for shipping case) Code of the shipping country, e.g. IT, NL, ES (recommended for shipping case) Telephone number (recommended for shipping case) varchar 32 varchar 100 varchar 40 varchar 40 varchar 20 varchar 2 varchar 20 * The shipping address fields may enable the seller protection provided by PayPal. For further information please contact directly PayPal's references. Example of XML message for Payment Initialisation response: <response> <paymentid> </paymentid> <hostedpageurl> <securitytoken>07dc08f9bde84c7aa0481d8e604c91e9</securitytoken> </response> Parameters of response to Payment Initialisation message: Name Description Type Length paymentid Id associated to the payment session varchar 18 securitytoken Security token varchar 32 hostedpageurl Payment page url to which the cardholder is directed varchar 255 Cardholder redirection to PayPal page: After receiving an initialisation message response, the web session of the cardholder must be redirected to the url specified in the hostedpageurl tag to which the paymentid parameter must be Technical Documentation 36 January 2018

37 appended. This url must be set as fixed parameter for redirection. However, for every payment, it must be retrieved dynamically from the appropriate tag PAYMENT OUTCOME NOTIFICATION Based on the choices made by the holder, through the account, PayPal processes the payment and communicates its outcome to MonetaWeb; the Merchant then receives a notification via HTTP post in NVP (NameValue Pair) format on the url indicated in the responsetomerchanturl parameter. The securitytoken is, among the various passed-in-post parameters, a security quantity generated by MonetaWeb and notified to the Merchant both upon initialisation response, and upon outcome notification; for security purposes, it is recommended to make sure that the value of the securitytoken received corresponds with anything received during initialisation. In order to redirect the web session of the cardholder to a new page containing the transaction outcome, the Merchant must reply to the notification message, which was newly received from MonetaWeb with the url of its outcome page hanging the 'paymentid' up as parameter. This url may be enriched with parameters to be able to display the outcome correctly. Upon notice of a hosted payment to the merchant URL response, once the connection has started, our services wait for 20 seconds to receive the final URL for the redirection. At the end of the timeout, the socket is closed. Should the notification of the url for holder redirection fail (unavailability of the responsetomerchanturl page, invalid content of the ToMerchantUrl response page and response timeout) MonetaWeb will redirect the holder to the recoveryurl page, which is notified by the Merchant through the appropriate parameter of the Initialisation message. If the recoveryurl parameter was not filled in in, MonetaWeb will redirect the holder to a courtesy page, published directly on MonetaWeb server. Technical Documentation 37 January 2018

38 MonetaWeb courtesy page will appear as shown below: Example of payment outcome message: Message sent to merchant at url [ with data: {authorizationcode=, cardcountry=, cardexpirydate=, cardtype=paypal, customfield=some custom field, maskedpan=, merchantorderid=2011ivr anti, paymentid= , responsecode=000, result=approved, rrn=, securitytoken=07dc08f9bde84c7aa0481d8e604c91e9, threedsecure=n} Technical Documentation 38 January 2018

39 Parameters of HTTP message for payment outcome notification: paymentid result Name Description Type Length responsecode merchantorderid cardtype Unique identifier of the order generated by MonetaWeb that corresponds to the same field received in response during the Initialisation phase Transaction outcome: - APPROVED, transaction authorised - CAPTURED, transaction confirmed - PENDING, transaction suspended pending verification (For current updates see PayPal backoffice) Response code (e.g. 000 if the transaction is authorised, in all other cases the transaction is rejected) Transaction Reference sent to the Merchant in Initialisation phase (can contain only letters and numbers and must be absolutely unique) Circuit and type of credit card used (upon request) - ['Amex', 'Diners', 'Maestro', 'Mastercard', 'Moneta', 'Visa', 'BAPAYPAL', 'PAYPAL'] varchar 18 varchar 20 char 3 varchar 18 varchar 10 cardcountry Nationality of the used credit card varchar 255 cardexpirydate customfield Expiration date of the used credit card (in the format mmaa) Custom field sent to the Merchant in Initialisation phase varchar 4 varchar 255 securitytoken Security token varchar 32 ERROR CASES Initialisation phase When incorrect parameters are sent (e.g. unknown terminal, incorrect password, invalid amount, ) MonetaWeb responds with an error message in XML format. This message includes: - an error code - a mnemonic description of the error Example of error message in Initialisation phase: <error> <errorcode>xyz123</errorcode> <errormessage>invalid amount</errormessage> </error> Technical Documentation 39 January 2018

40 Notification phase When the transaction is not approved by the PayPal system, MonetaWeb notifies the Merchant an error message in NVP format. This message includes: - an error code - a mnemonic description of the error - a payment id Example of error message in Notification phase: errorcode=pp10001, errormessage=paypal error [10417]: Instruct the customer to retry the transaction using an alternative payment method from the customers PayPal wallet. The transaction did not complete with the customers selected payment method., paymentid= Technical Documentation 40 January 2018

41 3.6. MasterPass payments Masterpass is the interoperable solution for online shopping offered by MasterCard that allows a easy, fast and secure way to shop on internet. Through the masterpass the Merchant will have access to the wallets exposed by major banking institutions. 1. The cardholder makes a purchase on the Merchant's site choosing MasterPass as payment method; payment data are transmitted to the Merchant's server 2. The Merchant's server initialises the payment with an HTTP Post message 3. MonetaWeb initialises the payment to MasterPass 4. MasterPass returns a session tocken 5. MonetaWeb returns to the Merchant the PaymentID, the security token and the URL for cardholder redirection 6. The Merchant's server redirects the cardholder to the MasterPass' login page 7. The cardholder enters his/her MasterPass credentials, chooses the payment instrument and the shipping address and confirm the checkout. 8. MasterPass returns cardholder's session to MonetaWeb 9. MonetaWeb requestes checkout data to MasterPass 10. MasterPass returns checkout data 11. MonetaWeb gets card, shipping and billing data from MasterPass and processes the payment 12. MonetaWeb sends the payment outcome in server to server mode to the Merchant's ResponseURL 13. The Merchant responds to MonetaWeb by sending the ResultURL 14. MonetaWeb redirects the cardholder to the ResultURL to display the final outcome. Technical Documentation 41 January 2018