Wirecard CEE Integration Documentation

Transcription

1 Wirecard CEE Integration Documentation () Created: :02 1/18

2 Wirecard Shop Plugin for Salesforce Commerce Cloud (Demandware) Installation guide for Wirecard Checkout Page This installation guide will show you the stepbystep installation of the plugin to your installed shop system on your web server. Please test your online shop and the configuration of the plugin on a test system, before you install the plugin on your production system. Prerequisites In order to integrate the Wirecard payment provider into your project make sure you have accomplished the following tasks: You have access to and finished the setup of your Wirecard account. For more information contact your Wirecard partner manager, sales representative or support. Your Wirecard account has been setup, and you have got your customer ID and preshared key (aka secret) to access it using the API. Step 1: Installing the Wirecard Integration Cartridge Please follow these initial steps to integrate the Wirecard integration cartridge to your project: 1. Please import the int_wirecard cartridge in your Salesforce Commerce Cloud (Demandware) UX Studio and assign it to your server project so that it is uploaded to the server. 2. Login to Business Manager. 3. Adjust the cartridge path: 1. Open Administration Sites Manage Sites and choose the site(s) in which you want to integrate the Wirecard payment service. 2. Change to the Settings tab and add the int_wirecard cartridge, separated by colon (:), into your cartridge path. 3. Go back to Administration Sites Manage Sites and choose the Business Manager site. 4. Add the int_wirecard cartridge, separated by colon (:), into your cartridge path. 2/18

3 4. Import the custom Site Preferences: 1. Switch to Site Development Import & Export 2. Upload file Wirecard_systemobjecttypeextensions.xml and import it afterwards. This file contains the necessary site preferences. 5. Create or import the Payment Processors: 1. Rename file Wirecard_paymentprocessors.xml to paymentprocessors.xml and add it into your site import package file or create a site import which just contains this file. Upload and import the site import file under Administration Site Development Site Import & Export. 2. Alternately, create the payment processors manually in your Site Ordering Payment Processors 1. Id: WIRECARD_CREDIT; Description: Wirecard credit card payment processor. 2. Id: WIRECARD_EPS; Description: Wirecard EPS Onlineueberweisung payment processor. 3. Id: WIRECARD_IDEAL; Description: Wirecard ideal payment processor. 4. Id: WIRECARD_PAYPAL; Description: Wirecard PayPal payment processor. 5. Id: WIRECARD_SOFORT; Description: Wirecard Sofort. payment processor. 6. Id: WIRECARD_SELECT; Description: Wirecard Select payment processor. 6. Import the Wirecard Payment Methods: 1. Select the site you want to integrate Wirecard, and go to Ordering Import & Export. 3/18

4 2. Upload file Wirecard_paymentmethods.xml and import it as Payment Methods. Therefore, go to Ordering Import & Export Payment Methods, click Import and follow the import steps. 7. Activate the Fatal Error notification (optional): 1. Navigate to Administration Operations Custom Log Settings. Enter a list of addresses in the Fatal Receive input field. Step 2: Specifying values for the site preferences In Business Manager open your site, navigate to Site Preferences Custom Site Preferences and choose the Wirecard preference group. This will open the preferences page where you see all required Site Preferences. Configure the settings as necessary: Wirecard Preferences Wirecard URL: Configuration value for the URL of the Wirecard server. The default value should already point to the correct server, but can be changed if necessary. Customer ID: Enter the Wirecard customer ID you receive only for the Production system. The default values are for the generic test environment. Secret String: Enter the Wirecard secret string / PreShared key you receive only for the Production system. The default values are for the generic test environment. Shop Id: Enter the value for the Shop ID, in order to indicate which premium templates should be loaded on their servers. You will receive this value from Wirecard. Success URL: Indicates the pipeline which is called as Wirecard Success URL. The default value is already configured with the correct URL. Cancel URL: Indicates the pipeline which is called as Wirecard Cancel URL. The default value is already configured with the correct URL. Failure URL: Indicates the pipeline which is called as Wirecard Failure URL. The default value is already configured with the correct URL. Confirm URL: Indicates the pipeline which is called as Wirecard Confirm URL. The default value is already configured with the correct URL. Pending URL: Indicates the pipeline which is called as Wirecard Pending URL. The default value is already configured with the correct URL. Service URL: Indicates the pipeline which is called as Wirecard Service URL. The default value is already configured with the correct URL. Note that the pipeline points to the default SG2 content page, and the ID of the content asset might be changed within the pipeline. Display Text: Resource Bundle Key for the display text displayed on the Wirecard templates. The resource bundle file is part of the plugin. Customer Statement: Resource Bundle Key for the Customer Statement Message. The resource bundle file is part of the plugin. Order Description: Resource Bundle Key for the Order Description text displayed in Wirecard CEE Payment Center. The resource bundle file is part of the plugin. Redirect Config: Controls if the Wirecard premium templates should be loaded in an iframe or within the browser window. Submit Order Number: Defines if the value for order number will be submitted to Wirecard or not. Duplicate Request Check: Defines if the Duplicate Request Check should be performed or not. 4/18

