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 on both a pre-production and production environment