Skip to main content

Merchant Help

 

Affirm Merchant Help

Oracle Commerce (ATG) Integration

Overview

The Affirm Oracle Commerce module:

  • Enables the Affirm payment method in your checkout
  • Adds Affirm promotional marketing to your product, category and cart pages
  • Manages orders paid with Affirm

Download 

You can download Affirm Oracle Commerce module from here:


Retrieve keys

  1. Sign in to https://sandbox.affirm.com/dashboard
  2. Retrieve API keys
    1. Hover over the profile icon area at the lower-left of the page.
      Screen Shot 2016-03-22 at 7.56.58 AM-2.png
    2. Click the API Keys link that appears.
      Screen Shot 2016-03-22 at 7.56.20 AM.png
    3. Copy the public, private, and financial product keys.

Installation

The Affirm module is packaged as an ATG module. This structure will be familiar to all users of Oracle Commerce. The directory structure for the non-Versioned module contains:

Directory/File

Description

build.properties

Configuration for the build

build.xml

The build file, modeled after the Oracle Commerce Reference Store build

data

Reference Only: File to hold sample data.

etc

Reference Only: This holds the JSP files that were used for integrating the module with the Oracle Commerce Reference Store.

lib

The libraries required for JSON parsing

META-INF

The module definition file

sql

The required SQL for the switching and core schemas to support the module functionality

src

This holds both the Java source as well as configuration files

Versioned

This is the base of the module for BCC support.

 

The reference implementation of the Affirm integration modules was done using the Oracle Commerce Reference Store. Therefore, the build scripts rely on the Oracle Commerce Reference Store ant build files. The merchant can choose to either keep the module separate from the existing application, or integrate the files in the module into the source code of the existing application. Details for each approach are below.

Maintain a separate module

If the module is going to be kept separate, then the module will at least need to be integrated to the existing build system and built and deployed with the application. This will require mimicking the existing applications build.xml file structure and including those in the separate module. The Affirm integration module's MANIFEST.MF needs to be updated to have ATG-Required: point to the existing main commerce module for the application. There will likely be individual files that need to be updated in this module, so building and deploying it along with the rest of the application is required. Finally, you will need to include the Affirm module in the module list when assembling your EAR file for deployment, and if you are specifying a command-line module list when starting your Oracle Commerce instances, you will need to add this module there as well.

Incorporate module code into existing module

If incorporating the code from the Affirm module into your existing application commerce module, you will simply copy the files in the src, config, and lib directories into your existing commerce module. The MANIFEST.MF will need to be updated to include the JSON libraries that are in the Affirm module's lib folder.

Module Configurations

The following configurations can be made in a centralized configuration component. The nucleus component path is /affirm/commerce/payment/AffirmPaymentConfiguration. Properties are:

Property Name

Type

Description

apiVersion

String

Currently set to 2. This is the Affirm API version

apiUrl

String

Set to sandbox or production URL. Use environment module or server configs to set production URL.
Defaults to sandbox: https://sandbox.affirm.com/api/v2

jsUrl

String

Set to sandbox or production URL. Use environment module or server configs to set production URL.
Defaults to sandbox: https://cdn1-sandbox.affirm.com/js/v2/affirm.js

enabled

boolean

If false, disable display of Affirm offers, and do not show the Affirm payment option at checkout.
Default module config is set to true. 

capturePaymentOnOrderSubmit

boolean

If true, the debit call is made immediately after the authorize call as part of checkout.
Default module config is set to false 

publicAPIKey

String

The public API key

privateAPIKey

String

The private API key

defaultRuleId

String

The repository id of the rule that you want to set as a default rule to show. This rule will not be checked to see if the cart/products qualify. It is intended to apply to any product or cart as the default.

minimumAmount

double

If the amount of the product (product/category pages) or cart (cart/checkout pages) is less than this amount, then we won't render the JSP code to invoke the Affirm Javascript call at all.

affirmCancelUrl

String

The URL to return to when the user cancels on the Affirm site for some reason

affirmConfirmationUrl

String

The URL to return to after the user has completed the loan.

moduleVersion

String

This is set in the module to either be version 11.x or 10.x

