Skip to main content

Merchant Help

 

Affirm Merchant Help

Kibo (MarketLive) Integration

Overview

This guide describes how to integrate Affirm into the Kibo (MarketLive) eCommerce platform so you can provide Affirm as a payment option to your customers. After integrating Affirm, your Kibo site will:

  • Offer Affirm as payment option on the checkout page
  • Process Affirm charges in your order management system
  • Display Affirm promotional messaging

The integration steps are:

  1. Install the Affirm Kibo module
  2. Configure Affirm as a payment method
  3. Review your order management functions
  4. Add the Confirmation Page function
  5. Test your integration
  6. Deploy to production

Before you begin

Before beginning integration work, you should review:

  1. The transaction flow when buying with Affirm
  2. The Kibo order job flow
  3. Your current checkout process to understand how Affirm will affect operations and customer experience
  4. Settlement reports to know how to reconcile transactions with the deposits into your bank account

1. Install the Affirm Kibo module

Before starting your server running this module, complete all the steps in this section or your store may not start correctly.

  1. Download the module from GitHub
  2. Add the module to your newly created Affirm project’s site.xml file
<sites>
  <deploy name="ylang">
    <section type="release" package="Marketlive-14" name="Platform" version="14.2.0.38"/>
    <section type="release" package="Marketlive-14" name="Integration/XMLBeans" version="14.2.0.38"/>
    <section type="release" package="Marketlive-14" name="Integration/Core" version="14.2.0.38"/>
    <section type="release" package="Marketlive-14" name="Apps/AppCommon" version="14.2.0.38"/>
    <section type="release" package="Marketlive-14" name="Apps/B2CWeb" version="14.2.0.38"/>
    <section type="release" package="Marketlive-14" name="Apps/Admin" version="14.2.0.38"/>
    <section type="release" package="Marketlive-14" name="Apps/IntegrationCLI" version="14.2.0.38"/>
    <section type="release" package="Modules" name="DataDeploy" version="14.2.0.38"/>
    <section type="source" package="sites/affirm_kibo_module/v14.2/trunk/source/Modules" name="DL-Affirm-Payment" version="1.0.0" />
    <section type="source" package="sites/affirm_kibo_module/v14.2/trunk/source" name="Apps/B2CWeb" version="14.2.0.38"/>
    <section type="release" package="Services" name="IntegrationWS/IntegrationWS-14" version="14.2.0.38" />
  </deploy>
</sites>
  1. Execute the following scripts to enable the Affirm payment method
  • /DL-Affirm-Payment/database/scripts/01-AddAffirmOrderPaymentType.sql
  • /DL-Affirm-Payment/database/scripts/02-AddOrderPaymentAffirmTable.sql
  • /DL-Affirm-Payment/database/scripts/03-UpdateCapture&RefundJobs.sql
  • /DL-Affirm-Payment/database/scripts/04-CreateVoidJob.sql
  • /DL-Affirm-Payment/database/scripts/05-CreateVoidTypeColumn.sql
  1. Paste your sandbox API keys in /DL-Affirm-Payment/database/mongo/AffirmCustomProperties.json (search for "name": "affirmpayment_public_api_key" and "name": "affirmpayment_private_api_key")
  2. Create and publish all of the properties defined in the following JSON files:
  • /DL-Affirm-Payment/database/mongo/AffirmCustomProperties.json
  • /DL-Affirm-Payment/database/mongo/AffirmCustomResources.json
  1. Confirm that the properties in AffirmCustomProperties.json are published to the desired environment
  2. Restart your Admin JVM to populate the Quartz Job Scheduling tables

2. Configure Affirm as a payment method

To configure Affirm as a payment method, you’ll need to make front-end changes and edit the property settings in your Kibo admin page.

Implement front-end changes

To add monthly payment messaging on all of your pages, add the Affirm.js embed code to your global layout page at /Modules/DL-Affirm-Payment/wwwroot/WEB-INF/views/layout/Main.jsp.

<!-- Affirm -->
<script>
 _affirm_config = {
   public_api_key:  "YOUR_PUBLIC_KEY",
   script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js",
   session_id:      "YOUR_VISITOR_SESSION_ID"
 };
 (function(l,g,m,e,a,f,b){var d,c=l[m]||{},h=document.createElement(f),n=document.getElementsByTagName(f)[0],k=function(a,b,c){return function(){a[b]._.push([c,arguments])}};c[e]=k(c,e,"set");d=c[e];c[a]={};c[a]._=[];d._=[];c[a][b]=k(c,a,b);a=0;for(b="set add save post open empty reset on off trigger ready setProduct".split(" ");a<b.length;a++)d[b[a]]=k(c,e,b[a]);a=0;for(b=["get","token","url","items"];a<b.length;a++)d[b[a]]=function(){};h.async=!0;h.src=g[f];n.parentNode.insertBefore(h,n);delete g[f];d(g);l[m]=c})(window,_affirm_config,"affirm","checkout","ui","script","ready");
// Use your live public API Key and https://cdn1.affirm.com/js/v2/affirm.js script to point to Affirm production environment.
</script>
<!-- End Affirm -->

