Skip to main content

 

Affirm Merchant Help

Prequal Status Visibility (Detailed)

Overview

When your customers go through the Affirm prequalification flow, you can see their status in real-time via the Affirm API. We send a webhook request to your server when a customer:

  • Clicks the “See if you qualify” button in the “Learn More” modal
  • Receives a credit decision
  • The prequalification expires

Usage

You can use this information to identify potential customers for email marketing campaigns. You can also use Status Visibility for in-prequal session (push) notifications and feedback. This guide covers how to receive Status Visibility updates from Affirm.

Prequalification Events

Customer Experience

Affirm Event

Webhook Event
Customer clicks the “See if you qualify” button in the “Learn More” modal Prequalification Triggered  

Creates or signs into an Affirm account

none

none

Processing Screen

Approval Decision

prequal_decision

Prequalification expires, could occur within up to 7 days later

Prequalification Expiration

 

Event Definitions:

Customers must opt-in for the approval decisions to be included. The prequal decision will also return the decision Affirm has made about the customer’s credit worthiness. The decision  (approved/not approved/etc.) will only be present if the customer has opted into the Affirm data sharing policy. Customers are actively prompted to enable data sharing, and they can toggle this setting ("Personalized Services") in their Affirm user profile at any time (https://www.affirm.com/u/#/settings).

Opened

When the customer has opened the “Learn More” modal and clicked the “See if you Qualify” button.

Prequalification Decision

Affirm has analyzed the customer’s information and has reached a prequalification decision.

Expired

If a customer’s prequalification decision has expired then the merchant will receive a webhook.

About Affirm’s Webhooks

Affirm will send an HTTP POST request to a URL that you provide to your Client Success Manager at Affirm. That URL should be a page or endpoint that you’ve set up to receive requests from our servers.

Endpoint requirements:

  • HTTP/HTTPS
  • Receives POST method
  • Returns 20x status
  • Support TLS 1.2 (self-signed or expired certificates are not accepted)
  • Rate dependent on merchant checkout traffic
  • Inbound IP is dynamic
  • Content-Type: application/x-www-form-urlencoded
  • Accept-Encoding: gzip

Webhook Request Properties:

  • POST method
  • User-Agent: Affirm-Webhook
  • Origin IP is dynamic
  • Number of fields varies; is based on:
    • Event type - approved/declined/more_information events have conditional fields
    • User opt-in - dictates whether conditional fields are present

Respond to a webhook event:

Your endpoint should respond to Affirm with a 2xx status code to communicate that you successfully received the webhook event notification. Affirm will treat all other response types as a failed delivery, including 3xx status codes. This means that we will treat URL redirections and “Not Modified” responses as failures. Affirm will ignore any other information returned in the request headers or request body.

Affirm doesn’t currently resend a webhook event if your endpoint didn’t successfully receive it.

Security Considerations:

Authentication

We can support Basic Authentication in the URL. You’ll need to provide your endpoint URL username and password to your Client Success Manager.

Example: “AB123:ZXY987@www.test.com/affirm_webhook”

Signed Requests

Affirm signs webhook requests so you can optionally verify that Affirm is sending the request instead of a third-party pretending to be Affirm. Each request includes a base-64 encoded header, X-Affirm-Signature. The value of the header is an HMAC-SHA256 hash signature computed from the request payload and your private API key found in your merchant dashboard.

Replay attack prevention

If a third-party intercepts a request payload and its signature, your endpoint is susceptible to a replay attack. To mitigate these attacks, we include a timestamp in the X-Affirm-Signature header. Since the timestamp is part of the signed payload, the attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is old, you should reject the request. We recommend rejecting a response with a timestamp 5 minutes older than the current time.

 

Event Definitions:

Customers must opt-in for the approval decisions to be included. The prequal decision will also return the decision Affirm has made about the customer’s credit worthiness. The decision  (approved/not approved/etc.) will only be present if the customer has opted into the Affirm data sharing policy. Customers are actively prompted to enable data sharing, and they can toggle this setting ("Personalized Services") in their Affirm user profile at any time (https://www.affirm.com/u/#/settings).

Content-Type: application/JSON

{
  "first_name": "Amy",
  "last_name": "Beall",
  "terms": [
    {
      "interest_amount": 16381,
      "created": "2015-03-10T23:06:30Z",
      "apr": "19.55",
      "installment_amount": 172127,
      "prequal_amount": 500000,
      "installment_count": 3,
      "id": "DX394TR2O0T6F3JM"
    },
    {
      "interest_amount": 29415,
      "created": "2015-03-10T23:06:30Z",
      "apr": "19.89",
      "installment_amount": 88236,
      "prequal_amount": 500000,
      "installment_count": 6,
      "id": "D3QF1AOBN0SL6XXT"
    },
    {
      "interest_amount": 56176,
      "created": "2015-03-10T23:06:30Z",
      "apr": "20.12",
      "installment_amount": 46348,
      "prequal_amount": 500000,
      "installment_count": 12,
      "id": "Z7XKQEWUW0FQOMJ2"
    }
  ],
  "created": "2019-02-27T22:42:00",
  "decision": "approved",
  "event_timestamp": "2019-02-27T22:42:08.092894",
  "expiration": "2019-02-27T22:42:08.092894",
  "webhook_session_id": null,
  "approved_amount": 500000,
  "email_address": "amy.beall@affirm.com",
  "event": "prequal_decision"
}    

Request Object Body

Parameter

Type

Description

event

enum

prequal_decision

decision

enum

  • approved

  • not_approved

event_timestamp

timestamp

UTC (YYYY-MM-DDTHH:MM:SS:SSSSSS)

created

timestamp

UTC (YYYY-MM-DDTHH:MM:SS:SSSSSS)

expiration

timestamp

UTC (YYYY-MM-DDTHH:MM:SS:SSSSSS)

first_name

string

The customer’s first name

last_name

string

The customer’s last name

email_address

string

The customer’s email address

terms

array

An array of terms objects

webhook_session_id

string

*(Optional) Must be enabled by Affirm. Only included if merchant passes the value in the checkout object

   

*For Shopify only, this field is unavailable

Terms Object Body

 

Parameter

Type

Description

interest_amount

integer

The total amount of interest that would be charged. The format is integer USD cents (“$163.81” = 16381)

created

timestamp

UTC (YYYY-MM-DDTHH:MM:SS:SSSSSS)

apr

float

The APR percentage offered. (“19.55%” = 19.55)

installment_amount

integer

The total amount of each payment that would be due. The format is integer USD cents (“$163.81” = 16381)

prequal_amount

integer

The total amount the customer qualifies for the entire store. The format is integer USD cents (“$163.81” = 16381)

installment_count

integer

The number of payments to pay off the loan.

id

string

An ID associated with the term offer