Skip to main content

Merchant Help

 

Affirm Merchant Help

Magento 2 Integration

Overview

This guide describes how to integrate Affirm into your Magento 2 eCommerce platform so that you can provide Affirm as a payment option to your customers. After integrating Affirm, your Magento 2 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 Magento 2 extension
  2. Configure Affirm as a payment method
  3. Add Affirm promotional messaging
  4. Review your order management functions
  5. Add the Confirmation Page function
  6. Test your integration
  7. Deploy to production
  8. Refer FAQ for known integration issues

Before you begin

Before beginning integration, you should review the following:

IMPORTANT NOTE:

  • Install the extension in your sandbox or staging environment before pushing it live
  • Keep a copy of your Magento store and database to ensure you can revert to the version before the installation
  • You may need to re-index all the produce and category tables after extension installation

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 the Magento 2 extension

You have 2 options for installing the Magento 2 extension. Both options also upgrade the extension using the exact same steps described below.

Install using Composer
  1. Retrieve your Magento authentication keys
  2. In the Magento 2 root directory, enter the following commands using the command line:
composer require affirm/magento2
composer update
php bin/magento setup:upgrade
php bin/magento setup:di:compile
  1. Clear the Magento 2 cache to use the default Magento 2 Affirm configuration
Install using Command Line
  1. Download the extension
  2. If it does not exist, create the directory Magento2_root/app/code/Astound/Affirm/
  3. Unzip the extension and move all the files to Magento2_root/app/code/Astound/Affirm/
  4. In the Magento 2 root directory, run the following command to verify that Astound_Affirm exists in List of disabled modules:
php bin/magento module:status
  1. In the Magento 2 root directory, run the following commands:
php bin/magento module:enable Astound_Affirm
php bin/magento setup:upgrade
  1. Clear the Magento 2 cache to use the default Magento 2 Affirm configuration

2. Configure Affirm as a payment method

After installing the extension, enable Affirm as a payment method by updating Magento 2’s configurations:

  1. Sign in to your Magento 2 admin portal
  2. Go to Stores > Configuration > Sales > Payment Methods > Affirm
  3. Set Enabled to Yes
  4. Keep Mode set to Sandbox (for development and testing)
  5. Enter the Public API Key and Private API Key (private key) you retrieved from the Affirm sandbox merchant dashboard
  6. If your checkout process automatically captures the charge, set Payment Action to Authorize and Capture
  7. Enter the dollar amount values for Minimum Order Total and Maximum Order Total that displays Affirm as a payment option to your customers when checking out (default is 0.01 and 100000, respectively)
  8. If you want to change the order of displaying Affirm as a payment option during checkout, enter a Sort Order value greater than 0.
  9. If you want to display Affirm as text instead of a logo during checkout, set Plain Text Appearance to Yes.
  10. If you want to customize the default Affirm logo, add the URL for the desired logo in Icon (requires Plan Text Appearance set to No)
  11. If you want to customize the default subtext, you can add in-line HTML to Affirm Payment Method HTML (requires Plan Text Appearance set to No)
  12. Set Enabled Checkout Button to Yes to display the Affirm button on the cart page (you can update the Affirm button URL in the Checkout Button Code)
  13. Keep Checkout Flow Type set to Redirect to send customers to an affirm.com page for checkout. Set Checkout Flow Type to Modal to use a modal for checkout

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

If these changes do not take effect immediately:

  1. In the Magento admin panel, go to System > Cache Management
  2. Click Flush Magento Cache
  3. Sign out
  4. Sign back in to reset permissions

3. Add Affirm promotional messaging

Add Affirm promotional messaging—which includes monthly payment messaging and educational modals—on your product, category, and cart pages.

  1. In the Magento admin panel, go to Stores > Configuration > Affirm Promos
  2. In the As Low As Functionality settings, set the following to Yes:
  • Enable for Product PDP (product pages)
  • Enable For Category PLP (category pages)
  • Enable for Shopping Cart (cart page)
  1. Select a color for Affirm logo
  2. Enter the Minimum amount for displaying the monthly payment pricing value to set the minimum threshold dollar amount that will display monthly payment messaging (e.g., setting this value to 100 will only display monthly payment messaging for products above $100)
  3. You can optionally enter a Promo ID value in Data Promo ID (contact the Affirm Client Success team for more information about Promo ID’s).

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