To add Affirm to the checkout process, do the following:

  1. Add the above Affirm.js embed code to /Modules/DL-Affirm-Payment/wwwroot/WEB-INF/views/checkout/accordion/Accordion.jsp
  2. Add the new payment type /Modules/DL-Affirm-Payment/wwwroot/WEB-INF/views/checkout/accordion/PaymentAffirmCheckout.jsp (along with PaymentCreditCard.jsp and PaymentWithPaypal.jsp)
  3. Display the Monthly Payment Price feature at the summary level in /Modules/DL-Affirm-Payment/wwwroot/WEB-INF/views/checkout/accordion/Summary.jsp (only applies when BorderFree is not enabled, or the selected country is the US and custom.affirmpayment_monthly_payment_cartsummary_enabled = true)
  4. Modify the post-Confirm behavior to send the Affirm checkout object and initiate the Affirm checkout process in /Modules/DL-Affirm-Payment/wwwroot/includes/MarketLive/Checkout/accordion/controllers.js (customer goes to Affirm for loan confirmation)

Edit the Kibo property settings

To find a property, either look for it in the Properties menu or search for it. To view and edit the property, click on it. Never click Remove on any property as that will delete it. To clear a property value, set it to 0.

Screen Shot 2018-07-31 at 2.15.06 PM.png

  1. Sign in to the Kibo admin page
  2. Go to Settings > Configuration Manager > Properties

Screen Shot 2018-07-31 at 2.16.11 PM.png

  1. Search for custom.affirmpayment_real_time_capture_call and set it to true if you plan to auto-capture orders
  2. Search for custom.affirmpayment_real_time_capture_order_status and confirm that it is set to Confirmed
  3. Search for affirmpayment_paymentenabled and confirm that it is set to true (this enables Affirm as a payment option)
  4. Search for custom.affirmpayment_monthly_payment_min_price_range and click on it to set the minimum price that will display Affirm as a payment option
  5. Enter the value for the minimum price in USD cents (e.g., $50 is 5000)
  6. Click the arrow next to Save, then click the desired environment and confirm the change

Screen Shot 2018-07-31 at 2.19.33 PM.png

  1. Search for custom.affirmpayment_monthly_payment_max_price_range and click on it to set the maximum price that will display Affirm as a payment option
  2. Enter the value for the maximum price in USD cents (e.g., $50 is 5000)
  3. Click the arrow next to Save, then click the desired environment and confirm the change.
  4. Search for custom.affirmpayment_monthly_payment_basket_enabled and custom.affirmpayment_monthly_payment_globalcart_enabled and set them to true (this displays monthly payment messaging in your cart)
  5. Search for custom.affirmpayment_monthly_payment_product_enabled and click on it
  6. Set the property to true to display monthly payment messaging on your product pages

Screen Shot 2018-07-31 at 2.22.18 PM.png

  1. Click the arrow next to Save, then click the desired environment and confirm the change
  2. Search for custom.affirmpayment_monthly_payment_directory_enabled and click on it
  3. Set the property to true to display monthly payment messaging on your directory pages
  4. Click the arrow next to Save, then click the desired environment and confirm the change
  5. Go to Settings > Configuration Manager > Site Messaging

Screen Shot 2018-07-31 at 2.23.45 PM.png

  1. Search for and edit msg.resource.affirmPricingMessage and As low as $ dollarsParam with {0} if you want to customize the messaging (dollarsParam is the lowest installment price and {0} displays the Affirm logo)
  2. Save, publish to desired environment, and restart the server

3. Review your order management functions

Processing orders (authorize, void, refund, and partial refund) in Kibo updates the order status in the Affirm dashboard. While you can process orders in the dashboard, we strongly recommend using Kibo to keep order status synced with Affirm. For more information, refer to their documentation.

4. Add the Confirmation Page function

When a customer completes their purchase, you can send their order and product information to Affirm for A/B testing, which will help you optimize your site. Send this information by adding the Confirmation Page function to your payment confirmation page. We only require orderId, total, productId, and quantity for A/B testing.

Click here for all the Confirmation Page function parameters.

affirm.analytics.trackOrderConfirmed({
    "orderId": "T12345",
    "total": 3739
}, [{
    "productId": "SKU-1234",
    "quantity": 1
}, {
    "productId": "SKU-5678",
    "quantity": 1
}]);

Required function parameters

Order object

Parameter Type Description
orderId string Your internal unique identifier representing the order. Maximum 500 characters.
total integer The total amount of the transaction, including tax and shipping, stated in USD cents (e.g., $100 = 10000).

Product object

Parameter Type Description
productId string Your internal unique identifier representing the product, such as the SKU or an internal database identifier. Maximum 500 characters.
quantity integer The quantity of the purchased product.

5. Test your integration

After completing your integration, do a thorough testing of both your front-end and order management functions in our sandbox to ensure that everything works as expected. Click here for our recommended test plan. However, you’ll need to tailor your testing plan to your specific systems, processes, and integration.

6. Deploy to production

Coordinate testing with Affirm

Before deploying the Affirm integration to your production site, Affirm will need to test it in your development or staging environment connected to our live environment. Contact your Client Success Manager to coordinate this test.

Connect to the live Affirm environment

  1. Retrieve your live API keys at https://affirm.com/dashboard/#/apikeys
  2. Paste your live API keys in /DL-Affirm-Payment/database/mongo/AffirmCustomProperties.json (search for "name": "affirmpayment_public_api_key" and "name": "affirmpayment_private_api_key")
  3. Remove sandbox from all URLs in /DL-Affirm-Payment/database/mongo/AffirmCustomProperties.json (search for sandbox)

The Production build requires publishing all properties and messaging to the Staging and Production environments BEFORE the Staging/Production build. You’ll need a DBA to execute the necessary database change scripts.

Launch to production

After you’ve connected to our live environment and we’ve tested your integration, you’re ready to deploy to your production environment and offer Affirm as a payment option to your customers.