Set Up Direct API

Learn how to integrate Affirm's Direct API on your site to initiate and authorize transactions. This guide walks you through embedding Affirm.js, setting up the checkout object, handling callbacks, and authorizing payments.

📘

Legacy Charges API

This integration uses the updated v1/transactions API endpoints. If you're using our legacy v2/charges endpoints, see the legacy Web (Charges).

Prerequisites

Steps

1. Embed Affirm JS (AFJS)

Add the Affirm.js script to the <head> on your site. The script loads directly from the Affirm domain.

🚧

Sandbox API Keys

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

<script>
var _affirm_config = {
		public_api_key: "YOUR_PUBLIC_API_KEY", /* replace with public api key */
		script: "https://cdn1-sandbox.affirm.com/js/v2/affirm.js",
		locale: "en_US",
		country_code: "USA",
	};

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

2. Configure and Render the Checkout Object

Call affirm.checkout() with your order details and then use affirm.checkout.open() to launch the Affirm checkout modal.

affirm.checkout({
  merchant: {
    user_confirmation_url: "https://merchantsite.com/confirm",
    user_cancel_url: "https://merchantsite.com/cancel",
    public_api_key: "YOUR_PUBLIC_KEY",
    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: 10000
  }]
});
affirm.checkout.open();

3. Handle the Callback and Retrieve the checkout_token

After a successful checkout, Affirm sends a checkout_token to the user_confirmation_url via HTTP POST or GET, depending on your configuration. Handle this on your backend.

You can also use a JavaScript callback in modal checkout mode to retrieve the token.

4. Authorize the Transaction

Send a POST request to the /transactions endpoint to authorize the purchase:

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

Save the returned transaction ID for future reference:

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

5. Error Handling

If there are issues with the checkout process, an error modal is displayed. You can define a callback for when that modal is closed:

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

🚧

Travel Merchants

If you're a travel merchant, you must include the itinerary object in the checkout request.

What’s Next?