Web (transactions)

📘

Legacy Charges API

This integration uses the updated v1/transactions API endpoints. If you're using our legacy v2/charges endpoints, click here.

Overview

Starting a payment with Affirm online consists of creating a checkout form, tokenizing customer information securely, and using that checkout_token to initiate a transaction.

Checkout initiation

Initiate the Affirm application in four steps.

Step 1. Embed affirm.js

📘

Account setup

Make sure that you've set up an account in the Affirm Merchant Portal.

Include the following script in the head section on every page on your site. This 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>

Once you include 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 multiple actions.

Step 2. Render Affirm checkout

Checkout creation is the process in which a customer uses Affirm to pay for a purchase on your site or in your app. You can create a checkout object and launch the Affirm checkout using the affirm.checkout() function.

Calling the affirm.checkout() function does the following:

• Sends the checkout object to the Affirm backend.
• 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.

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

When the customer selects Affirm at checkout, the affirm.checkout() function sends the checkout object. You can configure the checkout object with the following:

• A user_confirmation_url to redirect your customer to a confirmation page after they confirm their loan
• A user_cancel_url to redirect your customer to a cancellation page if they don't complete their loan application.
• The customer's billing/shipping address.
• A description of their cart.

Step 3. 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.

🚧

Modal checkout

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

Step 4. Authorize

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

1. Retrieve the checkout_token

Retrieve the checkout_token sent by Affirm via a HTTP request to the success callback.

"checkout_token": "CJXXM8RERR0LC066"

2. Authorize the checkout_token

Authorize the checkout_token by passing the value in the transaction_id parameter to /transactions within 24 hours.

curl --request POST \
     --url https://api.affirm.com/api/v1/transactions \
     --header 'Accept: */*' \
     --header 'Content-Type: application/json' \
     --data '
{
     "transaction_id": "CJXXM8RERR0LC066",
     "order_id": "JKLM4321"
}
'

3. Save the returned id

After authorizing the transaction, save the id from the transaction object returned in the response.

{
    "id": "9RG3-PMSE"
    "currency": "USD",
    "amount": 11500,
}

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