---
updatedAt: 2026-08-25T21:42:42.000Z
agentTools:
  siteIndex: https://docs.affirm.com/llms.txt
  projectIndex: https://docs.affirm.com/developers/llms.txt
---

# Integration Checklist

## Prerequisites

* [ ] Confirm Affirm has enabled your merchant account for Connected Accounts (contact your TAM)
* [ ] Obtain your public/private API key pair for the target environment (sandbox and production are separate credentials)
* [ ] Stand up secure, encrypted-at-rest, server-side storage for refresh tokens, keyed by `account_linking_id` (see 'Recommended Storage Schema')
* [ ] Decide on a stable `account_linking_id` source (internal customer DB ID, UUID, etc.) that must never change for a given customer
* [ ] Choose your refresh-token delivery method: Webhook (recommended) or Token Lookup API

## Step 1: Initial Linking

* [ ] Add `account_linking_id` (Affirm.js) or `account_linking.id` (Direct API) to your checkout-creation call
* [ ] If using the Webhook method: register your HTTPS endpoint with your TAM for the `linking_status_changed` event, and verify it’s working
* [ ] If using the Token Lookup API: call `POST /api/pba/v1/oauth/token/lookup` after the cancel/confirmation callback and store the returned `refresh_token`
* [ ] Persist the `refresh_token` and its `expires_at` against the customer's `account_linking_id` as soon as it's received

## Step 2: Returning-User Token Exchange

* [ ] Generate the PKCE pair via `affirm.checkout.prepareAuth()` (Affirm.js) or the Web Crypto API (Direct)
* [ ] Call `POST /api/pba/v1/oauth/token` with the stored `refresh_token` to obtain an `access_token`
* [ ] Atomically store the new `refresh_token` returned in that response and discard the old one; never retry with a stale refresh token
* [ ] (Affirm.js only) Call `POST /api/pba/v1/oauth/session` with the `access_token` and `code_challenge` to obtain a session\_code

## Step 3: Accelerated Checkout

* [ ] (Affirm.js) Pass `session_code` into `affirm.checkout.open()`
* [ ] (Direct API) Pass `account_linking.access_token` and `account_linking.code_challenge` in the Direct 

  Checkout request, then append `code_verifier` to the returned `redirect_url` before sending the customer's browser there
* [ ] Implement the fail-open principle: any failure in the exchange must fall through to a standard, non-accelerated checkout and never block or error out the customer

## Step 4: Re-linking & Unlinking

* [ ] Handle `unauthorized` on any future token exchange by deleting the stored refresh token and falling back to standard checkout

## Step 5: Testing

* [ ] Go through the test scenarios in [Reliabilty & Testing](https://docs.affirm.com/developers/docs/connected-accounts-reliabilty-and-testing) on both a pre-production and production environment 

# Sibling pages

* [Set Up Connected Accounts](https://docs.affirm.com/developers/docs/set-up-connected-accounts.md)
* [Reliability & Testing](https://docs.affirm.com/developers/docs/connected-accounts-reliabilty-and-testing.md)