Guide Setup sign-on pop-up for Automatic Card Payment Service via Betalingsservice

Transcription

1 Guide Setup sign-on pop-up for Automatic Card Payment Service via Betalingsservice Version 4.4 with payment method Nets A/S Lautrupbjerg Ballerup DK T F

2 Contents Contents Introduction Definitions, acronyms and abbreviations Sign on pop-up solution overview Callback and redirects Interface descriptions Pre-requisites Creditor s portal backend call to ticket web-service The ticket service Creditor s portal call to ACP pop-up Callback Return URL Integration setup Basic integration setup Integration setup with Redirect feature Examples Example 1: Only mandate registration Example 2: Mandate registration with first-time payment, callback and redirect Example 3: Cancelling or updating card mandates Test environment Appendix I. Ticket/generate web-service call implementation example in Java Appendix II. Ticket/generate web-service call implementation example in PHP Appendix III Examples of ACP pop up windows

3 1 Introduction The Automatic Card Payment via Betalingsservice (ACP) offers the possibility for a company s customers to register both credit card and account number to be used for recurrent payments of their services. The card and mandate registration process is performed in a web application hosted by Nets. To do this, the call to a (ACP) registration page should be properly embedded into the company s web portal or web application. Additionally a call should be made to the (ACP) backend system. This guide is intended for developers and other technical specialists who are responsible for embedding (ACP) service into another solution. It is assumed the person has knowledge of HTML markup, JavaScript and web application development (PHP, ASP.NET, Java/JSP or any other). Besides this document we recommend reading the more general document about the sign on process, requirements and the look of the pop-up. Click on nets.eu 1 to go to this document. 1 See under nets.eu -> Produkter og løsninger -> automatiske betalinger -> Automatisk kortbetaling via Betalingsservice -> vejledninger -> opsætning af tilmeldingslink ). 3

4 2 Definitions, acronyms and abbreviations Definitions: Creditor (also called company ) Vendor of the services or products. Debtor (also called customer ) Consumer of the services or products. Card mandate is the agreement between creditor and debtor without customer entering credit card details for each payment. Pbs, Debgr (PBS number, debtor group number) Identification of creditors within Nets. CustomerNo (customer number) creditor s identification of debtor acronyms: CREDITOR_WEB_SITE base path in creditor portal where special pages for (ACP) integration (return page etc.) are hosted. Example: Abbreviations: HTML Hyper Text Markup Language HTTP Hyper Text Transfer Protocol URL Universal Resource Locator ASP Active Server Pages JSP Java Server Pages 4

5 3 Sign on pop-up solution overview Integrating the company s portal and (ACP) pop-up consists of three major tasks: 1. Adding HTML and JavaScript snippets into an existing page. 2. Implementation of secure information transfer from backend through the web service. 3. Implementation of REST-service setup to get status of mandate registration see REST-service setup guide The JavaScript snippet s code is activated by clicking on a button/link, when the customer decides to register his/her card and account number for recurrent payments via (ACP). The ACP registration page should normally be opened in a pop-up window (JavaScript snippet is used to force this). For security purposes all information required for registration should be passed to an ACP via a POST request to a web service, which returns a unique identifier of the registration session (a ticket). This is used to make sure that all sensitive data will be securely transferred to ACP. The ticketid is returned in the embedded HTM/JS to the customer. The ACP registration page is opened with a HTTP POST or GET request with the ticketid as a parameter and is provided by Nets. Figure 1 Sign on flow 5