5 The following parameters are used as constants for the plugin, so please do not change the values of these parameters: Trim Response Parameters: Defines if the response parameters are trimmed by Wirecard for the fingerprint calculation. Default is true. Please note that this parameter is not implemented by Wirecard yet. Response parameter values are always trimmed by Salesforce Commerce Cloud (Demandware), and the value should always be set to true. Shop Name: Shop name of identify the plugin at Wirecard. Default is Salesforce Commerce Cloud and should not be changed. Shop Version: Shop name of identify the plugin at Wirecard. Default is and might be changed per year. Plugin Name: The internal Wirecard name of the plugin. There is no need to change the default value. Plugin Version: The internal Wirecard version of the plugin. There is no need to change the default value. Please make sure you have completed all settings for Sandboxes/Development, Staging and Production systems as necessary. Step 3: Setting up and defining the payment methods You can also control some preferences for the Wirecard payment methods. Therefore, please select your site and navigate to Ordering Payment Methods. Within the list you find the following new payment methods: WIRECARD_EPS_ONLINE_TRANSFER: EPS Onlineüberweisung (mainly used for Austria) WIRECARD_IDEAL: ideal (mainly used for the Netherlands) WIRECARD_SOFORT_UEBERWEISUNG: Sofort. (mainly used for Germany) 5/18

6 WIRECARD_CREDIT_CARD: Credit Card WIRECARD_PAYPAL: PayPal WIRECARD_SELECT: When using this payment method in the shop, the consumer selects the payment method in the Wirecard Checkout Page. This has the advantage that you can use any payment method Wirecard is supporting without modifying the source code of your plugin or your online shop. Please contact our support teams to enable additional payment methods. All payment methods are enabled by default, and should be disabled and sorted according to your needs. You need to deactivate the Salesforce Commerce Cloud (Demandware) standard payment methods for CREDIT_CARD and PayPal. The following custom attributes can be controlled for each payment method: Wirecard Payment Type: The payment method string which is sent to Wirecard in the interface. The values are already configured for each payment method. Wirecard Auto Deposit: Enables the autodeposit option for Wirecard. It defines if a payment should be directly approved (authorized) and deposited (captured) in one single step. If set to false, the transaction will only be approved. This value is mainly used for Credit Card and PayPal transactions. Wirecard Maximum Retries: Defines the number of maximum payment retries at Wirecard. If no value is defined, it won t be submitted to Wirecard and a default parameter is used there. Submit Shipping Data to Wirecard: Defines if the shipping address data are sent to Wirecard with the initial request. This value is only used for PayPal and has to be activated for this payment method. Submit Billing Data to Wirecard: Defines if the billing address data are sent to Wirecard with the initial request. This value is only used for PayPal and has to be activated for this payment method. Wirecard Update Shipping Data: Defines if the shipping address, which is returned by Wirecard, should overwrite the existing shipping address at the order. This value is only used for PayPal. 6/18

7 Step 4: Frontend changes and adjustments Depending on your checkout process, you need at least to overwrite and design the following templates: checkout/billing/paymentmethods.isml: This template lists the payment methods and fields in Site Genesis. The integration cartridge comes with an adjusted template which can be used in your storefront cartridge. It basically removes the standard credit card fields, and implements the logic to show only the Select payment method if it is activated. Styles should be moved to your project specific CSS file. checkout/billing/wirecarderrormessage.isml: This template renders the error messages which are shown on the billing/payment page when Wirecard returns with a failure or the cancelurl. The template can be included at the top of standard template checkout/billing/billing.isml. 7/18