These will need to be configured as appropriate for your different environments.

Code Required for Checkout Integration

The purchase process needs to redirect to Affirm at the time of checkout to complete the loan. That process either sends the user back to the billing page, or to a page that will submit the order and run it through the order processing pipeline. The merchant will need to handle these cases using the existing codebase. This front-end integration will be custom for each merchant. Examples of how this was done in the Reference Store can be found in src/Java/com/affirm/commerce/payment/AffirmCheckoutFormHandler.java and src/Java/com/affirm/commerce/payment/AffirmPaymentFormHandler.java.


Configuration

The user is shown the Affirm financing during the browse process, and on the cart page. During checkout, the user can choose to "Checkout with Affirm" on the payment page. That will redirect the user to the Affirm website to finalize the transaction. If successful, Affirm will return a checkout token. The ATG application will then authorize payment using that checkout token, and get back a "Charge ID" to use on future debit, void, and refund transactions.

AffirmUtil

com.affirm.commerce.payment.AffirmUtil
This class handles all the API calls to Affirm, including:

  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. Turn on loggingDebug on this component to see all messages going back and forth from the API.

AffirmPaymentProcessorImpl

com.affirm.commerce.payment.AffirmPaymentProcessorImpl

Implements the AffirmPaymentProcessor interface, and implements the authorize, debit, decreaseAuthorizationForPaymentGroup, and credit methods. Delegates to the AffirmUtil class to make build the JSON data and invoke the API calls.

AffirmProcessingManager

com.affirm.commerce.payment.AffirmProcessingManager

This class handles updating 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 is used to make the direct checkout API call to Affirm, get the checkout_token and redirect URL back, and then send a local redirect with that URL to the Affirm site.

AffirmPaymentFormHandler

com.affirm.commerce.payment.AffirmPaymentFormHandler

This is the form handler that is invoked from the page the user lands on after coming back from the Affirm site. With the Oracle Commerce Reference Store, this is just calling the exact same "processOrderBilling" method that the credit card orders use. The Affirm orders just don't have a credit card, and instead the Affirm Payment Method is used. This is the same way this would be implemented on any Oracle Commerce site.

ProcDebitPayment

This processor is included in the processOrder order processing pipeline chain, and will capture payment immediately after authorization if the AffirmPaymentConfiguration.capturePaymentOnOrderSubmit flag 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 finds the appropriate pipeline chain to run, and invokes that chain. For orders with the AffirmPayment payment group type, the affirmPaymentProcessorChain payment pipeline is invoked. This is a case of the order processing pipeline calling the payment processing pipeline.

JSON Objects for Affirm API calls

The POJO objects that get 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 just 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.

Purchase Process Configurations

The Affirm payment method will be implemented by creating the standard ATG payment objects and processors.

/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
Getting the checkout token back from Affirm

When a user selects the Affirm payment method, we first invoke the Direct Checkout API to get the token. This checkout_id is then used as the checkout_token in the authorize call. The response looks like:

{
"redirect_url":"https://sandbox.affirm.com/checkout/GQ07JK0LZACCQYJB/new/PENWW5OU8P2OJZ9U/",
"checkout_id":"PENWW5OU8P2OJZ9U"
}
Placing the order

The redirect URL that is 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

For the refund, void and capture methods, sample code and JSPs are supplied so each individual client can implement those as required by their implementation. The sample JSPs are located in /etc/crs-jsps/checkout/affirm_orders.jsp.

Affirm Rules

A droplet (com.affirm.rules.AffirmRuleDroplet) will take in order and product params and return a data-promo-id and a data-amount value to be used when invoking the Affirm Javascript to get the promotional messaging. 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.

AffirmRuleDroplet - com.affirm.rules.AffirmRuleDroplet

This is the droplet to put on any page that needs to show the Affirm offer. A sample JSP fragment to invoke the droplet and display the Affirm messaging would look like this:

<%-- 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 where all the logic for evaluating the rules resides.


Affirm Promotional Messaging

