This guide describes how to integrate Affirm into your Hybris platform so that you can provide Affirm as a payment option to your customers. After integrating Affirm, your Hybris 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:
- The transaction flow when buying with Affirm
- Your current checkout process to understand how Affirm will affect operations and customer experience
- Settlement reports to know how to reconcile transactions with the deposits into your bank account
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.
Installing Affirm on Hybris requires downloading the add-on, updating localextensions.xml, running the installation command and rebuilding/updating the system.
1. Download source here:
2. Place folders in custom folder into custom folder of Hybris Commerce Suite (
1. Check the presence of
<extension name="addonsupport" /> in the l
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
Run installation command
1. If Hybris is running, stop it. Depending on the server start mode we can use one of following method 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:
2. Go to
<HYBRIS_HOME>/bin/platform and run the following command if it was not applied in this terminal:
- Go to
<HYBRIS_HOME>/bin/platformand run the installation add-on with the command:
ant addoninstall -Daddonnames=" affirmpaymentaddon " - DaddonStorefront.yacceleratorstorefront="yacceleratorstorefront"
Rebuild the system
<HYBRIS_HOME>/bin/platform and rebuild the system with the command: ant clean all
ant clean all
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
4. Click on the Update button to update the Hybris system.
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 Affirm Payments configuration
Updating Affirm settings
Changes to the Affirm settings for BaseSite are made within AffirmConfigContainer, which is the container 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 Affirm Payments Configuration Fields
|Affirm Payment mode enabled||Set to |
|Sandbox Mode||Set to |
|Authorize and Capture||Set to |
|Modal Mode||Set to |
|VCN mode||Set to |
|Analytics enabled||Set to |
|Affirm Private Key||Affirm private API Key (use Sandbox private key if Sandbox Mode is enabled.|
|Affirm Public Key||Affirm public API Key (use Sandbox public key if Sandbox Mode is enabled.|
|List of Affirm Page Config||Click to configure Affirm promotional messaging (outlined in the next section)|
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. Click here for information about adding Affirm promotional messaging.
1. Access the Affirm configuration outlined in section 2, go to WCMS → Website → ADMINISTRATION → Affirm Config Container for CMSSite
2. Double click on the Affirm Page Config
3. To enable Affirm promotional messaging is enabled, set Affirm Promotion Flag to
True and click Save. Click on a value under List of Affirm Promotion Message for additional configuration.
4. Scroll down to the administration settings and click Save to save any edits.
|Affirm Promotion Message Code||Promotion message code for these settings (should not be edited)|
|Affirm Promotion Page Type||Values are "CATEGORY", "PDP" (for product page), and "CART" page. This value refers to the page that this configuration is for.|
|AffirmPromoMessage.affirmPromotionMessage||Edit this class to update attributes for Affirm's promotional messaging.|
Configure price threshold for Affirm (optional)
It is possible to restrict Affirm as a payment option on the checkout page based on minimum or maximum cart totals. If you want Affirm to be displayed for all cart thresholds, this step can be skipped.
1. To edit /view thresholds login to Backoffice with admin credentials and navigate to Price Settings -> Payment Modes and select affirm. Select the Administration tab and scroll down to Thresholds settings.
2. To edit threshold, select the
PaymentThreshold object from the list. Select
True to set the minimum threshold and
False to set the maximum threshold. Set the threshold in the Thresdhold amount field.
Processing orders (void, refund, and partial refund) in Hybris updates the order status in the Affirm dashboard. While you can process orders in the dashboard, we strongly recommend using Hybris BackOffice to keep order status synced with Affirm.
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.
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 [email protected] to coordinate this test.
Connect to the live Affirm environment
1. Retrieve your live API keys at https://affirm.com/dashboard/#/apikeys
2. Access the Affirm configuration outlined in section 2, go to WCMS → Website → ADMINISTRATION → Affirm Config Container for CMSSite
3. Set the Sandbox Mode to
False (1) and update the Affirm Private Key (2) and Public Key with the live API keys from your dashboard. Click SAVE.
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.
Updated 2 months ago