8 checkout/confirmation/wirecardpendingpayment.isml: This template renders an error/warning message which is shown on the order confirmation page when Wirecard returns with a Pending payment code. The template should be included at the top of the standard template checkout/confirmation/confirmation.isml. All Wirecardrelated wording and error messages are stored within the integration cartridge in templates/default/resources/wirecard.properties, and can be changed according to your needs. Default messages are delivered in English and German. For the texts which are sent to Wirecard (displaytext, customerstatement, orderdescription), the order number can be used as a placeholder within the message. Example: Step 5: Necessary SG Controller Changes A small change is necessary in the standard COPlaceOrder controller to ensure that the handlepayment function correctly redirects to Wirecard. Therefore, the Handle hook returns a new 8/18

9 result redirected which the calling controller COPlaceOrder needs to evaluate correctly. The following changes have been made: COPlaceOrder.handlePayments(): Return with redirected: true See lines 67ff in the screenshot below. COPlaceOrder.start(): Add logic to return in function start(). See line 163ff in the screenshot below: Furthermore, in order to ensure that the Wirecard redirect is tracked in Saleforce Commerce Cloud Analytics, you need to add a statement to controller COPlaceOrderStart. The UUID of the basket needs to be mapped to a request custom parameter OriginalBasketUUID. The parameter is used in template wirecard/wirecardforward.isml to call the reporting hook. Changes to the number of the checkout step etc. need to be implemented in the project. 9/18

10 Main Scripts WirecardManager: Main manager to handle the logic which is necessary for the integration. This is encapsulated in the following main functions: getwirecardcallparameters(): Collects all required parameters to call Wirecard. setwirecardpaymentparameters(): Sets all response parameters to the order and payment transaction depending on used the payment method. validatewirecardamountandfingerprint(): Checks the Wirecard amount against the shop order amount and checks the fingerprint. setorderpaymentstatus(): Sets the order payment status to PAID only if the payment status is SUCCESS and the confirmation url was called. checkandrestorebasket(): Checs if the basket has been restored when the order was set to failed, so after either the Cancel or Failure URL was called. Therefore, it is checked if the basket contains any line items (products or gift certificates). If a timeout is detected, it restores the basket and copies all line items, the billing and shipping address as well as the shipping method from the previously created order to the basket. Any copying of projectrelated custom attributes need to be added to this script. WirecardLogger: Implements the custom logging for the cartridge. Step 6: Script adjustments When the cancelurl, failureurl or serviceurl are called, the logic automatically detects a session timeout. Then, the basket will be restored from the previously created order using script wirecard/restorebasket.ds. You need to add the logic to copy any custom attribute from the order to the basket within this script. There are comments in the script for each business object which might be affected (shipping method, shipment, line item, shipping address and billing address). Step 7: Testing the Wirecard integration Once you completed the setup of the cartridge the integration needs to be tested against the Wirecard test system. The connection settings are already preconfigured in the custom site preferences. All payment authorization processes, checks and forms are implemented on the Wirecard servers. When Wirecard responds with the successurl or confirmurl, all attributes are stored at the order and payment transaction if submitted and present in the response (see the list below). The values can 10/18