6 4 Callback and redirects When the customer has completed the registration there are two additional features supported that can be used to provide feedback: - Callback from ACP o When the ticket service is being called a URL for callback may be passed along with other parameters. This callback URL is called when the registration is completed or an error has occurred. The callback URL is used as is and no additional information is added to it. In order to retrieve the registration status, a call should be done by using the Card Mandate Status web-service and\or 1 st time payment status webservice using debtor number and other required information (see Guide for REST based web-services). - Redirects from the popup o If redirect-url parameters are passed to the ticket, the customers browser will be automatically redirected to that URL in case of an unsuccessful/successful registration. Based on which features you would like to use in integrating with the ACP registration popup, there will be some additional setup, either: 1. Basic setup, which enables basic use-case (also sufficient for having callback to webservice). 2. Setup for redirect-on-success functionality. Integration setup should be adjusted considering which mode is to be used. The variants of setup are described in details in chapter 6 Integration setup. 5 Interface descriptions This chapter describes expected URL formats, parameters that should be passed to or properly received from the (ACP). 5.1 Pre-requisites The necessary FOCES certificates have been set-up at the creditor s site to access the URL s. See guide for FOCES certificates. 5.2 Creditor s portal backend call to ticket web-service Call web-service URL in order to create registration session in the Production environment: (see Section 8 Test environment for Test URL) HTTP POST request should be used. This Content-Type setting should be set for the request: Content-Type:application/x-www-form-urlencoded 6

