Affirm-developers

Salesforce Commerce Cloud

Overview

This guide describes how to integrate Affirm into Salesforce Commerce Cloud (formerly Demandware) so that you can provide Affirm as a payment option to your customers. It is applicable if your SiteGenesis is either based on Pipelines or JavaScript controllers or if it uses Storefront Reference Architecture (SFRA). Adding Affirm allows your Salesforce Commerce Cloud site to:

  • 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:

1. Install Affirm

Installing Affirm on Salesforce Commerce Cloud requires importing the Affirm cartridge, importing the required XML files, and enabling Affirm as a payment processor.

Import the Affirm cartridge

1. Download the cartridge
2. In the Salesforce UX Studio menu, click File > Import
3. Click to expand General and click Existing Projects into Workspace
4. Click Next

5. Click Browse and navigate to the directory where you downloaded the Affirm cartridge

6. After the window loads the project, click Select All
7. Click Finish
8. Right-click the project and click Properties
9. Click Project References and check all the Affirm references
10. Click OK
11. After Salesforce UX Studio builds the workspace, sign in to Business Manager and go to Site > Manage Sites
12. Select your site and click Settings
13. At the end of the cartridge path field, add the following options based on the Commerce Cloud Type:

  • Pipelines - int_affirm:int_affirm_controllers
  • JavaScript controllers - int_affirm:int_affirm_controllers
  • SFRA - int_affirm:int_affirm_sfra

Import the XML files from the Metadata directory of the downloaded cartridge

1. In the Business Manager go to Administration > Site Development > Import & Export
2. In the Import & Export Files section, click Upload

3. Select affirm_meta.xml
4. In the Meta Data section, click Import and select affirm_meta.xml

5. In the Business Manager go to Merchant Tools > Ordering > Import & Export
6. In the Import & Export Files section, click Upload

7. Select affirm_payment.xml
8. In the Payment Methods section, click Import and select affirm_payment.xml

9. In the Business Manager go to Merchant Tools > Content > Import & Export
10. Update the library ID in affirm_asset.xml

  • For Pipelines and Controllers put 'SiteGenesisSharedLibrary'
  • For SFRA put 'RefArchSharedLibrary'

11. In the Import & Export Files section, click Upload

12. Select affirm_asset.xml
13. In the Libraries section, click Import and select affirm_asset.xml

14. In the Business Manager go to Merchant Tools > Online Marketing > Import & Export
15. In the Import & Export Files section, click Upload

16. Select affirm_slots.xml
17. In the Content Slots section, click Import and select affirm_slots.xml

Enable the Affirm payment processor

1. In the Business Manager go to Merchant Tools > Ordering > Payment Processors
2. Click NEW
3. Verify that Site Preferences group was created with ID - AFFIRM_PAYMENT and name -- Affirm.
4. Verify Site Preferences Group exists with

  • ID: AFFIRM_PAYMENT
  • Name: Affirm

5. Merchant Tools > Ordering > Payment Methods Verify payment method exists with:

  • ID: Affirm
  • Name: Affirm

6. Click Enable
7. You can optionally add an image or text for the payment method by updating the asset affirm-payment-method

Edit Template Files

You would also need to update your sites template files to support promotional messaging and checkout functions. Instructions to make these custom changes can be found here.

Additionally, click Credit/Debit Carts to verify that Visa is enabled.

2. Configure Affirm as a payment method

After installation, enable Affirm as a payment method by updating these configurations:

1. In the Business Manager go to Merchant Tools > Site Preferences > Custom Preferences > AFFIRM_PAYMENT
2. Set Affirm Online Status to Yes
3. Enter the Affirm Public Key and Affirm Private Key (Affirm Financial Product Key is deprecated) you retrieved from the Affirm sandbox merchant dashboard
4. Set Affirm Mode to Sandbox for testing
5. If your checkout process automatically captures the charge, set Affirm Payment Action to Authorize and Capture
6. Enter the dollar amount values for Payment Min Total and Payment Max Total that displays Affirm as a payment option to your customers when checking out
7. Set Checkout Flow to Redirect (default) or Modal to control the Affirm checkout flow
8. Set Enable Affirm Analytics to Yes to enable analytics tracking for the order confirmation page

  • VCN Payment Instrument should be disabled unless virtual card integration is enabled for your merchant account
  • Leave the Financing program fields blank. This is now managed by Affirm unless you are offering multiple financing programs on a SKU, category or product level. To learn more about MFPs and how to set them up in Commerce Cloud, contact your Client Success Manager.

