Switching to the Transactions API

Affirm has moved to the new [Transactions API](🔗). While we will continue to support Charges API, we recommend using Transactions API. Transactions APIs support Leases serviced by LTO providers (Snap, Katapult, etc.) in addition to processing payments financed by installment loans. You can find more information [here](🔗).

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.

## 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 `affirm.checkout(checkoutObject)` and `affirm.checkout.open()` functions, which triggers our standard flow when the customer clicks on a _Complete payment_ button after selecting Affirm as a payment option.

Checkout functions and object

The above checkout functions do the following:

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

You can find more information on how to [create a checkout object](🔗) via our Affirm Javascript library.

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