Skip to main content

Merchant Help

 

Affirm Merchant Help

Initiate Checkout

[Affirm.js] affirm.checkout().post
Embed Affirm's JS runtime code

<script>
  _affirm_config = {
    public_api_key:  "XXXXXXXXXXXXXXX",
    script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js"
  };
  (function(l,g,m,e,a,f,b){var d,c=l[m]||{},h=document.createElement(f),n=document.getElementsByTagName(f)[0],k=function(a,b,c){return function(){a[b]._.push([c,arguments])}};c[e]=k(c,e,"set");d=c[e];c[a]={};c[a]._=[];d._=[];c[a][b]=k(c,a,b);a=0;for(b="set add save post open empty reset on off trigger ready setProduct".split(" ");a<b.length;a++)d[b[a]]=k(c,e,b[a]);a=0;for(b=["get","token","url","items"];a<b.length;a++)d[b[a]]=function(){};h.async=!0;h.src=g[f];n.parentNode.insertBefore(h,n);delete g[f];d(g);l[m]=c})(window,_affirm_config,"affirm","checkout","ui","script","ready");
 // Use your live public API Key and https://cdn1.affirm.com/js/v2/affirm.js script to point to Affirm production environment.
</script>

Note: replace the 'public_api_key' value with your own public API key. The API key must match the Affirm-environment you're referencing ('sandbox' or 'live').

Once the Affirm JS is initialized, the affirm.checkout methods are made available:

  • affirm.checkout({ }) - Stores the checkout object and is used for the checkout request payload.
  • affirm.checkout.post() - Sends the checkout object via POST request.
Define runtime parameters

The Affirm environment that's used is determined by the Affirm script URL that's defined in the _affirm_config.script:

var _affirm_config = {
    public_api_key:  "XXXXXXXXXXXXXXX",
    script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js"
  };
Checkout object

This is the data payload that gets POSTed to the Affirm API to initialize checkout.

affirm.checkout({

      "merchant": {
        "user_confirmation_url":    "https://merchantsite.com/confirm",
        "user_cancel_url":          "https://merchantsite.com/cancel"
        "user_confirmation_url_action": "POST",
        "name": "Your Customer-Facing Merchant Name"
      },
      "shipping":{
        "name":{
          "first":"John",
          "last":"Doe"
          // You can include the full name instead
          // "full" : "John Doe"
        },
        "address":{
          "line1":"325 Pacific Ave",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94112",
          "country":"USA"
        }
        "phone_number": "4151234567",
        "email": "johndoe@gmail.com"
      },
      "billing":{
        "name":{
          "full":"John Doe"
        },
        "address":{
          "line1":"325 Pacific Ave",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94112",
          "country":"USA"
        }
        "phone_number": "4151234567",
        "email": "johndoe@gmail.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"
        },
        "PRESDAY10": {
          "discount_amount":    1000,
          "discount_display_name": "President's Day 10% off"
        }
      },

      "metadata": {
        "shipping_type":        "UPS Ground",
        "entity_name":          "internal-sub_brand-name",
        "platform_name":        "your-platform-name"
      },

      "order_id":               "JKLMO4321",

      "shipping_amount":        1000,
      "tax_amount":             500,
      "total":                  6997

  });
 
merchant
required object. Define the URLs for the two results of a checkout attempt and an optional external name.
shipping
required object. Customer contact information.
billing
optional object. Customer contact information.
items
required list. A list of item objects.
discounts
optional hash. A hash of coupon codes to discount objects. If discounts are passed, they must have a name and positive integer dollar amount.
metadata
optional object. A hash of keys to values for any metadata to be passed into checkout and stored. 'entity_name' is a protected key, and will show up in your settlement reporting.
order_id
optional string. Your internal order id. This is stored for your own future reference.
shipping_amount
required integer. The total shipping amount; Defaults to 0.
tax_amount
required integer. The total tax amount computed after all discounts have been applied; Defaults to 0.
total
required integer. The total amount of the checkout. This determines the total amount charged to the user.

 

Merchant object

The merchant object contains the user_confirmation_url and user_cancel_url, which represent the two possible outcomes of the checkout attempt. The user goes to the confirmation_url if the user is approved and confirms their loan. The user goes to the cancel_url in all other cases (voluntary cancel, credit decline, identity verification issue, etc.). 

"merchant": {
    "user_confirmation_url":    "https://merchantsite.com/confirm",
    "user_cancel_url":          "https://merchantsite.com/cancel",
    "user_confirmation_url_action": "POST", // or "GET"
    "name":          "External Company Name"
     },
