Skip to main content

Merchant Help

 

Affirm Merchant Help

Oracle Commerce (ATG) Integration

Overview

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

The integration steps are:

  1. Install the Affirm module
  2. Configure Affirm as a payment method
  3. Add Affirm promotional messaging
  4. Create your order management functions
  5. Add the Confirmation Page function
  6. Test your integration
  7. Deploy to production

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

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 ▼
File or Directory Description
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.

2. Configure Affirm as a payment method

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

Property Name Type Description
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.

Configure the purchase process

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

/atg/commerce/order/OrderTools.properties

beanNameToItemDescriptorMap+=\
com.affirm.commerce.payment.AffirmPayment=affirmPaymentGroup
paymentTypeClassMap+=\
affirmPayment=com.affirm.commerce.payment.AffirmPayment

 /atg/commerce/payment/PaymentManager.properties

paymentGroupToChainNameMap+=\
com.affirm.commerce.payment.AffirmPayment=affirmPaymentProcessorChain

/atg/commerce/payment/paymentpipeline.xml

<pipelinemanager>
<!-- 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>
    <pipelinelink name="processAffirmPayment" transaction="TX_MANDATORY">
        <processor jndi="/affirm/commerce/payment/processor/ProcessAffirmPayment" />
    </pipelinelink>
</pipelinechain>
</pipelinemanager>

/affirm/commerce/payment/processor/CreateAffirmPaymentInfo.properties

$class=com.affirm.commerce.payment.ProcCreateAffirmPaymentInfo
$scope=global
affirmPaymentInfoClass=com.affirm.commerce.payment.AffirmPaymentInfo

/affirm/commerce/payment/processor/ProcessAffirmPayment.properties

$class=com.affirm.commerce.payment.ProcProcessAffirmPaymentImpl
$scope=global
affirmManager=/affirm/commerce/payment/AffirmPaymentUtil
orderTools=/atg/commerce/order/OrderTools

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:

  1. Direct Checkout API
  2. Authorization
  3. Void Authorization
  4. Capture
  5. Refund (and partial refund)
  6. 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.

AffirmPaymentProcessorImpl ▼

com.affirm.commerce.payment.AffirmPaymentProcessorImpl

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
AffirmProcessingFormHandler ▼
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.
com.affirm.rules.AffirmRuleDroplet ▼
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:choose>
            <c:when test="${not empty dataAmount}">
            <p class="affirm-as-low-as" data-promo-id="${dataPromoId}" data-amount="${dataAmount}" data-affirm-color="blue"></p>
        </c:when>
        <c:otherwise>
            <p class="affirm-as-low-as" data-promo-id="${dataPromoId}" data-affirm-color="blue"></p>
        </c:otherwise>
        </c:choose>
        <!-- Affirm data promo id: ${dataPromoId} -->
        <!-- Affirm rule display name: ${ruleName} -->
    </dsp:oparam>
    <dsp:oparam name="empty">
    <!-- No affirm rule match -->
    </dsp:oparam>
</dsp:droplet>
AffirmRuleManager ▼

com.affirm.rules.AffirmRuleManager

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

3. Add Affirm promotional messaging

Add Affirm promotional messaging—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:

Property Name Type Description
Rule ID String This is used internally by ATG and auto-generated. All items must have a unique ID.
Display Name String All rules are queried, and sorted by priority, and then evaluated one at a time. The first rule to match is used.
Priority Integer This is the value that is passed as data-promo-id in the JavaScript call.
Data Promo ID String This is the Financing program ID sent during checkout.
Rule Type Enumerated This determines how the rule is evaluated.
Dollar Amount Double This sets the threshold for the rule to apply. It can be used with either product_amount or cart_total rule types.
Products List 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.
Category RepositoryItem This is the category to which a rule applies. If "exclusive=true", then all items in cart must also be in this category.
Exclusive Boolean 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 Timestamp For a time-based rule, the current date must be after the start date.
End Date Timestamp 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

Screen Shot 2018-07-30 at 12.33.09 PM.png

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/AffirmProcessingFormHandler.java.

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 orderId, total, productId, and quantity for A/B testing.

Click here for all the Confirmation Page function parameters.

affirm.analytics.trackOrderConfirmed({
    "orderId": "T12345",
    "total": 3739
}, [{
    "productId": "SKU-1234",
    "quantity": 1
}, {
    "productId": "SKU-5678",
    "quantity": 1
}]);

Required function parameters

Order object

Parameter Type Description
orderId string Your internal unique identifier representing the order. Maximum 500 characters.
total integer The total amount of the transaction, including tax and shipping, stated in USD cents (e.g., $100 = 10000).

Product object

Parameter Type Description
productId string Your internal unique identifier representing the product, such as the SKU or an internal database identifier. Maximum 500 characters.
quantity integer The quantity of the purchased product.

6. Test your integration

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.

7. Deploy to production

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 Client Success Manager to coordinate this test.

Connect to the live Affirm environment

  1. Retrieve your live API keys at https://affirm.com/dashboard/#/apikeys
  2. In affirm/commerce/payment/AffirmPaymentConfiguration.properties, edit the appropriate properties:
Property Name Type Description
apiUrl String Set the API URL to https://api.affirm.com/api/v2.
jsUrl String Set the JavaScript URL to https://cdn1.affirm.com/js/v2/affirm.js.
publicAPIKey String Enter your live public API key.
privateAPIKey String 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.