Customizing Your WebSphere Commerce Integration
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
- Right click on the server within the Servers tab view
- Choose Clean... (the option below Publish).
- 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"
- 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
Property | Description |
---|---|
ApruveProcessor_<storeidentifier> | This is the processor object which calls apruve API |
ApruveRequestBuilder_<storeidentifier> | This class will actually build the request object. |
ApruveResponseProcessor_<storeidentifier> | Once request is processed, reply is wrapped into a response object. We need to process this response, which is done in ResponseProcessor Object. |
ApruveUtility_<storeidentifier> | |
ApruveProcessorHelper_<storeidentifier> | |
ApruveErrorMessage_<storeidentifier> | Location of properties file |
apruveConstantTextSource_<storeidentifier> | |
apruveParamsSource_<storeidentifier> | This can be MERCHCONFINFO or location of properties file. If configured as MERCHCONFINFO you need to make sure all data is in MERCHCONFINFO table |
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
.
Updated about 7 years ago