📘

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.

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

When a customer chooses to use Affirm to pay for a purchase, a `checkout` object containing the order details should be created so that Affirm can render the checkout flow. You can create a `checkout` object within `affirm.checkout()` and then launch the Affirm checkout experience using the `affirm.checkout.open()` function.

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 and total of their cart.

You can find more information about checkout object attributes in our checkout API.

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

## 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 <span style="color:green">success</span> callback.

#### 2. Authorize the checkout_token

Authorize the `checkout_token` immediately by passing the value in the `transaction_id` parameter to `/transactions` .

#### 3. Save the returned id

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

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