11 be reviewed in Business Manager Select a Site Ordering Search and select an Order Tabs: Attributes and Payment. Order attributes Wirecard Order No: The internal order number or transaction returned by Wirecard. The value is stored at the order to search for these values in Business Managers and realize an easier operations process. Please note that this value is also stored as transactionid at the payment transaction object. Payment transaction attributes Wirecard Financial Institution: The financial institution. Wirecard Gateway Reference Number: The gateway reference number. Wirecard Contract Number: The contract number. Wirecard Payment Method: The Wirecard internal payment method. Wirecard Payment State: The Wirecard payment state (e.g. SUCCESS, PENDING, CANCEL). Wirecard Masked PAN (Credit Card): The masked pan for the credit card. Only stored for credit card transactions. Wirecard ideal Consumer Name: The ideal customer name. Wirecard ideal Consumer Account Number: The ideal customer account number. Wirecard ideal Consumer City: The ideal customer city. Wirecard Sender Account Number (Sofortüberweisung): The account number used at Sofort. Wirecard Sender Account Owner (Sofortüberweisung): The account owner who used Sofort. Wirecard Sender Bank Number (Sofortüberweisung): The bank number which was used for the transfer at Sofort. Wirecard Sender Bank Name (Sofortüberweisung): The bank name which was used for the transfer at Sofort. Wirecard Sender BIC (Sofortüberweisung): The BIC code used for the transfer at Sofort. Wirecard Sender IBAN (Sofortüberweisung): The IBAN used for the transfer at Sofort. Wirecard Sender Country (Sofortüberweisung): The country code of the sender used at Sofort. Wirecard Security Criteria (Sofortüberweisung): The security criteria returned by Sofort. Values are 0 (not secure) or 1 (secure), see the Wirecard documentation for more details. Wirecard Paypal Payer Id: The payer ID of the customer who did the PayPal transaction. Wirecard Paypal Payer The address of the customer who did the PayPal transaction. Wirecard Paypal Payer Last Name: The last name of the customer who did the PayPal transaction. Wirecard Paypal Payer First Name: The first name of the customer who did the PayPal transaction. 11/18

12 Step 8: Customizations You need to style and adjust the customization templates delivered by Wirecard with the integration package. The templates are not part of the plugin. Please refer to the documentation on how to adjust the templates, and them to our support teams once completed. Wirecard will assign a shop ID, which you need to add as a site preference. You can find more details regarding customizations of the Wirecard Checkout Page at Customization. Step 9: Fraud handling When the successurl, pendingurl or confirmurl is called, the return values are checked as follows: The order total amount at the order is the same as the authorized amount returned by Wirecard (success and confirmation only). The returned fingerprint is valid. If the check fails, a fatal error is logged to the Wirecard log scope. You may enable or disable to be 12/18

13 informed about the fatal errors via in Business Manager at Administration Operation s Custom Log Settings. Step 10: Golive Once all testing is done and the premium templates are setup, we recommend placing at least one test order per payment method against the live system of Wirecard, using real payment data. You can configure the settings on the Salesforce Commerce Cloud (Demandware) production system for that, or use the development system if necessary. Additional implementation documentation PendingUrl The pendingurl is called when Wirecard is not able to detect whether payment was successful or not. This might be the case for some payment methods such as e.g. PayPal. In this case, the standard 13/18

14 behavior is to set the order state to NEW, but the payment status remains NOT_PAID and the wirecardpaymentstate of the order is set to PENDING. The order confirmation page is displayed to the customer and informs that the financial institution has not yet approved the payment and that confirmation will be sent later. Once the Wirecard payment state of the order is set to SUCCESS, the order is completed and the payment state is set to PAID. Session timeouts When there is a session timeout in Salesforce Commerce Cloud (Demandware), and the confirmurl, successurl or pendingurl are called, there is no problem because the order is already created and will be set to state NEW within the pipeline. The customer might not be logged in anymore, but is still associated to the order. When the cancelurl, failureurl or serviceurl are called, the logic automatically detects a session timeout. Then, the basket will be restored from the previously created order using script RestoreBasket.ds. You need to add the logic to copy any custom attribute from the order to the basket within this script. The payment and eventually added gift certificates are not restored in the script and must be entered again. Trimmed response parameter values Fingerprint validation issues The standard Salesforce Commerce Cloud (Demandware) platform removes all trailing and leading whitespaces for response parameter values. So in case a trailing whitespace is sent back from Wirecard with one of the parameter values, the server logic will get this parameter without any whitespace. In this case, the fingerprint calculation will fail, even if the payment is correct. The issue currently happens with the test interface of Sofort. and a trailing whitespace for parameter value senderbankname. In order to avoid this in future, a parameter trimresponseparameters=yes is send to Wirecard, so that the parameters are also trimmed within the Wirecard Checkout Server to calculate the fingerprint. The parameter value can be controlled using a site preference and is already part of the integration. Controllers COWirecard: Main controller which implements all required storefront and backend logic. It contains all return URLs from Wirecard, the logic to handle the call to Wirecard, the rollback (failure) and completion of the order. Payment hooks 14/18