7 The URL should also be provided with parameters, containing information about creditor, product/service, debtor and first-time payment if applicable, see table 1 for parameters. Table 1. Web-service parameters Parameter Data type Required Format Description No 1 st time payment Mandatory 1 st time payment Cancel/Update of Card Mandate pbs Number 1 8 digits PBS number of creditor Yes Yes Yes debgr Number 1 5 digits Debtor group number Yes Yes Yes customerno Text 1 15 chars Regex: ^[ÆØÅA-Z0-9]{1,15$ If customer number contains lowercase chars, these will automatically be converted to uppercase. No* No* Yes Cpr Number 10 or 8 digits CPR or CVR Number for debtor (if No No No known) customername Text 1-35 chars Debtor name No* No* Yes creditorreference Text 1-30 chars Reference for first-time payment N/A Yes N/A onetimeamount Number Integer (max 17 digits) recurrentamount Number Integer (max 17 digits) productdescription Text Free text up to 200 chars paymenttype Text AUTH or SALE paymentmethods Text OCA, WBS or OCA,WBS Amount of first-time payment in cents N/A Yes N/A Amount or recurrent payment in cents Description of product or service provided by creditor to debtor Indicates whether payment amount should be withdrawn (SALE 2 ) or reserved (AUTH 3 ). Indicates whether payment method should be OCA = Only Card, WBS = Card with BS or OCA,WBS = User should choose. No No N/A No Yes N/A N/A Yes N/A Yes Yes N/A regno Number 4 digits Bank registration number for debtor No No No accountno Number 6-10 digits Account number for debtor No No No lockaccregno Text true or false true Debtor cannot change regno and accountno false - Debtor can change regno and accountno callbackurl Text (URL) not validated If specified called in case if registration is successful or failed. returnurl Text (URL) not validated The browser returns to this url when the mandate has completed his mandate creation, canceled during the creation or cancelled a mandate. This is the url which should hold do the redirect as per section Integration setup with Redirect feature successredirecturl Text (URL) not validated URL, where the debtor s browser should redirect to when the sign up is complete. failureredirecturl Text (URL) not validated URL, where the debtors browser should navigate to if he cancels entering card information or an error occurs while entering. No No No No No No No No No No No No No No No 2 SALE correspond to 1st time payment without authorization where the card payment is done right away together with the debtors enrolment 3 AUTH correspond to 1st time payment with authorization/reservation of the amount on the debtors account until the product is actually send from creditor 7

8 To illustrate that the ACP registration pop-up can be called in tree modes, the Required column in the table above is split into tree columns: 1. General registration (with no 1 st time payment). 2. Registration with 1 st time payment. 3. Cancel/update of existing Card Mandate Parameters in table 1that are marked as No* are not required if the following conditions are satisfied: - customerno is optional if creditor allows temporary customer number to be generated by Nets. - customername is optional if customerno is not being sent. Note: Please note that callbackurl, returnurl, successredirecturl and failureredirecturl are not validated in ACP, but needs to include http protocol (example: ). They are expected to be valid and used as is. If an invalid URL is passed it won t have a negative impact on the registration pop-up, though data in creditor s system can get out of sync because the callback is not performed successfully. 5.3 The ticket service The web-service responds with a ticketid (JSON object) if the registration of data is successful. The ticketid is to be used as parameter for the pop-up URL. If data is missing or has a wrong format an error object that gives the list of rejected parameters in description is returned. Success response example: { "ticketid" : "d3d8fc6136a cf4c8b8474f5e5" Error response with validations { "code" : -1, "description" : "cpr:not valid;customername:not valid;customerno:not valid;" 5.4 Creditor s portal call to ACP pop-up The page URL to be called in order to open (ACP) pop-up in the Production environment is: (see section 8 Test environment for Test URL) Either HTTP GET or POST request may be used. TicketId is the only parameter, which should have the value returned by ACP ticket webservice. Example with GET: GET: 8

9 Example with POST: POST: ticketid=d3d8fc6136a cf4c8b8474f5e5 5.5 Callback The callback URL is always called with HTTP GET. The callback URL is used as it was provided and no additional information will be added to it by ACP. In order to retrieve registration status another call should be done to ACP by using the web-service Card Mandate Status and\or 1 st time payment status using debtor number and other required information as input parameters in the web-service call. 5.6 Return URL The page on the return URL in its simplest implementation is a HTML document without any visual appearance which intended to receive the redirect URL for a successful or failed registration. The return page should properly receive and handle following parameters: Parameter receipturl redirecturl Data type Text (URL) Text (URL) Description If specified called from (ACP) registration pop-up after the registration including card payment or reservation was successful. URL, where page in debtor s browser from which (ACP) pop-up has been opened should be navigated to. Please see detailed description of return page logic in section 6.2 Integration setup with Redirect feature. 6 Integration setup 6.1 Basic integration setup This type of setup is sufficient to use all the abilities of ACP pop-up except redirect in browser. To integrate the call to ACP registration pop-up some HTML and JavaScript must be added into a web-page that is accessible to creditor. The JavaScript code opens a pop-up window and triggers the creditor s backend application to send data to ACP web-service and get a ticketid. Here is an example: <form id="startbsexpform" method="post" name="startbsexpform" target="betalingservice" action="creditor_web_site/get-bsexpress-ticket.action">... HTML fields (if any applicable)... </form> <script language="javascript"> function openinpopup(formref, popw, poph) { window.name = 'DebtorPage'; 9

10 newwin = window.open('', 'BetalingService', 'resizable = 1,width=' + popw + ',height=' + poph); formref.submit(); newwin.focus(); </script> It is highly recommended that the web-page, where ACP registration pop-up is included, is only accessible for authenticated debtors. Control element for debtor is implemented as: <input type="button" onclick="openinpopup(document.startbsexpform, 800, 800);" value= Automatisk kortbetaling /> Or <a href="#" onclick="openinpopup(document.startbsexpform, 800, 800);">Automatisk kortbetaling</a> The handler for this response (mentioned get-bsexpress-ticket.action ) should make a request to ACP ticket web-service, obtain ticketid and redirect pop-up to the ACP registration page. Pseudo code below shows the common logic of web-service call implementation: Call With(pbs, debgr, [and other parameters, see Table 1. Web-service parameters]) Read JSON response If JSON response contains ticketid Redirect debtor to: With query parameters (ticketid=json_response.ticketid) Else Log JSON response Show error to debtor Example of the first ACP pop up window that debtor will be redirected to: See appendixes for examples of implementation: Appendix I for Java implementation. Appendix II for PHP implementation. 10

11 6.2 Integration setup with Redirect feature Redirect-on-success functionality provides ability to redirect the page in debtor s browser from which ACP pop-up has been opened to another URL. Do the following to enable this feature: 1. Basic setup should be completed. a. Generate ticket b. Forward debtor 2. A return page should be created and hosted on creditor s site. 3. Two parameters should be passed to the ACP ticket web-service: Return URL for end of registration Redirect URL for failure. (see more details about the ticket service in chapter 5.2). Note: The need for a special return page is dictated by cross-domain security, which does not allow updating one browser window from the JavaScript running in another window if these windows contain HTML documents from different domain. The intention is to redirect to a temporary pop-up window on a page hosted on creditor side, execute JavaScript snippet against the redirecturl parameter value and navigate back to the ACP registration receipt page. The return page is a simple webpage that automatically does following: 1. Transfers all the input HTTP parameters into the HTML form. 2. Updates and opens the browser window with redirect URL. 3. Automatically submits form back to ACP. Item1.: Any programming language\framework that allows to inject pieces of code into HTML markup, can be used (PHP, ASP.NET, Java/JSP etc.). Item 2. and 3.: JavaScript must be enabled on debtor s computer. Here is an example of a return page: <html xmlns=" <body onload="updateopenerandreturntobsexp();"> <form method="get" name="returntobsexpform" action="$request.receipturl"> </form> <input type="hidden" name="redirecturl" value="$request.redirecturl" /> <script language="javascript"> function updateopenerandreturntobsexp(){ var redirecturl = ""+document.getelementsbyname('redirecturl')[0].value; if(redirecturl.length > 0){ window.opener.location.href = redirecturl; document.returntobsexpform.submit(); </script> </body> </html> The $REQUEST entity in code is a pseudo-entity and should be replaced in accordance to the programming language supported by creditor s web-server. For example in PHP it should be: <?php echo(htmlspecialchars($_request["redirecturl"]));?> 11

12 7 Examples 7.1 Example 1: Only mandate registration Assumptions: Creditor would like to give debtors the opportunity to register card mandates for automatic payments. Debtors sign up for card mandate registration without first-time payment. Callback and redirect functionality is not used. In this example the creditor uses PHP for debtor s portal. Step 1. Create backend implementation of ACP ticket/register web-service call. The following parameters must be filled out (see Table 1. Web-service parameters for explanation): pbs debgr (customername/customerno) Host it at CREDITOR_WEB_SITE/get-bsexpress-ticket.action. When ticket is retrieved successfully debtor should be redirected to: with ticketid as parameter, i.e.: GET /mandate/choose-mandate-operation.action?ticketid=hg5345jgh34534jh5g See chapter 10 Appendix II. Ticket/generate web-service call implementation example in PHP Appendix for implementation example. The example is built with HTTP POST parameters. Step 2. Prepare the pop-up form opening and add it to the portal page which is available to debtor. Any HTML inputs can be added, but be careful not to expose sensitive information in the web-page without extreme necessity. <form id="startbsexpform" method="get" name="startbsexpform" target="betalingservice" action="creditor_web_site/bsexpress/get-bsexpress-ticket.action">... HTML fields (if any applicable)... </form> <script language="javascript"> function openinpopup(formref, popw, poph) { window.name = 'DebtorPage'; newwin = window.open('', 'BetalingService', 'resizable = 1,width=' + popw + ',height=' + poph); formref.submit(); newwin.focus(); </script> Step 3. Prepare control (e.g. a button) that will launch the pop-up and add it to the same page. <input type="button" onclick="openinpopup(document.startbsexpform, 800, 800);" value= Automatisk kortbetaling /> 12

13 7.2 Example 2: Mandate registration with first-time payment, callback and redirect Assumptions: Creditor offers debtors the opportunity to register mandates for recurrent payments. It is required that the debtor makes a card payment as part of the registration. A callback web-service is set up at and creditor would like to receive a status of registrations and payments to this web-service. After successful registration debtor should be redirected to Thank-you page ( It is assumed for this example that JSP technology is uses for debtor s portal. Step 1. Create backend implementation of ACP ticket/register web-service call. The following parameters must be filled out (see Table 1. Web-service parameters for explanation): pbs debgr customerno customername creditorreference onetimeamount productdescription paymenttype paymentmethods returnurl callbackurl successredirecturl failureredirecturl Host it at When ticket is retrieved successfully debtor will be redirected to: with ticketid as parameter, i.e.: GET /mandate/choose-mandate-operation.action?ticketid=hg5345jgh34534jh5g See Appendix I. Ticket/generate web-service call implementation example in Java for implementation example. The example is built with HTTP POST parameters. Step 2. Prepare the pop-up form opening and add it to the portal page that is available to debtor. Any HTML inputs can be added into the form, but be careful not to expose sensitive information in the web-page without extreme necessity. <form id="startbsexpform" method="get" name="startbsexpform" onsubmit="openinpopup(this, 800, 800);return false;" target="betalingservice" action=" ">... HTML fields (if any applicable)... </form> <script language="javascript"> function openinpopup(formref, popw, poph) { window.name = 'DebtorPage'; newwin = window.open('', 'BetalingService', 'resizable = 1,width=' + popw + ',height=' + poph); formref.submit(); newwin.focus(); </script> 13

14 Step 3. Prepare control (e.g. a button) that will launch the pop-up and add it to the same page. <input type="button" onclick="openinpopup(document.startbsexpform, 800, 800);">Automatisk kortbetaling</input> Step 4. Prepare the call back service to call the first time transaction status rest service, to get status if the mandate was created successfully (see rest service documentation). Then make necessary registrations to creditor database. Step 5. Prepare the return page (in JSP) and host it at address <?xml version="1.0" encoding="utf-8"?> <%@ page language="java" contenttype="text/html; charset=utf-8" pageencoding="utf-8"%> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " transitional.dtd"> <html xmlns=" <body onload="updateopenerandreturntobsexp();"> <form method="get" name="returntobsexpform" action="${param.receipturl"> </form> <input type="hidden" name="result" value="${param.result" /> <input type="hidden" name="redirecturl" value="${param.redirecturl" /> <script language="javascript"> function updateopenerandreturntobsexp(){ var redirecturl = ""+document.getelementsbyname('redirecturl')[0].value; if(redirecturl.length > 0){ window.opener.location.href = redirecturl; document.returntobsexpform.submit(); </script> </body> </html> 14

15 7.3 Example 3: Cancelling or updating card mandates Assumptions: Debtor must be able to update card mandate with new card information or cancel the card mandate from creditors web-site. A link to the edit/cancel mandate pop up must be implemented at creditors web-page. Step 1. Create backend implementation of ACP ticket/register web-service call. The following parameters must be filled out (see Table 1. Web-service parameters for explanation): pbs debgr customerno callbackurl Host it at CREDITOR_WEB_SITE/get-bsexpress-ticket.action. When ticket is retrieved successfully debtor should be redirected to: with ticketid as parameter, i.e.: POST /mandate/choose-mandate-operation.action?ticketid=hg5345jgh34534jh5g See Appendix I. Ticket/generate web-service call implementation example in Java for implementation example. The example is built with HTTP POST parameters Step 2. Prepare the pop-up form (see step 2 in example 2). Step 3. Prepare control (e.g. a button) that will launch the pop-up and add it to the same page. <input type="button" onclick="openinpopup(document.startbsexpform, 800, 800);">Automatisk kortbetaling</input> Step 4. Prepare the call back service to call the card mandate status rest service, to get status if the mandate was cancelled successfully (see rest service documentation). Then make necessary registrations to creditor database. Step 5. Prepare the return page if necessary (see step 5 in example 2). See screenshots of cancellation at the end of appendix III. 8 Test environment ACP has a test environment on the domain bsekspress-test.nets.no That will change the ticket generation url to: and the popup URL to: 15

16 9 Appendix I. Ticket/generate web-service call implementation example in Java import java.io.bufferedwriter; import java.io.ioexception; import java.io.inputstream; import java.io.unsupportedencodingexception; import java.net.httpurlconnection; import java.net.url; import java.net.urlencoder; import java.util.hashmap; import java.util.map; import java.util.map.entry; import org.apache.commons.io.ioutils; import org.apache.commons.logging.log; import org.apache.commons.logging.logfactory; import org.json.jsonexception; import org.json.jsonobject; private static final Log LOG = LogFactory.getLog(SomeClass.class); /** * Calls BsExpress generate ticket web-service * ticketparams * map of parameters for web-service call (see Table 1 for * description) ticketid Exception */ public String getticketid(map<string, String> ticketparams) throws Exception { // urlencode and concatenate the POST arguments into // pbs=xxxx&debgr=yyyy&... String urlparameters = getquery(ticketparams); java.net.httpurlconnection connhttp = null; try { // Make a URL URL = new URL // Open connection connhttp = (HttpURLConnection) url.openconnection(); connhttp.setdooutput(true); connhttp.setdoinput(true); // Set method to POST connhttp.setrequestmethod("post"); connhttp.setrequestproperty("user-agent", "NETSBS/1.0"); // Content-Type MUST be application/x-www-form-urlencoded connhttp.setrequestproperty("content-type", "application/x-www-form-urlencoded"); connhttp.setrequestproperty("content-language", "en-us"); // Send parameters OutputStream os = connhttp.getoutputstream(); BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(os, "UTF-8")); writer.write(urlparameters); writer.flush(); writer.close(); os.close(); // Check HTTP response code LOG.info("Register ticket service responded with code: " + connhttp.getresponsecode()); catch (Exception e) { throw e; 16

17 // Read JSON response String callbackresponse = null; try (InputStream is = connhttp.getinputstream();) { callbackresponse = new String(IOUtils.toByteArray(is), "ISO "); // Log the response LOG.debug("Ticket registration service responded [" + callbackresponse + "]"); // Try to parse the response JSONObject json = new JSONObject(callbackResponse); // Check if ticketid was returned if (!json.has("ticketid")) { // If no ticket Id then it must be error throw new Exception(callbackResponse); return json.getstring("ticketid"); /** * Compiles list of entries to query string like pbs=xxxx&debgr=yyyy&... * (buildurlparameters(allrequestparams UnsupportedEncodingException */ private String getquery(map<string, String> postparams) throws UnsupportedEncodingException { StringBuilder result = new StringBuilder(); boolean first = true; for (String key : postparams.keyset()) { if(first) first = false; else result.append("&"); String value = postparams.get(key); result.append(urlencoder.encode(key, "UTF-8")); result.append("="); result.append(urlencoder.encode(value, "UTF-8")); return result.tostring(); 17

18 10 Appendix II. Ticket/generate web-service call implementation example in PHP <html xmlns=" <body> <?php // $allticketparams array should be prepopulated with necessary parameters for REST WS call // keys in this array should be the same as parameter names for ticket/generate web-service // (see Table 1 for description) $ticketid = registerticket($allticketparams); //ticketid generated - redirect with ticketid to BsExpress $redirecturl = ' header('location: '.$redirecturl); /** * Register and return ticket. * $allticketparams map/array with parameter names for ticket\generate as keys and their values */ function registerticket($ticketparams){ // Automatic card payment ticket web-service URL $request = $session = curl_init($request); // Tell curl to use HTTP POST curl_setopt ($session, CURLOPT_POST, true); // Tell curl that this is the body of the POST curl_setopt ($session, CURLOPT_POSTFIELDS, getquery($ticketparams)); // Tell curl not to return headers, but do return the response curl_setopt($session, CURLOPT_HEADER, false); curl_setopt($session, CURLOPT_RETURNTRANSFER, true); //get the response $responsetext = curl_exec($session); curl_close($session); //Decode JSON $response = json_decode($responsetext); //Check if ticketid is returned if(property_exists($response, "ticketid")){ //ticketid generated return $response->ticketid; else { //Something was wrong, log error echo("error occured:<br/>"); echo($response->description); /** * Makes query string with ticket parameters for POST call (like pbs=xxxx&debgr=yyyy&...) $requestparams array with request parameters string */ function getquery($requestparams){ $query=""; $i = 0; foreach($requestparams as $param=>$value){ if($i++>0){ $query.="&"; 18

19 $query.=$param; $query.="="; $query.=urlencode($value); return $query;?> </body> </html> 19

20 11 Appendix III Examples of ACP pop-up windows The first window in the flow when mandate option is both Card & BS The first window in the flow when mandate option is both Only Card The first window in the flow when mandate options is free choice 20

21 The second window in the flow when 1. Time payment is used The second window in the flow when WITHOUT 1. Time payment The receipt window when debtor has an active e-boks 21

22 The receipt window when debtor do not have an active e-boks First window when debtor want to cancel or update an existing card mandate Receipt window when debtor has made a cancellation of card mandate 22

23 Receipt window when debtor has updated card mandate 23