HomeGetting StartedSolutionsPlatformsGlobal Integration
Docs

Integrate Affirm

Learn how to integrate Affirm and render a hosted checkout on your site.

Suggest Edits

Offering Affirm as a payment option on your site consists of creating a checkout form, securely tokenizing customer information, and using that checkout_token to initiate a charge.

We make it easy to build a smooth and stress-free buying experience:

  • A simple application requiring a few pieces of information for a real-time decision
  • More purchasing power for your customers with flexible payment options
  • Customization and branding options that integrate harmoniously with your site
  • A seamless and secure transaction experience for you and your customers

How it works

Affirm checkout is the process of collecting your customer's details when they choose Affirm to pay for their purchase. After the customer submits their checkout, you create a checkout object and your customer is either redirected to Affirm or sees an Affirm modal. We then present the option to sign in or sign up to select and confirm their loan terms. Once they fill out the required information, they’re redirected back to your site’s confirmation page.

1. Set up your Affirm account

Before you start, you need an Affirm account to access our merchant account credentials. To begin your integration process, you’ll need to sign in to your account.

2. Add Affirm.js

🚧

Use only your sandbox API keys and domain for testing and development. This ensures that you don't accidentally modify your live transactions.

Include the following script in the head section on every page on your site. The script should always load directly from the Affirm domain.

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

Adding Affirm.js creates a defined instance of Affirm on your client. This grants you access to the following methods within the Affirm object to trigger multiple actions:

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

3. Initiate checkout

Rendering the Affirm checkout is the process in which a customer uses Affirm to pay for a purchase on your site. You can create a checkout object and launch Affirm checkout using the Checkout function.

📘

You can find more information on how to create a checkout object via our Affirm Javascript library.

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":"Joe",
          "last":"Doe"
        },
        "address":{
          "line1":"633 Folsom St",
          "line2":"Floor 7",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94107",
          "country":"USA"
        },
        "phone_number": "4153334567",
        "email": "[email protected]"
      },
      "billing":{
        "name":{
          "first":"Joe",
          "last":"Doe"
        },
        "address":{
          "line1":"633 Folsom St",
          "line2":"Floor 7",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94107",
          "country":"USA"
        },
        "phone_number": "4153334567",
        "email": "[email protected]"
      },
      "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"
        "categories": [
            ["Home", "Bedroom"],
            ["Home", "Furniture", "Bed"]
        ],
      }],
      "shipping_amount":        1000,
      "tax_amount":             500,
      "total":                  5997
  });

affirm.checkout.open()

4. Handle callbacks

After you initiate a checkout and the customer confirms their Affirm loan, we send an HTTP request with the checkout_token to the URL you defined in the checkout object (user_confirmation_url). By default, Affirm sends this request via POST. However, you can configure the checkout object to have Affirm send this request via GET.

You choose how we send the checkout_token by setting the user_confirmation_url_action parameter in the checkout object.

  • Setting it to POST sends the checkout_token in the body of the HTTP request (default setting).
  • Setting it to GET sends the checkout_token in the query string of the HTTP request.

5. Create a transaction

When a customer successfully completes a checkout, it is recorded as a new purchase attempt. This needs to be handled on your server-side to be fulfilled via our Transaction API.

Updated 12 months ago