15 WIRECARD_CREDIT et al.: These payment hooks are named as the payment methods, and contain three hook functions dynamically called by the SiteGenesis and Wirecard integration. The code is the same for all payment methods: Handle: Called when the payment method is selected and adds the payment instrument to the basket. Authorize: Jumps to COWirecardRedirect which handles the collection of the call parameters. Complete: Calls COWirecardSetPaymentParameters to complete the payment and store all attributes. The hooks are registered in file hooks.json as defined in the Site Genesis standard cartridge. Main templates wirecard/wirecardswitch: Implements the switch to decide if Wirecard should be opened in an iframe of the browser. wirecard/wirecardforward: Submits the call parameters to Wirecard via post. wirecard/wirecardresponse: Only called if Wirecard was opened in an iframe and responds within the iframe. The template posts all http parameters again to the top window, in order to avoid that the shop is loaded in the iframe again. order/* : Business Manager hook templates for the Order Payment dialog to print out all payment transaction fields and avoid error logs. checkout/billing/* : See section Frontend Changes and Adjustments. Installation guide for previous versions If you use a previous version of Salesforce Commerce Cloud (Demandware) the following information may be of use for you. Frontend Changes and Adjustment In order to ensure that the Wirecard redirect is tracked in Salesforce Commerce Cloud Analytics, you should add an Assign node to pipeline COPlaceOrderCreateOrder. The UUID of the basket needs to be mapped to a pipeline dictionary parameter OriginalBasketUUID. The parameter is used in template wirecard/wirecardforward.isml to call the reporting hook. Changes to the number of the checkout step etc. need to be implemented in the project. 15/18

16 Necessary pipeline call nodes The Site Genesis 2 code supports the feature of asynchronous payments since version The cartridge is build using this feature, but existing custom code can also be easily adapted if necessary. Site Genesis 2 Asynchronous payments integration The cartridge should work as is and no pipeline modifications are necessary. The order is created in pipeline COPlaceOrder in state CREATED, and then the payment authentication is done. A dynamic pipeline node calls the Authorize pipeline for all Wirecard payment methods, which collects the necessary parameters and automatically posts this to Wirecard. The error and cancel handling is implemented in the main plugin pipeline COWirecard, and set the order to FAILED in this case. The basket will be restored in this case. When the confirmurl, successurl or pendingurl is called, all necessary attributes are stored at the order and payment. Pipeline COWirecardSubmitImpl is called to complete the order and then the order confirmation page is shown. Site Genesis 2 Older versions (migration guide) We strongly recommend to review the latest pipeline COPlaceOrder in the Site Genesis cartridge, and get familiar with the approach for asynchronous payments. The main changes you need to do in your projectspecific pipeline COPlaceOrder are: Please add a new pipeline COPlaceOrderCreateOrder to create the order and use pipeline CreateOrder2 (copy the code). Remove pipelet CreateOrderNo. Adjust COPlaceOrderHandlePayments to make dynamic call nodes to <paymentmethodid>authorize, or add each single payment method you want to support. Add a private call node for COPlaceOrderSubmitImpl, which is called by the plugin. Change COPlaceOrderPlaceOrder and use pipelet PlaceOrder within there. Additional changes for the authorization of gift certificates or similar might be necessary, but this strongly depends on your existing code. COPlaceOrder node for SubmitImpl 16/18

17 COPlaceOrder pipelines and logic for CreateOrder and PlaceOrder Main scripts 17/18

18 GetWirecardCallParameters: Collects all required parameters to call Wirecard. SetWirecardPaymentParameters: Sets all response parameters to the order and payment transaction depending on used the payment method. ValidateWirecardAmountAndFingerprint: Checks the Wirecard amount against the shop order amount and checks the fingerprint. SetOrderPaymentStatus: Sets the order payment status to PAID only if the payment status is SUCCESS and the confirmurl was called. CheckSessionTimeout: This script checks if the basket has been restored when the order was set to failed, so after the either the cancelurl or failureurl was called. Therefore, it is checked if the basket contains any line items (products or gift certificates). RestoreBasket: This script restores the basket and copies all line items, the billing and shipping address as well as the shipping method from the previously created order to the basket. Any copying of projectrelated custom attributes need to be added to this script. 18/18