Monthly payment messaging and modal on product, category and shopping cart pages are enabled by default. Monthly payment messaging and modal can be customized by adding a defaultRuleId and mapping it to a rule in BCC. Affirm Rules can be managed in the Oracle Commerce application. These are set up in the ProductCatalog repository. Affirm Rules can be created or edited in Oracle Commerce BCC: BCC -> Project_Name -> Affirm Rules.

Rule properties - The BCC-managed rules have the following properties:

Property Name Type Description
Rule ID string 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 int This is the value that is passed as the "data-promo-id" in the Javascript call to Affirm
Data promo ID string This is the Financing program id sent during checkout
Rule Type enumerated This determines how the rule is evaluated. See below for details
Dollar Amount double This can be used with either product_amount or cart_total rule types, and sets the threshold for the rule to apply
Products List The list of product repository items that a rule applies to. If "exclusive=true" then this option only applies if all products in the cart are in the list.
Category RepositoryItem The category that a rule applies to. 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 end 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.

To set up a default rule and add a data-promo-id:

  1. Visit BCC -> Project_Name -> Affirm Rules
  2. Add Affirm Rule and enter the properties:
    • Display Name (Ex: Default data-promo-id)
    • Data Promo ID (data-promo-id provided by Affirm)
    • Rule Type - product_amount
    • Dollar Amount - 50
    • Exclusive - No
  3. Click Save

data-promo-id.png

 

Multiple Financing Programs

Multiple Financing Programs (MFPs) allows you to selectively offer a specific custom financing program to consumers based on product or cart attributes that are defined in the Affirm Rules in BCC. MFP setup is optional and the data-promo-id and financing program ID values are provided by Affirm. For more information, please visit Oracle ATG multiple Financing Programs documentation


Order Processing

Handling void/refund/capture operations

The module adds a payment method in the standard way all ATG payment methods work. This means that all existing calls that perform standard payment group operations will work the same as they do for an order with a credit card payment group. For example, calling PaymentManager.debit on an order with an Affirm payment method will automatically debit the Affirm payment group by making the API call to Affirm for the debit operation. Sample code exists in the module for invoking the debit, void, refund, and shipping update methods using a separate form handler. These can be found in the src/Java/com/affirm/commerce/payment/AffirmProcessingFormHandler.java file.


Test your Affirm configuration

Test your configuration to ensure that everything is working before you go live. Email  merchanthelp@affirm.com with a link to your test site so that we can verify your configuration and provide you with production keys.

  1. Add an item to the cart on your test site.
  2. Proceed to checkout.
  3. During checkout, enter valid U.S. addresses and mobile-phone information. Affirm cannot test your configuration if the address or phone information is fake.
  4. Select Affirm as the payment option.
  5. Proceed to Affirm's testing environment checkout.

Note: The URL https://sandbox.affirm.com indicates that you are in the testing environment.

6. When prompted for your security PIN, enter 1234.

7. Select terms.

8. Confirm your loan.

 

9. Wait to ensure that you have been redirected to your confirmation page.

10. Verify that the transaction appears in your platform's admin panel and on  sandbox.affirm.com/dashboard

Note: When a customer completes checkout with Affirm as the payment method, Affirm authorizes a charge for the amount of the order. The charge appears in a pending state on the customer’s Affirm account. Authorized transactions expire if they are not captured before the capture deadline. The default capture deadline is specified in your partnership agreement with Affirm. If you did not specify your authorization-period requirements because of inventory, pre-orders, or shipping time in your onboarding form, please email merchanthelp@affirm.com for help with completing this process.


Go live with Affirm financing

After you verify that your configuration is working properly in the Affirm Sandbox environment, your Affirm Client Success Manager will activate your Affirm Live environment access. This will allow you to sign into the Live version of the Merchant Dashboard, as well as access your Live API keys.

Retrieve Live API keys

  1. Go to the API keys page in the Affirm dashboard.
  2. Retrieve your live API keys.
  3. Enter the live API keys into your integration/platform.

Note: The email address that you use to access the dashboard must be registered as a Google account. Check to see if your existing email address is a Google account or create a new Google account. You can link your existing work email address to a Google account by signing up without Gmail.

Update Affirm URL and script references

  1. Affirm JS URL: https://cdn1.affirm.com/js/v2/affirm.js
  2. Affirm API base URL: https://api.affirm.com