Skip to main content

Merchant Help

 

Affirm Merchant Help

Shopify Integration

Overview

This guide describes how to integrate Affirm into the Shopify platform so you can provide Affirm as a payment option to your customers. After integrating Affirm, your Shopify 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 Affirm on Shopify
  2. Add Affirm promotional messaging
  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, you should review:

Retrieve your keys by going to the Affirm Merchant Live Dashboard

  1. Go to https://www.affirm.com/dashboard
  2. Sign in with Google, or use your email and password.

Note: The work email address that you use to sign-in to the Affirm Dashboard must be granted access by your Dashboard's administrator, or your Affirm contact.

Need help accessing the Affirm Dashboard?

1. Install Affirm on Shopify

  1. Sign in to your Shopify account and go to Settings > Payments

Screen Shot 2018-07-24 at 2.39.28 PM.png

  1. In the Alternative Payments section, Select Affirm

Screen Shot 2018-07-24 at 2.39.57 PM.png

  1. Check the Use test mode checkbox for testing in our sandbox
  2. Enter the Public API Key and Private API Key you retrieved from the Affirm live merchant dashboard
  3. Click Activate

Affirm is now a payment option in Shopify.

shopify.png

Set a price floor for checkout (Shopify Plus only)

Merchants using Shopify Plus can set a price floor that displays Affirm as a payment option when the customer's cart exceeds a minimum dollar amount.

  1. Go to the Shopify script editor
  2. Click Create Script
  3. Choose Payment Gateway for the script type
  4. Choose Blank Template
  5. Click Create Script
  6. In the Title box, enter Affirm price floor as the script name
  7. Click Code to open the Ruby source code console
  8. Paste the following code into the console
available_gateways = Input.payment_gateways
cart = Input.cart
subtotal = cart.subtotal_price
unless cart.line_items.empty? or cart.discount_code.nil?
  case cart.discount_code
  when CartDiscount::Percentage
    if cart.subtotal_price >= cart.discount_code.minimum_order_amount
      subtotal = cart.subtotal_price * ((Decimal.new(100) - cart.discount_code.percentage) / 100)
    else
      subtotal = cart.subtotal_price
    end
  when CartDiscount::FixedAmount
    if cart.subtotal_price >= cart.discount_code.minimum_order_amount
      subtotal = cart.subtotal_price - cart.discount_code.amount
    else
      subtotal = cart.subtotal_price
    end
  else
    subtotal = cart.subtotal_price
  end
end
if subtotal < Money.new(cents:100) * 250
  available_gateways = available_gateways.delete_if do |payment_gateway|
    payment_gateway.name == "Affirm"
  end
end
Output.payment_gateways = available_gateways
  1. Click Run Script
  2. Click Save and Publish

The price floor takes effect immediately. Test it by attempting a checkout for an item less than the price floor amount.

2. Add Affirm promotional messaging

Affirm promotional messaging components—monthly payment messaging and educational modals—show customers how they can use Affirm to finance their purchases. Properly placed promotional messaging helps drive increased AOV and conversion.

Adding Affirm promotional messaging is a required integration step, and you should complete it before testing your integration. Click here for information about adding Affirm promotional messaging.

Use Multiple Financing Programs

Multiple Financing Programs (MFPs) allow you to offer custom financing programs to your customers based on rules you define. To learn more about MFPs and how to set them up in Shopify, contact your Client Success Manager.

3. Review your order management functions

Processing orders (authorize, void, refund, and partial refund) in Shopify updates the order status in the Affirm dashboard. While you can process orders in the dashboard, we strongly recommend using Shopify to keep order status synced with Affirm. For more information on processing orders in Shopify, 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.

To add the confirmation page function, go to Settings > Checkout > Order Processing > Additional scripts and add the code below.  Replace public_api_key with your public API key found in the merchant dashboard (You can also pass a session ID variable for the optional session_id to take advantage of additional analytics).

<script>
_affirm_config = {
   public_api_key:  "YOUR_PUBLIC_KEY",
   script:          "https://cdn1.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");

affirm.ui.ready(function(){
affirm.analytics.trackOrderConfirmed({
    "orderId": "{{ order.order_number }}",
    "total": "{{ order.total_price }}"
}, [{
   {% for item in order.line_items %}
   "productId": "{{ item.sku }}",
   "quantity": "{{ item.quantity }}",
   {% endfor %}
}]);
});
</script>

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. Sign in to your Shopify account and click the Settings (gear) icon at the bottom-left of the screen.
  3. Click Payments
  4. In the Alternative Payments section, find Using: Affirm and click Edit
  5. Uncheck the Use test mode checkbox
  6. Enter the Public API Key and Private API Key you retrieved from the Affirm merchant dashboard
  7. Click Save
  8. In the Affirm promotional messaging, update the Affirm.js code to use the live public API key you just received for public_api_key and https://cdn1.affirm.com/js/v2/affirm.js for script

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.