Affirm-developers

Web

Learn how to collect customer details on the Web.

Starting a payment with Affirm on the web consists of creating a checkout form, tokenizing customer information securely, and using that checkout_token to initiate a charge.

This guide shows you how to include Affirm.js and Affirm Checkout on your web page.

1. Set up Affirm.js

Include the following script in the head section on every page on your site. That script should always be loaded directly from the Affirm domain.

🚧

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

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

🚧

Canada

Make sure you include the https://cdn1-sandbox.affirm.ca/js/v2/affirm.js script URL to point to our Canadian sandbox.

2. Initialize Affirm

Once you included the script above, a defined instance of Affirm will be created on your client. You will gain access to methods that are within the affirm object to trigger multiples actions.

3. Render Affirm checkout

Checkout creation is the process in which a customer uses Affirm to pay for a purchase in your app. You can create a checkout object and launch the 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"]
        ]
      }
   ],
      "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",
      "mode":"modal"
   },
   "order_id":"JKLMO4321",
   "currency":"USD",  
   "financing_program":"flyus_3z6r12r",
   "shipping_amount":1000,
   "tax_amount":500,
   "total":100000
}

affirm.checkout.open()

🚧

The above does a couple of things:

  • Sends the checkout object.
  • Redirects the customer to the Affirm checkout process on the affirm.com domain or shows them an Affirm modal.
  • Validates the required data in the checkout object.

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.

🚧

You can also retrieve the checkout_id from a javascript callback if you set the metadata mode to modal. Learn more about modal checkout.

5. Create a charge

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

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.");
        });
    }
);

Try it out!

Use the demo below to try out our basic checkout flow.

Updated 2 months ago


What's Next

You can find additional objects and methods available in Affirm’s browser-side JavaScript library, Affirm.js.

Create a Charge
Charge Actions
AFJS Reference

Web


Learn how to collect customer details on the Web.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.