Skip to main content

Merchant Help

 

Affirm Merchant Help

AmeriCommerce Integration

Overview

This guide describes how to integrate Affirm into the AmeriCommerce eCommerce platform so that you can provide Affirm as a payment option to your customers. After integrating Affirm, your AmeriCommerce 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 and configure Affirm
  2. Add Affirm.js
  3. Add Affirm promotional messaging
  4. Review your order management functions
  5. Add the Configuration Page function
  6. Test your integration
  7. Deploy to production

Before you begin

Before beginning integration, you should review:

Sandbox development

You should have received an email inviting you to create an Affirm account. Click here for information about accessing your account.

Develop and test the Affirm integration in your development environment connected to our sandbox. To use our sandbox, retrieve your sandbox API keys at https://sandbox.affirm.com/dashboard/#/apikeys for use during integration.

After development and testing, you'll need to update your integration to use your live API keys, which you can find at https://affirm.com/dashboard/#/apikeys.

1. Install and configure Affirm

Visit AmeriCommerce for instructions on how to install and configure Affirm. Check Use Sandbox for development and testing. Return here after configuring Affirm to complete the integration.

2. Add Affirm.js

Add Affirm.js to the global page template.

  1. Go to to Themes > Edit Theme > Head Tags
  2. Add the code below
<!-- 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 -->

Be sure to use your public API key from the sandbox merchant dashboard for public_api_key and a session ID variable for the optional session_id to take advantage of additional analytics.

3. Add Affirm promotional messaging

Add an HTML element everywhere you want to display an Affirm promotional messaging component. The element attributes (see below) determine which component displays. We generally recommend adding promotional messaging to your category, product, cart, and payment pages.

In each HTML element, include the new data-page-type attribute corresponding to the page where that promotional messaging component is placed. The data-page-type attribute allows you to customize messaging in the future without development work. By default, promotional messaging on product pages have prequalification enabled, but you can work with your Client Success Manager to change this and configure additional customizations.

You’ll need to edit the HTML on your pages by signing in to the AmeriCommerce admin page and navigating to Themes > Edit > Product Details > HTML Editor. When configuring your promotional messaging, you'll need to use AmeriCommerce’s merge codes for the data-amount values. Possible merge codes include:

  • ##RAWPRICE## (product page)
  • ##CARTRAWTOTAL## (cart page)
  • $$ITEMPRICEDOLLARS$$
  • $$ITEMPRICECENTS$$
  • ##ITEMPRICE##
  • $$ITEMPRICE$$
  • $$PRICE$$

Add promotional messaging to product and cart pages.

<script>
   affirm.ui.ready(function(){
     var refreshable = document.getElementById('as-low-as-refreshable');
     if (refreshable){
         var amount = "##RAWPRICE##".replace(/[^0-9]+/g,"");
         refreshable.setAttribute('data-amount', amount);
         affirm.ui.refresh();
     }
 });
 </script>
 
 <p class="affirm-as-low-as" data-amount="##RAWPRICE##" id="as-low-as-refreshable" data-page-type="product"> </p> 

Here’s a sample code for a variant product page.

 <script>
   //Calculate price to update data-amount value
   function updateAffirmDataAmount (){
       var rawProductPrice = $('.ProductDetailsPricing .ProductDetailsPrice').html();
       rawProductPrice = Math.round(100 * parseFloat(rawProductPrice.replace(/[^0-9\.-]+/g, '')));       
       var refreshable = document.getElementById('as-low-as-refreshable');
       refreshable.setAttribute('data-amount', rawProductPrice);
   }
 
  //Check if the product price changed
   $(document).on("DOMSubtreeModified", ".ProductDetailsPricing .ProductDetailsPrice", function () {
       updateAffirmDataAmount ();
       affirm.ui.refresh();
   });
 
 </script>  
 
 <p class="affirm-as-low-as" data-amount="" id="as-low-as-refreshable" data-page-type="product"> </p>
 
 <script>
      updateAffirmDataAmount();
 </script>

Click here for more information on adding Affirm promotional messaging to your site

4. Review your order management functions

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

5. 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. Click here for all the Confirmation Page function parameters.

To add the function, go to Settings > Orders > General and paste the script below in the Place Order Script box.

<script>
affirm.ui.ready(function(){
    var orderTotal = "##ORDERTOTAL##".replace(/[^0-9]+/g,"")
    affirm.analytics.trackOrderConfirmed({
       "orderId": "##ORDERID##",
       "total": orderTotal,
    });
 });
</script>

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).

6. 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.

7. 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

Refer back to the AmeriCommerce instructions for connecting to the live Affirm environment.

  1. Retrieve your live API keys at https://affirm.com/dashboard/#/apikeys
  2. Enter the Public API Key and Private API Key you just retrieved from the Affirm merchant dashboard
  3. Uncheck the Use Sandbox box

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.