Add promotional banners

To add Affirm banner images to various pages on your site:

  1. In the Magento 2 admin panel, go to Stores > Configuration > General > Affirm Promos
  2. Set Enabled to Yes
  3. For each page where you want a banner displayed, set Display to Yes and Promo Size and Promo Position to the values of your choice

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

Use Multiple Financing Programs

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

4. Review your order management functions

Processing orders (authorize, void, refund, and partial refund) in Magento 2 updates the order status in the Affirm dashboard. While you can process orders in the dashboard, we strongly recommend using Magento 2 to keep order status synced with Affirm. Click here for more information.

5. Add the Confirmation Page function

Confirmation page analytics is available in version 2.0.9 and up of the Magento 2 extension. To enable confirmation page analytics:

  1. Go to Stores > Configuration > Affirm Promos
  2. In the Enhanced Analytics section,  set Enable pixel for confirmation page to Yes

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

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

  1. Retrieve your live API keys at https://affirm.com/dashboard/#/apikeys
  2. In the Magento admin panel, go to Stores > Configuration > Sales > Payment Methods > Affirm
  3. Set Mode to Production
  4. Enter the Public API Key and Private API Key you just retrieved from the Affirm merchant dashboard

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

How do I modify the monthly payment messaging placement on the product detail or cart page?

You can place monthly payment messaging on the product detail page by doing the following:

  1. In the Magento 2 admin page, go to Stores > Configuration > General > Affirm Promos
  2. In As Low As Additional Developer Settings, set Placement options for As low as to one of these options:
  • After Price (selected by default)
  • Before Price
  • End of Product Info

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

This integration uses the Affirm/Block/Promotion/ProductPage/Aslowas block and the Affirm/view/frontend/templates/promotion/aslowasPDP.phtml template. To include this block in a specific location on the product or cart page, you’ll need to select the appropriate handle (the default product page in Magento 2 is catalog_product_view.xml) and parent block or container, which will render the as low as block (using <referenceBlock name="parent_block_name"> structure or <referenceContainer name="test_content">), where parent_block_name - name parent block in layout.

If your website dynamically changes the product price based on size, color, or some other attribute, a selector allows you to call the updateAffirmAsLowAs function. This function updates the monthly payment calculation whenever the price changes. See these files:

  • Astound\Affirm\Block\Promotion\AslowasAbstract.php
  • Astound\Affirm\Block\Promotion\ProductPage\Aslowas.php
  • Astound\Affirm\Block\Pro motion\CartPage\Aslowas.php
  • Astound\Affirm\view\frontend\web\js\model\aslowas.js

 

What to do if I see "Invalid header line detected" error message when placing an order with Affirm?

Reason for this error is: We recently upgraded our load balancers from AWS Classic ELB to AWS Application Load Balancer and the new ALB supports both HTTP/1.1 and HTTP/2. As a result, clients that support HTTP/2 will auto upgrade. It's likely that cURL also auto upgrades to HTTP/2, transparently i.e. it sends HTTP/2 request with a HTTP/2 response, on the wire. We use magento's core Zend Framework library for curl request and it does not support HTTP/2. We have plans to switch to another library or Magento's curl in future, to fix the issue for now please follow these instructions to apply patch to add HTTP/2 support to ZF1 library.

1. File path : <magento root>/vendor/magento/zendframework1/library/Zend/Http/Response.php, modify around line 185 :
From: 
        if (! preg_match('|^\d\.\d$|', $version)) {
To:
        if (! preg_match('|^\d\.\d$|', $version) && ($version != 2)) { // Hot fix by Affirm

2. File path : <magento root>/vendor/magento/zendframework1/library/Zend/Http/Response.php, modify around line 586 :
From:
        if ($index === 0 && preg_match('#^HTTP/\d+(?:\.\d+) [1-5]\d+#', $line)) {
            // Status line; ignore
            continue;
        }
To:
        if ($index === 0 && preg_match('#^HTTP/\d+(?:\.\d+) [1-5]\d+#', $line)) {
            // Status line; ignore
            continue;
        }
        // Hot fix by Affirm
        if ($index === 0 && preg_match('#^HTTP/2 200#', $line)) {
            // Status line; ignore
            continue;
        }