Oracle Commerce (ATG)

Integrate Affirm into the Oracle Commerce e-commerce platform.


This guide describes how to integrate Affirm into the Oracle ATG web commerce platform so you can provide Affirm as a payment option to your customers. After integrating Affirm, your Oracle 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:

Sandbox development

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

1. Install the Affirm module

Download the Affirm module.

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

ATG module structure



Module description


Build file (based on Oracle Commerce Reference Store)


Sample data (reference)


JSP files used to integrate the module with Oracle Reference Store (reference)


Libraries required for JSON parsing


Module definition


Required SQL for the switching and core schemas


Source code for Java and configuration files


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.

2. Configure Affirm as a payment method

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

Property name





This is the Affirm API version (currently 2).



Set the API URL to (sandbox).



Set the JavaScript URL to (sandbox).



Set to true to enable Affirm checkout option.



If your checkout process automatically captures the charge, set to true.



Enter your sandbox public API key.



Enter your sandbox private API key.



Set to the default MFP Program ID.



Enter the minimum dollar amount value that displays Affirm as a payment option.



Enter the URL where the customer goes after canceling an order.



Enter the URL where the customer goes after completing a loan.



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.

Configure the purchase process

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






<!-- This chain is used to process a Affirm payment group -->
<pipelinechain name="affirmPaymentProcessorChain" transaction="TX_REQUIRED" headlink="createAffirmPaymentInfo">
    <pipelinelink name="createAffirmPaymentInfo" transaction="TX_MANDATORY">
        <processor jndi="/affirm/commerce/payment/processor/CreateAffirmPaymentInfo" />
        <transition returnvalue="1" link="processAffirmPayment" />
    <pipelinelink name="processAffirmPayment" transaction="TX_MANDATORY">
        <processor jndi="/affirm/commerce/payment/processor/ProcessAffirmPayment" />





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.


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.


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

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.

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.

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:

<%-- Import Required Beans --%>
<dsp:importbean bean="/atg/commerce/ShoppingCart"/>
<dsp:importbean bean="/affirm/rules/AffirmRuleDroplet"/>
<dsp:droplet name="AffirmRuleDroplet">
    <dsp:param name="order" bean="ShoppingCart.current"/>
    <dsp:param name="product" param="product"/>
    <dsp:param name="sku" param="sku"/>
    <dsp:param name="pageType" param="pageType"/>
    <dsp:oparam name="output">
        <dsp:getvalueof var="dataPromoId" param="dataPromoId"/>
        <dsp:getvalueof var="ruleName" param="ruleName"/>
        <dsp:getvalueof var="dataAmount" param="dataAmount"/>
            <c:when test="${not empty dataAmount}">
            <p class="affirm-as-low-as" data-promo-id="${dataPromoId}" data-amount="${dataAmount}" data-affirm-color="blue"></p>
            <p class="affirm-as-low-as" data-promo-id="${dataPromoId}" data-affirm-color="blue"></p>
        <!-- Affirm data promo id: ${dataPromoId} -->
        <!-- Affirm rule display name: ${ruleName} -->
    <dsp:oparam name="empty">
    <!-- No affirm rule match -->



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

3. Add Affirm promotional messaging

Add [Affirm promotional messaging]doc:promo-messaging-getting-started)---which includes monthly payment messaging and educational modals---on your product, category, and cart pages by creating and editing rules in the Oracle Business Command Center (BCC). Access the BCC from the main admin page by going to BCC > Project_Name > Affirm Rules. The rules managed by the BCC have the following properties:

Rule ID


This is used internally by ATG and auto-generated. All items must have a unique ID.

Display Name


All rules are queried, and sorted by priority, and then evaluated one at a time. The first rule to match is used.



This is the value that is passed as data-promo-id in the JavaScript call.

Data Promo ID


This is the Financing program ID sent during checkout.

Rule Type


This determines how the rule is evaluated.

Dollar Amount


This sets the threshold for the rule to apply. It can be used with either product_amount or cart_total rule types.



This is the list of product repository items to which a rule applies. If exclusive=true then this option only applies if all products in the cart are in the list.



This is the category to which a rule applies. If exclusive=true, then all items in cart must also be in this category.



If this is true, then a product must be the only item in the cart. If this is set on a category rule, then all other items in the cart must be children of that category.

Start Date


For a time-based rule, the current date must be after the start date.

End Date


For a time-based rule, the current date must be before the end date. If this is left blank, then there is no end date and the rule is assumed to remain valid indefinitely.

Setup a sample default promotional messaging rule and add a Promo ID (contact your Client Success Manager about using Promo ID's).

1. Go to BCC > Project_Name > Affirm Rules.
2. Click Add Affirm Rule.
3. Enter the Display Name.
4. Enter the Data Promo ID provided by Affirm.
5. Select product_amount for Rule Type.
6. Enter 50 into Dollar Amount.
7. Set Exclusive to No.
8. Click Save.

Use Multiple Financing Programs

Multiple Financing Programs (MFPs) allow you to offer custom financing programs to your customers based on rules you define. To learn more about MFPs and how to set them up in Oracle, contact your engagement manager.

4. Create your order management functions

The Affirm module's payment method works in the same way as all ATG payment methods. Therefore, all existing calls that perform standard payment group operations function the same as they do for an order with a credit card payment group. For example, calling PaymentManager.debit for an order using an Affirm payment method will automatically debit the Affirm payment group by making an API call to Affirm for the debit operation.

Sample code for invoking the debit, void, refund, and shipping update methods using a separate form handler is in src/Java/com/affirm/commerce/payment/

5. Add the Confirmation Page function

When a customer completes their purchase, you can send their order and product information to Affirm for A/B testing, which will help you optimize your site. Send this information by adding the Confirmation Page function to your payment confirmation page. We only require orderIdtotalproductId, and quantity for A/B testing.

Click here for all the Confirmation Page function parameters.{
    "paymentMethod": "Visa",
    "orderId": "T12345",
    "total": 3739
}, [{
    "productId": "SKU-1234",
    "quantity": 1
}, {
    "productId": "SKU-5678",
    "quantity": 1

Required function parameters

Order object






The payment method chosen by the customer (e.g., Visa). Maximum 150 characters.



Your internal unique identifier representing the order. Maximum 500 characters.



The total amount of the transaction, including tax and shipping, stated in USD cents (e.g., $100 = 10000).

Product object






Your internal unique identifier representing the product, such as the SKU or an internal database identifier. Maximum 500 characters.



The quantity of the purchased product.

6. 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.

7. Deploy to production

Connect to the live Affirm environment

1. Retrieve your live API keys at
2. In affirm/commerce/payment/, edit the appropriate properties:



Set the API URL to



Set the JavaScript URL to



Enter your live public API key.



Enter your live private API key.

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.

Did this page help you?