Getting the Plugin

The plugin is available in our GitHub repository: https://github.com/apruve/apruve-websphere

The project contains the following folders:

• WC
  • lib - contains required JAR files to communicate with Apruve
  • xml - payment configuration related files
• ZApruvePaymentPlugin.jar - EJB project JAR which has entity beans to persist Apruve data and payment plugin session bean
• WebSphereCommerceServerExtensionsLogic - contains commands and utility classes
• Stores - Struts config file and properties file
• Dataload
  • acp - contains access control policy files
  • sql - SQL scripts that are required to create tables, make cmdreg entries and policy entries

How to Integrate

Add the EJB project to your workspace

If your workspace already has ZApruvePaymentPlugin as a EJB project, and connected to SVN, please disconnect the project from SVN and make sure to check 'also delete the SVN meta information from the file system', then click Ok.

To import the EJB project into your workspace, right click on an empty space in navigation view, select Import, select the EJB folder, then select EJB JAR file.

Once the JAR file has been imported, update your project's build path. Right-click on the project, click Properties, then select Build Path. Add WebSphereCommerceServerExtensionsData to your build path.

Prepare the project for deployment:

Restart WC server, and republish it.

Add ZApruvePaymentPlugin to your WC project

Add ZApruvePaymentPlugin to Stores/WebContent/META-INF/MANIFEST.MF

Steps to republish/to fix issues with ZApruvePaymentPlugin.jar during publishing

1. Right click on the server within the Servers tab view
2. Choose Clean... (the option below Publish).
3. The dialog that appears next should ask you: "Clean will discard all publish state and republish from scratch. Are you sure you want to clean all published projects?". The dialog will also present you with the two buttons: "OK" and "Cancel"
4. The state of server should not matter, but these steps were tested with the server started already.

Coding Changes

Struts Configuration

Copy Stores/WebContent/WEB-INF/struts-config-apruve.xml to your stores project

XML Changes

This is required to configure your plugin with the Apruve payment method.

Merge the below mentioned files from the Zip folder:

File: \WC\xml\config\payments\edp\groups\default\PaymentMappings.xml

<Mapping paymentActionRule="Early Deposit" paymentConfiguration="ZApruveOnlineConfiguration" paymentMethod="Apruve"/>

File: \WC\xml\config\payments\edp\groups\default\PaymentMethodConfigurations.xml

<PaymentMethodConfiguration dependentCreditRequired="true" humanEditable="true" maximumAmount="Unbounded" 
  minimumAmount="0" name="ZApruveOnlineConfiguration" partiallyConsumable="true" paymentSystemName="ZApruveOnlineSystem" 
  priority="HIGH" refundAllowed="true" systemEditable="true"/>

File: \WC\xml\config\payments\ppc\plugins\PaymentSystemPluginMapping.xml

<PaymentSystemName name="ZApruveOnlineSystem"> 
  <Mapping paymentConfigurationId="default" pluginName="ZApruvePaymentPlugin"/>
</PaymentSystemName>

Copy the folders:

• WC\xml\config\payments\edp\groups\default\ZApruveOnlineConfiguration
• WC\xml\config\payments\ppc\plugins\ZApruvePaymentPlugin

View/JS Changes

File: /Stores/WebContent/ZCGAuroraB2C/ShoppingArea/CheckoutSection/OrderShippingBillingDetails.jsp
Page: Shipping Billing Method

Description:
Code Added to redirect to the Apruve account and toggle the payment options based on the presence of Apruve.

File: /Stores/WebContent/ZCGAuroraB2C/Snippets/EDP/PaymentMethods/PaymentAmount.jspf
Page: Shipping Billing Method
Description:
Code Added to populate the amount in the Amount text box during the existing Apruve payment method.

File: /Stores/WebContent/ZCGAuroraB2C/ShoppingArea/CheckoutSection/CheckoutPaymentsAndBillingAddress.jspf
Page: Shipping Billing Method
Description:
Conditions added to display Apruve payment methods and to send the parameters which will be used in the piAdd/Update.

File: /Stores/WebContent/ZCGAuroraB2C/ShoppingArea/CheckoutSection/CheckoutPaymentAndBillingAddressSummary.jspf
Page: Shipping Billing Method
Description:
Condition added to stop display billing address if the payment method is Apruve and display 'Apruve' as billing address.

File: /Stores/WebContent/ZCGAuroraB2C/javascript/CheckoutArea/CheckoutPayments.js
Page: Shipping Billing Method
Description:
Conditions added to handle Apruve Payments.

File: /Stores/WebContent/ZCGAuroraB2C/Snippets/EDP/PaymentMethods/StandardApruve.jsp
Page: Shipping Billing Method
Description:
Payment snippet for the Apruve payment method (PaymentAmount.jspf will be included in this jsp, to pass piAmount for piAdd/update. Make sure that Apruve payment method is not displayed with other payment methods in the drop down, for this code added in the CheckoutPaymentsAndBillingAddress.jspf)

Note: If you are not using ZCGAuroraB2C, like B2BDirect or Elite or any other store, this will be
OrderItemDisplay.jsp. Copy snippet from <!-- Apruve requirement start --> till <!-- Apruve requirement end–>. If you have any questions, please reach out to Zobrist Apruve support team at [email protected].

Resource Bundle

Copy the below mentioned new property files for communication with the Apruve environment

• Apruve.properties (stores/src/<StoreIdentifier>/com/zobristinc/commerce/payments/apruve/Apruve.properties)

• apruveConfig.properties: This file helps to extend the default implementation of the plugin

  Note: A detailed explanation of how to configure the above two files is in the section How to Configure the Plugin below.