user_confirmation_url
required url. URL that the customer is sent to if they successfully complete the Affirm checkout flow. 
A checkout_token will be sent to this URL in the POST request, and that checkout_token should be used to authorize the charge before the user is redirected to the order confirmation page.
Analytics tags are other query string parameters can be persisted here as well. Read more here.
user_cancel_url
required url. URL that the customer is sent to if the customer exits the Affirm checkout flow.
This is the same if the user voluntarily cancels or closes the window before completion, or if the user is denied. You should setup the cancel_url to be the checkout payment page, and you can also append analytics tags to the URL to help you identify who you may want to reach out to about alternative payment methods or reapplying. 
Analytics tags are other query string parameters can be persisted here as well. Read more here.
user_confirmation_url_action
optional string. Accepted values are: 'GET', 'POST'. Defaults to 'POST'. Read more here.
name
optional string. If you have multiple sites operating under a single Affirm account, you can override the external company/brand name that the customer sees. This affects all references to your company name in the Affirm UI.

Contact object
  • 'shipping' object is required. 'billing' object is optional. Both have the same format as a contact object/

"shipping":{
        "name":{
          "first":"John",
          "last":"Doe"
          // You can include the full name instead
          // "full" : "John Doe"
        },
        "address":{
          "line1":"325 Pacific Ave",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94112",
          "country":"USA"
        }
        "phone_number": "4151234567",
        "email": "johndoe@gmail.com"
      }
 "billing":{
        "name":{
          "first":"John",
          "last":"Doe"
          // You can include the full name instead
          // "full" : "John Doe"
        },
        "address":{
          "line1":"325 Pacific Ave",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94112",
          "country":"USA"
        }
        "phone_number": "4151234567",
        "email": "johndoe@gmail.com"
      }
(object key name)
required string. Either 'shipping' or 'billing'. Only the 'shipping' object is required, 'billing' object is optional.
name
required object. First and last, or full name. Used to pre-populate the account sign-up form.
address
required object. Address information. Validated against public address service APIs.
phone_number
optional string. The user's phone number. Validated against the Affirm checkout API. Must be a valid, U.S.-based, mobile phone number. Used to pre-populate the account sign-up form.
email
optional string. The user's email address.

 

Address object

"address":{
   "line1":"633 Folsom St",
   "city":"San Francisco",
   "state":"CA",
   "zipcode":"94107",
   "country":"USA"
}
line 1
required string. Valid U.S. street address, verified by public address service APIs.
line 2
optional string. Apartment, suite, floor, etc. 
city
required string. City name, verified by public address service APIs.
state
required string. 2-letter ISO code or full name, verified by public address service APIs.
zipcode
required string. Must match other provided address information, verified by public address service APIs.
country
optional string. If provided, must be 'US' or 'USA' (3-letter ISO code). Affirm is only available to U.S. residents.

Name object 

"name":{
   "first": "John",
   "last": "Doe",
   "full": "John Doe"
}
first
required string. Can contain multiple words (for middle names).
last
required string.
full
optional string. Required if 'first' and 'last' keys are missing. String must contain at two words.

Item object

The item object array should be built dynamically, based on the current cart contents.

"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"
      },
      {
        "display_name":         "Best Drone",
        "sku":                  "DEF-456",
        "unit_price":           5999,
        "qty":                  1,
        "item_image_url":       "http://merchantsite.com/images/best-drone.jpg",
        "item_url":             "http://merchantsite.com/products/best-drone.html"
      }]
display_name
required object. The display name of the product.
sku
required string. The product SKU.
unit_price
required integer. The item price expressed as integer USD cents ("$100" = 10000).
qty
required integer. The item quantity expressed as an integer.
item_image_url
required string. The item's product image URL.
item_url
required string. The item's product description page URL.

 

Sending the checkout request

With the checkout object built, you can now call:

affirm.checkout.post();

This method will send a POST request to the /checkout/ API endpoint with the checkout object as the data payload. Then, it will redirect the user to the Affirm checkout flow on the affirm.com domain.

Syntax notes
  • The checkout object is sent as a JSON object.
  • All numerical values must be sent as integer USD cents ($25.00 -> 2500).
  • The items are stored in an object array. You should build this array dynamically by adding item objects to it based on cart contents.
  • The discount object uses the discount code as the name of the nested objects. As a result, you may have to construct each discount without the use of a strongly-typed class.
Checkout object validation

The following data in the checkout object is validated:

  • Name
    • There must be a first and last name.
  • Address
    • The address must have a direct match on both Smarty Streets and Google Maps.
  • Phone number
    • Number must be a valid US cell phone number that is able to receive SMS text messages.
  • Total
    • An order total must be present and greater than 0.
  • Discount
    • Any discount values must be positive integers.
  • Item
    • Item URL   
      • Must be present, but can be an empty string.
Error handling

Errors generated by the checkout request are presented on the page where checkout is initiated, in the form of a pop-up modal window. Specific messaging about the source of the error is presented in this modal (e.g., "Invalid phone number"). 

You may define a callback function when this error modal is closed, but currently that callback does not relay any event data specific to the error message that's displayed in the modal. 

Here's an example of how this event callback would be defined:

affirm.ui.ready(
    function() {
        affirm.ui.error.on("close", function(){
            alert("Please check your contact information for accuracy.");
        });
    }
);