ideal Integrated PHP

Transcription

1 ideal Integrated PHP Shop Integration Guide composed by: version 1.7, Aug 2011 Copyright 2006, ABN AMRO Bank

2 Contents Contents Introduction Signup process ideal overview Integration modules Installation Prerequisites Global configuration Security configuration Transactions Directory request Transaction request Customer Redirect Status request Error handling APPENDIX A: Data catalogue Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 2 of 15

3 1 Introduction This document intends to help software developers integrate the ideal payment method into their PHP webshop(s). This document describes the ideal Integrated PHP integration method and offers installation instructions and example code. Before you start, please note the following: - This document is only applicable to ideal Integrated PHP. If you have signed up for ideal via a Payment Service Provider (PSP), no integration effort is necessary. Instructions for ideal Hosted, the less complex (and less flexible) integration method, can be downloaded from the ideal Dashboard. - Your public key needs to be uploaded twice: once on the integration platform and once on the production platform (see signup process in Chapter 2). You may use different certificates if you want. - The merchant has a 'collection duty' with respect to the status of every ideal transaction. See Chapter for more information. - Requirements regarding the presentation of ideal on your website can be found on - For questions or suggestions please contact ABN AMRO by using the service ticket functionality in the ideal Dashboard (menu item: Tickets ). Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 3 of 15

4 2 Signup process Table 1 describes the complete signup process for ideal. The process is illustrated in Figure 1. Figure 1: ABN AMRO ideal signup process Step Description Explanation 1 Registration username / password 2 address verification The merchant registers username, password and address at An activation link will be send to the address that was provided in step 1. The merchant verifies this address by clicking on the hyperlink in the e- mail. 3 Fill in ideal application The merchant logs on for the first time and completes the application for ideal by providing company details, contact details and the preferred integration Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 4 of 15

5 Step Description Explanation form method. 4 Verify application ABN AMRO Bank verifies the application of the merchant. 5 Send contract After positive verification ABN AMRO Bank sends out the contract to the merchant by Upload certificate and perform test transactions After receiving the contract by (Step 5), the merchant can immediately start with embedding ideal in the webshop. When ideal is integrated, the merchant has to perform 7 mandatory test transactions. Please note the following in order to be able to complete these tests: The merchant has to logon to the test environment, using the same logon credentials as the production environment. The test environment can be reached via - Here the merchant has to upload the self-generated public key that will be used to decrypt the electronic signatures in all outgoing messages. - Next, the merchant has to perform 7 mandatory test transactions: 1 directory request and 6 ideal transactions (all sent to the test environment URLs, see APPENDIX A: Data catalogue). The results can be triggered by sending in different transaction amounts and have to be checked by the merchant: o Transaction with amount = 100: result Success o Transaction with amount = 200: result Cancelled o Transaction with amount = 300: result Expired o Transaction with amount = 400: result Open o Transaction with amount = 500: result Failure o Transaction with amount = 700: result SE2700 (Invalid electronic signature / Ongeldige digitale handtekening) - When these transactions are completed the results are transferred to (and can be found on) the production environment. The results are transferred 20 minutes after the last test transaction is successfully completed. N.B. Step 6.1 and 6.2 can be completed separately. 6.2 Sign and return contract (in twofold) to ABN AMRO Bank The merchant signs the contract returns it to the ideal service desk in twofold. Contact details of ABN AMRO Bank are provided in the that is sent to the merchant by in step 5. N.B. Step 6.1 and 6.2 can be completed separately. 7 Verify contract and test transactions 8 Upload certificate and activate ideal ABN AMRO Bank verifies the contract and test transactions and updates the signup status. The merchant logs on to the production environment to upload the self-generated public key and activate ideal. Table 1: ABN AMRO ideal signup process Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 5 of 15