• ApruveErrorMessages.properties: This file consists of error messages that may occur during the payment process.

• ApruveLineDetails.properties

Copy Apruve-related (as designated by "Apruve requirement" comments) key values from storetext_v2.properties to your storetext property file.

Java file changes

Add ZApruvePaymentPlugin to the build path of your WebSphereExtensionLogic

File: com/zobristinc/commerce/integration/apruve/commands/OrderItemsDetail.java
Description:
Value object for order items information, will be used while creating the json or hash to create Apruve order.

File: com/zobristinc/commerce/integration/apruve/commands/ZCOrderInformationCmd.java
Description:
Interface for new controller command

File: com/zobristinc/commerce/integration/apruve/commands/ZCOrderInformationCmdImpl.java
Description:
Implementation class forZCOrderInformationCmd, used to create secure hash and json object used for creating apruve order

File: com/zobristinc/commerce/integration/apruve/commands/ZCApruveProcessWebhookResponseCmd.java
Description:
Interface for new controller command

File: com/zobristinc/commerce/integration/apruve/commands/ZCApruveProcessWebhookResponseCmdImpl.java
Description:
Implementation class for ZCApruveProcessWebhookResponseCmd, this command will be used to receive the responses from webhooks and perform respective operations in commerce

File: com/zobristinc/commerce/integration/apruve/commands/ZCReturnFromApruveCmd.java
Description:
Interface for new controller command

File: com/zobristinc/commerce/integration/apruve/commands/ZCReturnFromApruveCmdImpl.java
Description:
Implementation class for ZCReturnFromApruveCmd, this command will be called to add payment in commerce after creating the order at Apruve.

Environment Changes

Add ZApruvePaymentPlugin.jar to the lib directory of the WC project.

Add ZApruvePaymentPlugin.jar to Stores/WebContent/META-INF/MANIFEST.MF

Copy the following files into 'DataLoad'

• acp/common/ApruveACPPolicy.xml
• sql/common/Apruve.sql

Make sure you include ApruveACPPolicy.xml in the ACP load script. Run Apruve.sql only once in each environment.

Import the certificate for the host mentioned in the webhooks. For example: aprvdev.zobristinc.com (host name of webhook url given in merchant site)

Steps on importing certificate can be found in the deploy and set up instructions

How to configure the Apruve plugin

There are two places you need to configure:

apruveConfig.properties

This file is for extending the default implementation. Every key class is configured in apruveConfig.properties. As we cannot predict every requirement, code is written to be flexible, and as such, we extend request building, processing and response handling.

If you only have a single store or brand, you can leave _<storeidentifier> off of the property names. For example:

ApruveProcessor=com.zobristinc.commerce.payments.apruve.processor.ZCApruveDirectProcessor

These are the properties you can configure

Apruve.properties.

This file can be found in Stores/src/<storeName>/com/zobristinc/commerce/payments/apruve/.

# Payment method id, default value is Apruve
ApruvePayMethodId = Apruve
# You can choose to add payment on return from apruve. In case you want to delay it till checkout page
addPaymentOnReturn = true
# This is gift card payment method. When there are gift card payments we sent gift card amount as other payments
GiftCardPayMethod = GiftCard
#merchant details
#Merchant authentication information
Merchant_ID = <Your Apruve Merchant ID>
Merchant_API_Key = <Your Apruve API Key>
#flags used for creating finalize and invoice
#if we set FINALIZE_ON_CREATE as true then the apruve order gets finalize immediately after creating order else we can set it as false and finalize the order later
FINALIZE_ON_CREATE = false
#if we set INVOICE_ON_CREATE as true then the apruve will generate invoice automatically when order gets created else we can set it as false and we can create invoice latter.
INVOICE_ON_CREATE = false
#Request header values used while creating requests 
accept = application/json
contentType = application/json

#Request URLs
#URL used for finalizing order
APRUVE_ORDER_FINALIZE_URL_START = https://app.apruve.com/api/v4/orders/
APRUVE_ORDER_FINALIZE_URL_END = /finalize
#URL used for updating order
APRUVE_UPDATE_ORDER_URL = https://app.apruve.com/api/v4/orders/
#URL used for creating order items
APRUVE_ORDER_CREATE_ORDER_ITEMS_URL_START = https://app.apruve.com/api/v4/orders/
APRUVE_ORDER_CREATE_ORDER_ITEMS_URL_END = /order_items
#URL used for updating order items
APRUVE_UPDATE_ORDER_ITEMS_URL = https://app.apruve.com/api/v4/order_items/
#URL used for deleting order items
APRUVE_DELETE_ORDER_ITEMS_URL = https://app.apruve.com/api/v4/order_items/
#URL used for creating invoice
APRUVE_ORDER_CREATE_INVOICE_URL_START = https://app.apruve.com/api/v4/orders/
APRUVE_ORDER_CREATE_INVOICE_URL_END = /invoices
#Public key file path used for verifying signature for webhook requests(file given by apruve).

APRUVE_PUBLIC_KEY_FILE_PATH = C:/IBM/WCDE80/workspace/ZApruvePaymentPlugin/ejbModule/com/apruve/payment/plugin/public_key.txt

Customizing Code

First step to customize plugin code is you need to update apruveConfig.properties file. Update the required class you
want to customize.

Every request is generated using simple value object. Example, if you want to send different value for 'createapruveorderrequest', extend ZCApruveCreateOrderRequestObject and overwrite getJSONRequestObj.

Extend ZCApruveRequestBuilder and overwrite getApruveCreateOrderTransactionObject method to return new <ext>ApruveCreateOrderRequestObject.