Install and configure Affirm

This guide walks you through configuring Affirm at checkout in Hybris.

Install Affirm on Hybris

Step 1: Download Add-on

Installing Affirm on Hybris requires downloading the add-on, updating localextensions.xml, running the installation command and rebuilding/updating the system.

1. Download source: 

The source will need to be downloaded locally from the repo and then placed into a directory as outlined in the next step.

Step 2: Update localextensions.xml

Place folders in custom folder into custom folder of Hybris Commerce Suite (<HYBRIS_HOME>/bin/custom).

1. Check the presence of <extension name="addonsupport" /> in the localextensions.xml file.
2. Add extension <extension name=" affirmpaymentaddon " />.
3. Add extension <extension name="affirmpaymentcore" />.
4. Add extension <extension name="'affirmpaymentfulfilmentprocess'" />.
5. Check the presence of the target storefront extension.

Step 3: Run the installation command

1. If Hybris is running, stop it. Depending on the server start mode we can use one of following methods to stop Hybris server.

  • If the Hybris server was started with embedded mode, press Ctrl+C to stop Hybris server.
  • If the Hybris server was started with service mode run the following command to stop:
    -Windows: hybrisserver.bat stop\
    -Unix: ./ stop\

2. Go to <HYBRIS_HOME>/bin/platform and run the following command if it was not applied in this terminal:

  • Windows: setantenv.bat\
  • Unix: . ./

3. Go to <HYBRIS_HOME>/bin/platform and run the installation add-on with the command:

ant addoninstall -Daddonnames=" affirmpaymentaddon " -

Step 4: Rebuild the system

Go to <HYBRIS_HOME>/bin/platform and rebuild the system with the command below.

ant clean all

Step 5: Update the system

After the previous step you may need to perform full initialization through Hybris Administration Console (hAC) if this is the first installation of Hybris.

If you have already performed full initialization then you need to update your Hybris system as follows:

1. Open web browser, go to hAC →  Platform →  Update.
2. Deselect the checkbox stating Create essential data".

3. Select the checkboxes next to affirmpaymentcore, affirmpaymentfulfilmentprocess and affirmpaymentaddon.

4. Click on the Update button to update the Hybris system.

Configure Affirm

After installing affirmpaymentaddon successfully, you can now login to Hybris backoffice to set up the Affirm configuration and assign it to specific sites in Hybris.

1. Login with Admin credentials to backoffice. 
2. View the Affirm Payments configuration.


Updating Affirm settings

Changes to the Affirm settings for BaseSite are made within AffirmConfigContainer, which is the container for Affirm-related configurations. AffirmConfigContainer is added as an attribute to BaseSite to support Affirm.

To view or edit the Affirm configuration, within Hybris Backoffice, go to WCMS → Website → ADMINISTRATION → Affirm Config Container for CMSSite.

3. Edit the Affirm Payments Configuration fields.

Affirm Payment mode enabledSet to True to enable Affirm as a payment method.
Sandbox ModeSet to True to enable sandbox mode for development and testing.
Authorize and CaptureSet to True to automatically capture the payment at the time the order is placed. If set to False, the capture will happen during the fulfillment process.
Modal ModeSet to True to enable modal checkout. Leave "False" to use the default, redirect checkout.
VCN modeSet to True only if you are using Affirm's VCN checkout.
Analytics enabledSet to True to enable Affirm to obtain analytics on the order confirmation page
Affirm Private Key (US)Affirm private API Key for US (use Sandbox private key if Sandbox Mode is enabled.
Affirm Public Key (US)Affirm public API Key for US (use Sandbox public key if Sandbox Mode is enabled.
Affirm Private Key (CA)Affirm private API Key for Canada (use Sandbox private key if Sandbox Mode is enabled.
Affirm Public Key (CA)Affirm public API Key for Canada (use Sandbox public key if Sandbox Mode is enabled.
List of Affirm Page ConfigClick to configure Affirm promotional messaging (outlined in the next page)

Configure the Virtual Card Processing

Our virtual card integration assumes you're processing a debit card using your payment processors. By default, it uses the built-in mock payment gateway processor and if you need to integrate Affirm with other payment processors, you can refer to affirm-custom.js file in the Affirm Hybris extension folder for an example. This file consists of vcn SuccessCallbackFunction function which returns the virtual card details after the loan is confirmed. Once you receive the card details, you can then process the payment similar to any other debit/credit card transaction.

If you wish enable VCN checkout, set VCN mode to True in the above Affirm payment configuration.