6 3 ideal overview Consumers who already use an Internet banking product from a bank which offers ideal will in principle be able to make payments using ideal. The steps needed to complete a payment will be presented to the consumer in successive screens. For an online demo of ideal, please visit The ideal system is built up from bilateral relationships based on the 'four-party' model. Figure 2 shows the four parties in this model and their mutual primary relationships in the context of ideal: - Acquirer-Merchant: The merchant maintains an account with the acquirer. This account is used for crediting in ideal. The acquirer offers the merchant the possibility of accepting ideal payments from consumers. They exchange messages to this end. - Issuer-Acquirer: The issuer and acquirer have a banking relationship. They effect mutual transfers and process these in their accounting records. They exchange messages in the context of ideal. - Issuer-Consumer: The consumer maintains an account with the issuer. This account is used for the debiting in ideal. The issuer offers the consumer the possibility of making ideal payments to merchants based on the issuer s Internet banking product. - Consumer-Merchant: The consumer makes purchases from the merchant, who delivers these purchases after payment. Figure 2: 'Four parties model The ideal protocols comprise (request/response) XML messages and browser redirects which initiate and process a transaction in a particular sequence, with all parties involved being informed on the status of the transaction. This document describes three requests that are part of the ideal message protocols: - Directory request: The Directory request allows a merchant to fetch a list from his acquirer of issuers affiliated to the acquirer. This information can be used to compile an issuer list from which the consumer can select a bank. - Payment request: The Payment request enables a merchant to submit a transaction to his acquirer in order to have it approved at the consumer's issuing bank by the consumer who initiated the transaction. Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 6 of 15

7 - Status request: the Status request enables the merchant to retrieve the (guaranteed) status of a transaction from an issuer (via the acquirer). 3.1 Integration modules ABN AMRO Bank offers one integration module: ideal Integrated. When embedded in the webshop, ideal Integrated enables the merchant to (automatically) perform Directory Requests, Payment Requests and Status Requests. ideal Integrated is the most flexible solution, offering the complete transaction in the merchants own look&feel and the ability to automatically retrieve a guaranteed transaction status. ideal Integrated Payment process in webshop look&feel Automated retrieval of guaranteed transaction status Technical skills required Security PHP, Asp.NET or Java SHA1_RSA (OpenSSL required on webserver) Table 2: ABN AMRO integration module feature Figure 3: Functional overview of ideal Hosted and ideal Integrated. IDEAL Hosted is currently not available for new clients. Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 7 of 15

8 4 Installation This chapter describes all the steps necessary to install and configure ideal Integrated PHP (in this document also referred to as thinmpi). 4.1 Prerequisites - PHP capable web server like Apache or IIS - PHP Version OpenSSL-module Outgoing Internet access to connect to the acquirer on https-port 443 (SSL) - Public key of ABN AMRO Bank (included) - Your merchantid - Access permissions (at least reading permissions) for all files To install PHP and the OpenSSL-module for PHP see also and If you compile PHP yourself, the SSL library must be included. Please verify using phpinfo(). 4.2 Global configuration The parameters below needs to be set in the configuration file config.conf. It is recommended to rename this file (and related code) to config.conf.php for security purposes. See APPENDIX A: Data catalogue for a description of these parameters. Security related entries are explained in the following paragraph. - merchantid - merchantreturnurl - description - entrancecode The variables description and entrancecode are optional. It is recommended to set these variables dynamically. Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 8 of 15

