Affirm-developers

Shopify

Learn how to integrate Affirm into your Shopify eCommerce platform

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

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.

Affirm Dashboard

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 > Payment Providers

2. In the Alternative Payments section, Select Affirm

3. Check the Use test mode checkbox for testing in our sandbox
4. Enter the public_api_key and private_api_key you retrieved from the Affirm live merchant dashboard
5. Click Activate Affirm is now a payment option in Shopify.

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. There are two ways to add Affirm promotional messaging:

  • Affirm pay-over-time promotional messaging app: Our pay-over-time messaging app allows you to quickly configure and add promotional messaging to your site. When you enable the app, we automatically add our Affirm.js file to your theme code directory so you don't have to manually edit your theme file. This method is especially useful if you have custom themes. To use our messaging app, see our Promotional messaging app docs.
  • Manually edit your theme files: This allows you to manually add our promotional messaging HTML components to your store's theme files. To manually add promotional messaging components, see the Add Affirm promotional messaging in Shopify docs.

Manually adding promotional messaging

If you choose to manually edit your theme files, we recommend using an experienced front-end developer to avoid any potential errors in the code.

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.

<script>
_affirm_config = {
   public_api_key:  "YOUR_PUBLIC_KEY",
   script:          "https://cdn1.affirm.com/js/v2/affirm.js"
};
(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.id }}",
    "total": "{{ order.total_price }}"
}, [{
   {% for item in order.line_items %}
   "productId": "{{ item.sku }}",
   "quantity": "{{ item.quantity }}",
   {% endfor %}
}]);
});
</script>

Required function parameters

Order object

Attributes
Type
Description

paymentMethod

string

The payment method chosen by the customer (e.g., Visa). Maximum 150 characters.

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

Attributes
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 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 Integration Consultant or merchanthelp@affirm.com 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.

FAQ

1. Why are some orders are marked as 'Pending' when Payment Authorization is set to "Manual capture'?

This occurs due to a bug in Shopify admin UI where after successful Affirm authorization, order status does not get updated. In this race condition, when you have Payment Authorization set to Manually capture payment for orders in Settings > Payment Providers > Payment authorization, orders may be marked as Pending instead of Authorized. You can still process these orders (Cancel or Capture) within Shopify as you would normally do. To process these orders, follow these instructions.

Updated about 23 hours ago


Shopify


Learn how to integrate Affirm into your Shopify eCommerce platform

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.