Paymetrics Quick Start

Broadleaf Commerces offers an out-of-the-box Paymetrics XiPay solution that requires little configuration and is easily set up.
This implementation should be useful for those with a simple checkout flow.

You must have completed the Paymetrics Environment Setup before continuing

Adding Paymetrics Checkout Support

These instructions assume integration with the default Heat Clinic Demo Site provided with the framework.

In your core applicationContext.xml, replace the block of text

    <!-- Scan DemoSite Sample Payment Gateway Implementation -->
    ...
    <!-- /End DemoSite NullPaymentGateway Config -->

with

    <context:component-scan base-package="com.broadleafcommerce.payment.service.gateway"/>
    <context:component-scan base-package="com.broadleafcommerce.vendor.paymetrics"/>
    <bean class="com.broadleafcommerce.vendor.paymetrics.service.payment.PaymetricsGatewayType"/>

    <bean id="mySampleConfigurationServices" class="org.springframework.beans.factory.config.ListFactoryBean">
        <property name="sourceList">
            <list>
                <ref bean="blaymetricsConfigurationService"/>
            </list>
        </property>
    </bean>
    <bean class="org.broadleafcommerce.common.extensibility.context.merge.LateStageMergeBeanPostProcessor">
        <property name="collectionRef" value="mySampleConfigurationServices"/>
        <property name="targetRef" value="blPaymentGatewayConfigurationServices"/>
    </bean>

    <bean id="blVariableExpressions" class="org.springframework.beans.factory.config.ListFactoryBean">
        <property name="sourceList">
            <list>
                <ref bean="blPaymetricsVariableExpression" />
            </list>
        </property>
    </bean>

Depending on the integration method, on your checkout page, add the following to you credit card form:

form integration method (skip this section for iFrame):

    <input id="Paymetrics_BaseUrl" type="hidden" th:value="${#paymetrics.getBaseUrl() + '/Form'}" />
    <input id="Paymetrics_Guid" type="hidden" th:value="${#paymetrics.getGuid()}" />
    <input id="Paymetrics_AccessToken" type="hidden" th:value="${#paymetrics.generateAccessToken()}" />
    <input id="Paymetrics_OrderId" type="hidden" th:value="${cart.id}" />

Add this js to run when form is submitted

        var diecommUrl = $('#Paymetrics_BaseUrl').val();
        var merchantGuid = $('#Paymetrics_Guid').val();
        var accessToken = $('#Paymetrics_AccessToken').val();
        var orderId = $('#Paymetrics_OrderId').val();
        var cardType = //<Your card type (Visa, MC, Disc, Amex)>
        var binRange = //<Your bin range based on card type (3000, 4000, 5000, 6000)>
        var cardNumber = //<Your credit card number>
        var expirationMonth = //<Your expiration month>
        var expirationYear = //<Your expiration year>
        var cvv = //<Your cvv>
        var myData = $XIPlugin.createJSRequestPacket(merchantGuid, accessToken);
        myData.addField($XIPlugin.createField('Paymetric_CreditCardType', false, cardType));
        myData.addField($XIPlugin.createField('Paymetric_BinRange', false, binRange));
        myData.addField($XIPlugin.createField('Paymetric_CreditCardNumber-2', true, cardNumber));
        myData.addField($XIPlugin.createField('Paymetric_Exp_Month', false, expirationMonth));
        myData.addField($XIPlugin.createField('Paymetric_Exp_Year', false, expirationYear));
        myData.addField($XIPlugin.createField('Paymetric_CVV', false, cvv));
        myData.addField($XIPlugin.createField('Order_Id', false, orderId));
        $XIPlugin.submit({ url: diecommUrl, data: myData });
    });

iFrame integration method (skip this section for form):

    <div th:with="accessToken=${#paymetrics.generateAccessToken()}">
          <script th:src="${#paymetrics.getBaseUrl() + '/Scripts/XIFrame/XIFrame-1.1.0.js'}"></script>
          <iframe id="paymetrics-iframe" style="width:100% !important; height: 220px !important; border: none"
                  th:src="${#paymetrics.getBaseUrl() + '/View/IFrame/' + #paymetrics.getGuid() + '/' + accessToken + '/1'}">
          </iframe>
          <button onclick="payNow()">Pay Now</button>

          <form id="paymetrics-order-info" th:action='${#paymetrics.getProcessUrl()}' method='post' style="display: none">
            <input id='access-token' name='id' th:value="${accessToken}">
            <input name='orderId' th:value="${cart.id}">
            <input type="hidden"
                   th:name="${@blExploitProtectionService.getCsrfTokenParameter()}"
                   th:value="${@blExploitProtectionService.getCSRFToken()}" />
          </form>

          <script>
              function payNow() {
                  $XIFrame.submit({
                      iFrameId: 'paymetrics-iframe',
                      targetUrl: document.getElementById('paymetrics-iframe').getAttribute('src'),
                      onSuccess: function (e) {
                          document.getElementById('paymetrics-order-info').submit();
                      }
                  });
              }
          </script>
    </div>

Note - if the html that includes your credit card form (the above code) is loaded over ajax instead of a page load, the XiPay script will not work. This is inherent to XiPay and is not a Broadleaf issue.

(Optional) Override BroadleafPaymetricsController to add custom logic for handling the response from the above form's submission.

@Controller
public class MyPaymetricsController extends BroadleafPaymetricsController {

    @Override
    @RequestMapping(value = "/return", method = RequestMethod.GET)
    public String returnEndpoint(Model model, HttpServletRequest request, RedirectAttributes redirectAttributes, Map<String, String> pathVars) throws PaymentException {

        /*
         * Custom logic
         */

        return super.process(model, request, redirectAttributes);
    }

    @Override
    @RequestMapping(value = "/error", method = RequestMethod.GET)
    public String errorEndpoint(Model model, HttpServletRequest request, RedirectAttributes redirectAttributes, Map<String, String> pathVars) throws PaymentException {

        /*
         * Custom error logic
         */

        redirectAttributes.addAttribute(PAYMENT_PROCESSING_ERROR, request.getParameter(PAYMENT_PROCESSING_ERROR));
        return getOrderReviewRedirect();
    }
}

Note - you do not need to override the Paymetrics controller. It has logic to do all standard handling of transactions and errors. Only do this if you want to customize it.

The process method will decrypt the response and translate it into a form Broadleaf understands, before initiating checkout and performing all other necessary actions. It will return a redirect to the confirmation page.

Done!

At this point, all the configuration should be complete and you are now ready to test your integration with Paymetrics XiPay. Add something to your cart and proceed with checkout.