9 4.3 Security configuration The following steps have to be completed, in order to create a private/public key: 1. Download the openssl library to your computer ( There are a number of binaries for different operating systems available (see for more info about the certificate request and the certificate generating utility). 2. Generate a RSA private key using a self-chosen password for [privatekeypass] (without the brackets): openssl genrsa -des3 out priv.pem -passout pass:[privatekeypass] Create a new Certificate based on this private key (using the same password): openssl req -x509 -new -key priv.pem -passin pass:[privatekeypass] -days out cert.cer 4. Copy the private key and the certificate file into the directory security\ 5. Edit the following entries in the configuration file config.conf, using the data from the steps 2 and 3 above (see also APPENDIX A: Data catalogue) - privatekey - privatekeypass - privatecert The public certificate entry certificate0 does not need to be modified. This entry holds the public certificate of the acquirer for message authentication and is included by default. If a new public certificate is received from the acquirer, a new entry needs to be added for this (and every next) certificate. To add a new acquirer public certificate, edit the configuration file config.conf and add the certificate as follows: certificate0=<filename of default certificate> certificate1=<filename of new certificate> etc. Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 9 of 15

10 5 Transactions This chapter describes the three ideal requests: - Directory request - Transaction request - Status request This chapter uses the example code to explain these three protocols. Each request is implemented in three separate example files: DirReq.php, TransReq.php and StatReq.php respectively. 5.1 Directory request The file DirReq.php shows a (very simple) webshop in which the user can select some products. By opening the file DirReq.php a Directory Request is automatically processed. This means that the most up-to-date list of ideal Issuers is requested from the acquirer. The select box below the orderform is populated with the results of the Directory Request. N.B. The directory request has to be executed only once a day. The following is done in DirReq.php to perform a Directory Request. 1. Create a DirectoryRequest object: $data = & new DirectoryRequest(); 2. Set parameters (obtain from the configuration file config.conf). 3. Create an instance of thinmpi: $rule = new thinmpi(); 4. Process the request using this instance: $result = $rule->processrequest($data); Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 10 of 15

11 Check the file DirReq.php to see how the result is handled to populate the select box 1. After the user clicks the Order-button the form is posted to the file TransReq.php. 5.2 Transaction request The file TransReq.php performs a Transaction Request based on the values it receives from DirReq.php. The process of performing a Transaction Request is very similar to performing a Directory Request: 1. Create Request object (AcquirerTrxRequest in this case) 2. Set parameters (obtain from the configuration file config.conf and from DirReq.php 2 ). 3. Create an instance of thinmpi 4. Process the request using this instance 5. Check and handle the result 5.3 Customer Redirect After the Transaction Request the customer is redirected to the issuer. The URL of the issuer is provided in the response of the Transaction Request. It can be retrieved from the result of ProcessRequest() with the function getissuerauthenticationurl(): //Get IssuerURL en decode it $ISSURL = $result->getissuerauthenticationurl(); $ISSURL = html_entity_decode($issurl); //Redirect the browser to the issuer URL header("location: $ISSURL"); exit(); 1 Please note that the demoshop performs a Directory Request every time a user accesses DirReq.php. This is not mandatory, because the list of ideal issuers does not change very often. It is also allowed to perform the directory request periodically and store the list on your system. 2 Please note that on the integration (test) environment the parameter amount determines the result of the transaction. Use amount=100 to simulate a successful transaction. See Chapter 2 (Step 6.1) for more information. Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 11 of 15

12 5.4 Status request After the transaction the customer is redirected back to the merchantreturnurl. To perform the mandatory (!) Status Request the steps below have to be completed. Read everything about the so-called collection duty in the next paragraph. 1. Create Request object (AcquirerStatusRequest in this case) 2. Set parameters (obtain from the configuration file config.conf and from TransReq.php). 3. Create instance of thinmpi 4. Process the request using this instance 5. Check and handle the result Collection duty The merchant has a 'collection duty' regarding the status of the transaction. By performing the Status request (and successfully receiving a status unequal to open, see 5.4.2), the merchant complies with this duty. Even if the customer is NOT redirected back to the merchantreturnurl (e.g. because the customer closes the browser window), the merchant must actively perform a Status Request. This can be done via the ideal Dashboard (Payments\Details\Status Request-button) or by performing a Status Request automatically when the time set by the parameter expirationperiod has expired. Especially for virtual content the latter is a necessity 3. N.B. The status request, to get the result of the transaction to see if a transaction has been completed successfully, has to be executed only for a limited number of times. One can start the status request approximately 3, 5 or 10 minutes after the consumer returned to the web shop. If the attempt failed a second status request shortly after the expiring time (keep always some seconds between the official communicated expiring time and the time to obtain the status response). In case there is still no response one can do the status request every hour. 3 Example: a merchant sells concert tickets and reserves these tickets for a period of 10 minutes. Within this period a consumer has to make the purchase. If not, the tickets are released for other consumers. Suppose a consumer wants to buy a concert ticket and selects ideal as his method of payment. The merchant has set the expirationperiod to PT5M, which gives the consumer 5 minutes to pay for the ticket. The consumer pays for the ticket within 3 minutes, but closes the browser window before being redirected to the merchantreturnurl. Because the consumer is not redirected back to the merchantreturnurl the Status Request will not be carried out. For this specific situation (virtual content; reservation system; unknown Transaction.status) it is very important to perform the Status Request right after the expirationperiod. Otherwise this ticket will be released for other consumers (after 10 minutes), despite the fact that the consumer did pay for it via ideal. Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 12 of 15

13 5.4.2 Transaction status The following values for Transaction.status are defined in the ideal standard: - Open: payment not yet completed, expirationperiod not expired; - Expired: payment not completed; expirationperiod expired; - Success: payment completed and guaranteed by bank of consumer; - Cancelled: payment cancelled by consumer; - Failure: payment not completed (e.g. because of insufficient balance). 5.5 Error handling When an Error Response is returned instead of a normal response the error is handled by the function isok(). By calling the function isok() on the result of ProcessRequest() you can check if an ErrorRes is received. If so, the function geterrormessage() returns a description of the error. For example (from DirReq.php): if(!$result->isok()) { $Msg = $result->geterrormessage(); print("$msg<br>"); } In the case of an error response, the merchant is obliged to communicate the value of the parameter consumermessage to the consumer (in the browser window). Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 13 of 15

14 APPENDIX A: Data catalogue Parameter Format Description issuerid PN..4 ID of the issuer that the user has selected merchantid PN..9 ID that identifies the merchant (you) subid N..max6 Set to 0 unless you have specific reasons not to authenticationtype AN..max40 Set to SHA1_RSA merchantreturnurl AN..max512 URL on the merchants system (your system) that the customer is redirected to after the payment. N.B. This page should perform the status request (!) purchaseid AN..max16 Order number from the merchant s system (your system) amount N..max12 Total amount for the order currency A..3 Set to EUR N.B. Please note that on the test environment the parameter amount determines the result of the transaction. See Chapter 2 for more information. expirationperiod RDT Timeframe during which the transaction is allowed to take place. Notation PnYnMnDTnHnMnS, where every n indicates the number of years, months, days, hours, minutes and seconds respectively. E.g. PT1H indicates an expiration period of 1 hour. PT3M30S indicates a period of 3 and a half minutes. Maximum allowed is PT1H; minimum allowed is PT1M. language CL..2 Set to nl unless you have specific reasons not to description AN..max32 Description of the order entrancecode ANS..max40 entrancecode is set by the merchant (e.g. order number or a session-code) and used as an 'authentication' to facilitate continuation of the session between merchant and consumer. It enables the merchant to recognize the consumer associated with a (completed) transaction. entrancecode is sent to the merchant in the HTTP(S) GET to the merchantreturnurl for this. acquirerurl n/a The URL where the Directory, Transaction and Status Requests have to be send to. Integration (test) environment: Production environment: Format AN ANS N PN Explanation Alphanumeric, free text Alphanumeric strict (only and abc..) Numeric Numerical (padded), the contents are extended to the maximum length by trailing zeros..23 Maximum amount of characters. CL RDT Code list Relative datetime field: PnYnMnDTnHnMnS Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 14 of 15

15 Security related parameters: Parameter Description privatekey n/a RSA private key generated by merchant (you) privatekeypass n/a Password used to generate Certificate based on privatekey privatecert n/a Certificate generated with privatekeypass and privatekey certificate0 n/a Default public certificate from acquirer (included). This key is used by the thinmpi to decrypt the response of the Status Request (containing the guaranteed status of a transaction). Copyright 2006, ABN AMRO Bank, version 1.7, Aug 2011 Page 15 of 15