Install Affirm on SFCC

Country Availability

Country List ⬇️

USA

Canada

Prerequisites

• Review Salesforce Commerce Cloud (SFCC).

Step 1: Import the Affirm cartridge

📘

Note: These steps work in any IDE, though we use Cursor for this guide.

1. Install Prophet Debugger in Cursor:

   1. Open Cursor.
   2. Click the Extensions icon in the left sidebar.
   3. Locate the Prophet Debugger and click Install.

2. Open the cartridge folder in Cursor:

   1. In GitHub, download the Affirm cartridge.

   2. Unzip the file.

   3. In Cursor, click File > Open Folder.

   4. Select the Cartridges directory and click Open.

      

3. Create dw.json (sandbox connection config):

   1. In the root of the folder you opened, create a file titled dw.json and include the following:
      JSON

      {
          "hostname": "your-sandbox-hostname.demandware.net",
          "username": "your-bm-username",
          "password": "your-bm-password",
          "code-version": "YOUR_CODE_BASE_NAME"
      }

      • Hostname: Your SFCC sandbox URL (without https://).
      • Username: Your Business Manager login.
      • Password: Your Business Manager login.
      • Code-version: The code version name that you created or activated in Business Manager.
   2. Then, save the file to automatically activate the Prophet Debugger.
   
   

   🚧

   Add dw.json to your .gitignore because it contains credentials.

4. Upload/sync the cartridge:

   1. In Cursor, click View > Command Palette.

   2. Enter “Prophet” and select Prophet: Enable Upload. Prophet uploads your cartridge files to the sandbox.

      

   3. (Optional) You can monitor progress in the Output panel by selecting View > Output > Prophet Debugger.

   📘

   To do a full clean upload of the cartridge in your IDE’s project at any time, you can select Prophet: Clean Project/Upload All in the Command Palette.

5. Verify cartridge is on the server:

   1. Log in to Business Manager.
   2. Go to Administration > Site Development > Code Deployment.
   3. Find your code version and confirm the cartridge files appear under it.

Step 2: Import the XML files

Next, you must import the XML files from the Metadata directory of the downloaded cartridge:

1. In the Business Manager, go to Administration > Site Development > Site Import & Export.
2. In the Import section, click Choose File and select affirm.zip from the metadata folder.

3. Click Upload.
4. After the upload completes, select instance/affirm.zip from the archive list.
5. Click Import.

📘

Note

Configure your library ID in the library.xml file in the metadata folder. Currently, 'RefArchSharedLibrary' is the default.

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

5. In Business Manager, go to Merchant Tools > Site Preferences > Custom Preferences.
6. Verify that the **Site Preferences **group was created with:
   1. ID = AFFIRM_PAYMENT
   2. Name = Affirm
7. Verify that the Payment Method was created with an ID of Affirm and a name of Affirm. Then, enable the Affirm payment method.
8. (Optional) To add an image or text for your payment method, you can update the content asset affirm-payment-method.

📘

Note

SFCC has required AppExchange partners to remove any dynamically loaded Javascript files from content delivery networks (CDNs). As such, Affirm.js, which is a browser-side Javascript library served via CDN, is replaced by a static copy. To prevent Affirm.js from going out-of-date and to ensure that Affirm.js receives critical updates, we recommend using the CDN route to embed the script into the storefront pages.

Step 3: Enable the Affirm payment processor

1. In the Business Manager, go to Merchant Tools > Ordering > Payment Processors.

2. Click NEW.

3. Verify that the Site Preferences group was created with:

   1. ID = AFFIRM_PAYMENT
   2. Name = Affirm

4. Verify that the Site Preferences Group exists with:

   1. ID = AFFIRM_PAYMENT
   2. Name = Affirm

5. Go to Merchant Tools > Ordering > Payment Methods to verify a payment method exists with:

   1. ID = Affirm
   2. Name = Affirm

6. Click the new AFFIRM_PAYMENT processor > Settings.

7. Select the Affirm Online Status checkbox to enable it.

   

8. (Optional) You can add an image or text for the payment method by updating the asset affirm-payment-method.

Step 4: Custom code

You must update your site's template files to add promotional messaging and optimize checkout functionalities. We've included detailed instructions for these custom enhancements:

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

Step 5: Configure the Virtual Card for processing

1. Sign in to Business Manager and go to Merchant Tools > Site Preferences > Custom Site Preferences > Affirm.
2. Set the Affirm Virtual Card Integration to Enabled.
3. Add the VCN payment instrument with last part of hook name (e.g., BASIC_CREDIT).

(Optional) Integrate with other payment processers

Our virtual card integration assumes you're processing a debit card using your payment processors. By default, it uses the BASIC_CREDIT processor. If you need to integrate Affirm with other payment processors, you can follow these steps:

1. Set site preference attribute VCN Payment Instrument with the last part of hook name (e.g., CYBERSOURCE_CREDIT_CARD).
2. Register the new hook handler for extension point dw.int_affirm.payment_instrument.%PI%, where %PI% is payment instrument value you've set in the previous step. (e.g., dw.int_affirm.payment_instrument.CYBERSOURCE_CREDIT_CARD). By default it is dw.int_affirm.payment_instrument.BASIC_CREDIT defined inside /cartridge/scripts/hooks.json.
3. Implement a method "add" of this hook handler, which takes basket as the parameter.
   1. The method returns a newly created payment instrument.
   2. Credit card information can be extracted from HttpParametersMap and a reference implementation can be found in cartridge/scripts/payment/instrument/BASIC_CREDIT.js).
   3. Lastly, check Credit/Debit Cards to verify that Visa Card is enabled.

What’s Next?

• Configuring Affirm for SFCC