## Install Affirm on Oracle Commerce (ATG)

Download the Affirm module.

  • [Version 11.x](🔗)

  • [Version 10.x](🔗)

The Affirm module is a packaged ATG module whose structure will be familiar to Oracle Commerce users.

**ATG module structure**

**build.properties** Module description
**build.xml** Build file (based on Oracle Commerce Reference Store)
**/data** Sample data (reference)
**/etc** JSP files used to integrate the module with Oracle Reference Store (reference)
**/lib** Libraries required for JSON parsing
**/META-INF/MANIEST.MF** Module definition
**/sql** Required SQL for the switching and core schemas
**/src** Source code for Java and configuration files
**/Versioned** Base module for Business Control Center (admin)

Since the reference implementation of the Affirm module is based on the Oracle Commerce Reference Store, the build scripts rely on the Oracle Commerce Reference Store build files. You can choose to either keep the module separate from your existing store or integrate the module files into the source code of your existing store.

**Maintain a separate module**

If you choose to maintain Affirm as a separate module, you'll still need to integrate it into your existing build system so that the Affirm module deploys with your store's main commerce module. Mimic your existing store module's build.xml file structure and include it in the Affirm module. Update ATG-Required in [MANIFEST.MF](🔗) to point to your store's existing module. You'll likely need to update individual files in the Affirm module, so you're required to build and deploy it with the rest of the store. Finally, include the Affirm module in the module list when assembling your EAR file for deployment. If you're specifying a command-line module list when starting your Oracle Commerce instances, then add this module there as well.

**Integrate the module**

If you choose to integrate the Affirm module files into your existing store commerce module, then copy the files in the /src, /config, and /lib directories into your existing commerce module. Update the [MANIFEST.MF](🔗) to include the JSON libraries in the [Affirm module's /lib folder](🔗).

## Configure Affirm

The following table includes the parameters found in affirm/commerce/payment/AffirmPaymentConfiguration.properties. Edit each parameter to configure Affirm as a payment method.

Property nameTypeDescription
**apiVersion**_string_This is the Affirm API version (currently 2).
**apiUrl**_string_Set the API URL to https://sandbox.affirm.com/api/v2 (sandbox).
**jsUrl**_string_Set the JavaScript URL to https://cdn1-sandbox.affirm.com/js/v2/affirm.js (sandbox).
**enabled**_boolean_Set to true to enable Affirm checkout option.
**capturePaymentOnOrderSubmit**_boolean_If your checkout process automatically captures the charge, set to true.
**publicAPIKey** _string_Enter your sandbox public API key.
**privateAPIKey** _string_Enter your sandbox private API key.
**defaultRuleId** _string_Set to the default MFP Program ID.
**minimumAmount** _double_Enter the minimum dollar amount value that displays Affirm as a payment option.
**affirmCancelUrl** _string_Enter the URL where the customer goes after canceling an order.
**affirmConfirmationUrl** _string_Enter the URL where the customer goes after completing a loan.
**moduleVersion** _string_Set to either version 11.x or 10.x.

Develop your front-end integration for when a customer completes a loan. Be sure to handle the use cases for sending a customer back to the billing page or to a page that submits the order and runs it through an order processing pipeline in your existing store's codebase. These will be custom integrations for each merchant. You can review examples from the Reference Store.

  • [src/Java/com/affirm/commerce/payment/AffirmCheckoutFormHandler.java](🔗)

  • [src/Java/com/affirm/commerce/payment/AffirmPaymentFormHandler.java](🔗)

**Configure the purchase process**

Create standard ATG payment objects and processors to configure the Affirm payment method.






**Review Affirm module libraries and processes**

The following describes how different libraries and processes work in the Oracle ATG Affirm module. While it is mostly descriptive, there are some references to configurations you can make.

**AffirmUtil** `com.affirm.commerce.payment.AffirmUtil`

This class handles the following API calls to Affirm:

  • Direct Checkout API

  • Authorization

  • Void Authorization

  • Capture

  • Refund (and partial refund)

  • Update Shipping (tracking code, carrier, address)

All code uses a shared method for making the call to Affirm. Enable loggingDebug in this class to view all messages going to and from the API.



This class implements the AffirmPaymentProcessor interface and implements the authorize, debit, decreaseAuthorizationForPaymentGroup, and credit methods. It delegates to AffirmUtil to build the JSON data and invoke the API calls.

**AffirmProcessingManager** `com.affirm.commerce.payment.AffirmProcessingManager`

This class updates the shipping details. This is the only operation that happens outside of the Oracle Commerce payment processing pipeline.

**AffirmCheckoutFormHandler** `com.affirm.commerce.payment.AffirmCheckoutFormHandler` This class makes the direct checkout API call to Affirm, receives the checkout token and redirect URL, and then sends a local redirect with that URL to the Affirm site.

**AffirmPaymentFormHandler** `com.affirm.commerce.payment.AffirmPaymentFormHandler` The page the user lands on after returning from the Affirm site invokes this form handler. With the Oracle Commerce Reference Store, this calls the exact same "processOrderBilling" method that credit card orders use. The difference is that Affirm orders use the Affirm payment method instead of credit cards. Your Oracle site should implement this in the same way.

**ProcDebitPayment** This processor is included in the` processOrder` order processing pipeline chain. It captures payment immediately after authorization if `AffirmPaymentConfiguration.capturePaymentOnOrderSubmit` is set to true. This processor delegates to the out-of-the-box `PaymentManager`, which calls debit on each payment group in the order. The `PaymentManager` then finds and invokes the appropriate pipeline chain to run. Orders with the AffirmPayment payment group type invoke the `affirmPaymentProcessorChain` payment pipeline. This is an example of an order processing pipeline calling the payment processing pipeline.

**JSON Objects for Affirm API calls** The POJO objects, which are transformed to JSON, are located in the com.affirm.commerce.payment.json package. The objects included are:

  • `AffirmOrder`

  • `AffirmItem`

  • `AffirmMetaData`

  • `AffirmAddress`

  • `Billing`

  • `Config`

  • `Discount`

  • `Merchant`

  • `Name`

  • `Shipping`

  • `UpdateShipment`


This is sample code for invoking the void, capture, refund and shipment update API calls. Each Oracle Commerce implementation will have a different entry point for these operations.

**Placing the order**

The redirect URL sent to Affirm (`AffirmPaymentConfiguration.affirmConfirmationUrl`) is currently set to the `checkout/affirm_post.jsp`. That page immediately invokes the `AffirmPaymentFormHandler` to process the order.

**Order Management After Purchase**

The file `/etc/crs-jsps/checkout/affirm_orders.jsp` includes sample code for the refund, void and capture methods.

**Affirm Rules**

A droplet (`com.affirm.rules.AffirmRuleDroplet`) will receive order and product parameters and then return a `data-promo-id` and a `data-amount` value for the promotional messaging JavaScript. The business logic in the `AffirmRuleManager` will determine the highest priority rule that the user qualifies for, and return the corresponding `data-promo-id` for that rule.


Place this droplet on any page that will show the Affirm offer. Here is a sample JSP fragment to invoke the droplet and display the Affirm messaging:



This is class includes all the logic for evaluating the rules.