Skip to main content

Merchant Help

 

Affirm Merchant Help

Modal Checkout

Overview

Modal checkout is a more fluid checkout experience for customers on all platforms and devices. The modal checkout flow also enables client-side callbacks so that you can receive the checkout confirmation from our JavaScript runtime instead of HTTP.

Implementation

Modal Checkout is enabled by:

  1. Adding a specific metadata flag to your checkout object.
  2. If you want to use JS callbacks for cancel/confirm actions at runtime, you will need to define those callback functions as well.

Add checkout object parameter

Modal checkout is enabled by adding a new parameter to the checkout object metadata:

{
    ...,
      "metadata": {
        "mode":        "modal"
      },
    ...
}
mode
optional enum. Set to "modal" to enable the modal checkout flow. If a other/blank/null value is passed, the default, redirect checkout flow will be used.

 

Define callback functions

Note: This step is optional.

The affirm.checkout.open() function will accept an argument object where you can define a success and failure callback function.

{
    onFail: function(){yourAffirmCancelFunction()},
    onSuccess: function(succes_object){yourAffirmSuccessFunction(succes_object)}
}
onFail
optional function. Called when the user exits from, cancels, or is declined in the Affirm checkout flow
onSuccess
optional function. Called when the user confirms their approved Affirm loan. A success_object is passed through to your success function, which contains the checkout_token.

Initiate checkout

Call affirm.checkout.open() and the modal checkout flow will appear in a lightbox modal above your page contents.

affirm.checkout.open({
    onFail: function(){console.log("User cancelled the Affirm checkout flow")},
    onSuccess: function(a){console.log("Affirm checkout successful, checkout token is: " + a.checkout_token)};
});

Please note there are Safari-specific nuances when around using a network response to trigger Affirm checkout

Design

Screen Shot 2017-09-21 at 10.14.28 AM.pngScreen Shot 2017-09-21 at 10.14.13 AM.png

Screen Shot 2017-09-21 at 10.14.13 AM.png

Example Code

 

 

Example checkout object

affirm.checkout({

      "merchant": {
        "user_confirmation_url":    "https://merchantsite.com/confirm",
        "user_cancel_url":          "https://merchantsite.com/cancel",
        "user_confirmation_url_action": "GET",
        "name": "Your Customer-Facing Merchant Name"
      },
      
      "metadata": {
        "mode":        "modal",
      },
      
      "shipping":{
        "name":{
          "first":"Joe",
          "last":"Doe"
        },
        "address":{
          "line1":"633 Folsom St",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94107",
          "country":"USA"
        },
        "phone_number": "4151234567",
        "email": "joedoe@123fakestreet.com"
      },
      "billing":{
        "name":{
          "first":"Joe",
          "last":"Doe"
        },
        "address":{
          "line1":"633 Folsom St",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94107",
          "country":"USA"
        },
        "phone_number": "4151234567",
        "email": "johndoe@123fakestreet.com"
      },
      "items": [{
        "display_name":         "Awesome Pants",
        "sku":                  "ABC-123",
        "unit_price":           1999,
        "qty":                  3,
        "item_image_url":       "http://merchantsite.com/images/awesome-pants.jpg",
        "item_url":             "http://merchantsite.com/products/awesome-pants.html"
      }],

      "discounts": {
        "RETURN5": {
          "discount_amount":    500,
          "discount_display_name": "Returning customer 5% discount"
        }
      },
      
      "shipping_amount":        1000,
      "tax_amount":             500,
      "total":                  6997

  });

Notes

Stringing network requests and checkout initiation

When implementations which rely on an asynchronous HTTP response to trigger Affirm checkout, Safari users with pop-up blocking enabled may see a 'Continue' button initially instead of the Affirm checkout window. This does not block the isse of Affirm checkout, it just adds one additional click to the checkout process for the customer. Thankfully, there are ways to workaround this issue, and it only affects a portion of all users.

To workaround this issue, you can make any network requests which trigger Affirm synchronous instead asynchronous. 

Most all Javascript HTTP/AJAX libraries support synchronous mode, including the native XMLHTTPRequest method.

var xhttp = new XMLHttpRequest();
//xhttp.open(method, page, async)
xhttp.open(POST, 'https://site.com/somepage/', false); 

Please use the help link at the bottom, or reach out to your technical integration contact if you have any questions about this browser behavior and available workarounds.

Third-party cookies

Modal checkout functionality relies on third-party cookies being allowed/enabled within your browser's Privacy and Security settings. If third-party cookies are blocked, and the Affirm.com cookie is not already present on the user's machine, the Affirm checkout flow will appear in a pop-up (new) window instead of a modal (inline) window.

To make sure third-party cookies are allowed, please check your browser settings:

  • Chrome:
    • Preferences -> Advanced -> Content Settings -> Cookies
      Screen Shot 2018-05-14 at 9.55.40 AM.png
  • Safari:
    • Preferences -> Privacy -> 'Cookies and website data': 'Always allow'
      Screen Shot 2018-05-14 at 9.58.14 AM.png