9. In the Business Manager, go to Administration > Operations > Services > Service Credentials.
10. Choose New.
11. Enter the following details:

  • Name: Affirm
  • User: Affirm Public Key
  • Password: Affirm Private key

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 Business Manager main page, go to Merchant Tools > Site Preferences > Custom Site Preferences > Affirm
2. Set the following to Yes to display messaging on those pages:

  • Product Promo Message (product pages)
  • PLP Promo Message (category pages)
  • Cart Promo Message (cart page)

3. Enter a Promo Min Total value to set the minimum threshold dollar amount that will display monthly payment messaging (e.g., setting the Promo Min Total to 100 will only display monthly payment messaging for products above $100)
4. If you have been provided with a Promo ID by the Affirm team, you can optionally enter a Promo ID value, to customize messaging (prepend the Promo ID value with default|data-promo-id and set Default financing program to default). Otherwise, leave all the "Financing Program" related field blank.

Use Multiple Financing Programs

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

4. Set up your order management functions

Processing orders (authorize, void, refund) in Commerce Cloud updates the order status in the Affirm dashboard. While you can process orders in the dashboard, we strongly recommend using Commerce Cloud to keep order status synced with Affirm.

To set up your order management functions, you'll need to import XML files from the downloaded cartridge and enable each job (function). Some of these function may not be available in older versions of the cartridge.

1. In the Business Manager go to Administration > Operations > Import & Export
2. In the Import & Export Files section, click Upload

3. Select affirm_services.xml
4. In the Services section, click Import and select affirm_services.xml

5. In the Import & Export Files section, click Upload

6. Select the affirm_jobs.xml file
7. In the Job Schedules section, click Import and select the affirm_jobs.xml file you just selected

8. Go to Administration > Operations > Jobs.
9. Verify that each job exists

10. For each job (shown above), check the enabled box and set the interval

11. Check the Scope in the Job Steps tab to make sure your site is included

Process transactions in the Dashboard

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.

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. In the Business Manager main page, go to Merchant Tools > Site Preferences > Custom Site Preferences > Affirm
3. Enter the Affirm Public Key and Affirm Private Key you just retrieved from the Affirm merchant dashboard
4. In the Business Manager go to Administration > Operations > Services > Service Credentials -> Affirm
5. Enter the Affirm Public Key and Affirm Private Key as the User name and Password
6. Set Affirm Mode to Live

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. What should I do if I am on pipelines and seeing an issue where the order has been placed but there is an error when capturing?

Please look in the Affirm Dashboard to see if the order has been voided. If it has, please follow step 5 in section 2.2 of the edit template instructions

2. What should I do if orders are failing order validations from the cartridge? Is it possible to ease up the restrictions?

Yes, to remove all validations except the order total check, please remove the following files:

Replace file: ~/cartridges/int_affirm/cartridge/scripts/basket/affirmBasket.ds with this version : affirmBasket.ds

Replace file: ~/cartridge/scripts/utils/affirmUtils.ds with this version : affirmUtils.ds

3. What should I do if customers are experiencing an error going through the checkout but the loan has been left in the authorized state?

a. Replace file: ~/cartridges/int_affirm/cartridge/scripts/order/affirmOrder.ds with this version : affirmOrder.js
b.1. If you are on pipelines, follow the section 2.2 step 6 in the edit template instructions
b.2 If you are on controllers, follow the section 2.1 step 2.b. in the edit template instructions

4. What should I do if I am are seeing an issue where the promotional price does not match the ALA price?

Replace file: ~/cartridges/int_affirm_controllers/cartridge/templates/default/util/affirmpromo.isml with this version: affirmpromo.isml

5. I noticed that the cartridge should be downloaded from Github, do you have a certified cartridge

We recommend downloading the cartridge from Github because we keep it up to date with the latest bug-fixes. Affirm has a certified cartridge (sign in required) by Salesforce Commerce Cloud, installing the Affirm cartridge requires developer access to your SiteGenesis instance.

Updated a day ago


Salesforce Commerce Cloud


Suggested Edits are limited on API Reference Pages

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