Prequalification Callback API

Learn about receiving prequalification events.

Overview

The Prequalification Callback API provides a way to register a callback function to be invoked when customers reach a decision outcome on the prequalification application. Whether the customer was approved or denied for prequalification, the API provides a way for your web application to respond to events on a real-time basis. The guide provides the necessary steps to start receiving prequalification events.

1. Embed Affirm.js and enable Prequalification

📘

See our Embed Affirm and Prequalification Overview documentation page for more details.

Include the following script in the head section on every page on your site.

<script>
 _affirm_config = {
   public_api_key:  "YOUR_PUBLIC_KEY",
   script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js"
 };
(function(m,g,n,d,a,e,h,c){var b=m[n]||{},k=document.createElement(e),p=document.getElementsByTagName(e)[0],l=function(a,b,c){return function(){a[b]._.push([c,arguments])}};b[d]=l(b,d,"set");var f=b[d];b[a]={};b[a]._=[];f._=[];b._=[];b[a][h]=l(b,a,h);b[c]=function(){b._.push([h,arguments])};a=0;for(c="set add save post open empty reset on off trigger ready setProduct".split(" ");a<c.length;a++)f[c[a]]=l(b,d,c[a]);a=0;for(c=["get","token","url","items"];a<c.length;a++)f[c[a]]=function(){};k.async=
!0;k.src=g[e];p.parentNode.insertBefore(k,p);delete g[e];f(g);m[n]=b})(window,_affirm_config,"affirm","checkout","ui","script","ready","jsReady");
</script>

2. Register a callback function

Affirm currently provides two implementation options for registering a callback function. We recommended registering the callback function directly with Affirm.js, although this requires having access to the global scope of the parent document. If you're a third-party provider with an embedded <iframe> tag within the parent document, listening to messages dispatched by the postMessage API will be necessary to receive events. The following table outlines the compatibility between the two methods given how the client application is embedded within the parent document:

Integration methodEmbedded Embedded tag in parent document
Affirm.js:white-check-mark::x:
postMessage API:white-check-mark::white-check-mark:

🚧

You cannot register multiple callbacks with Affirm.js at this time. If multiple parties are looking to subscribe to prequalification events, you must use the postMessage

Integrate with AffirmJS

If you're a merchant or a third party provider who have access to the same global scope embedded with Affirm.js, you may register a callback function which will be invoked after completing prequalification, regardless of the decision outcome.

function prequalCallback(event) {
    console.log(event);
}

affirm.ui.ready(function() {
    affirm.events.on("prequal:complete", function(data) {
        prequalCallback(data)
    })  
});

A sample output of the event data is provided below with specifics outlined in the Callback data object section:

Example event data

{
    amount: 400000,
    terms: [{
        apr: "10.13",
        created: "2015-08-12T23:57:25Z",
        id: "sandbox_plan_3",
        installment_amount: 135531,
        installment_count: 3,
        interest_amount: 6686,
        prequal_amount: 400000
    }, {
        apr: "10.13",
        created: "2015-08-12T23:57:25Z",
        id: "sandbox_plan_6",
        installment_amount: 68598,
        installment_count: 6,
        interest_amount: 11749,
        prequal_amount: 400000
    }, {
        apr: "10.13",
        created: "2015-08-12T23:57:25Z",
        id: "sandbox_plan_12",
        installment_amount: 35141,
        installment_count: 12,
        interest_amount: 22010,
        prequal_amount: 400000
    }]
}

📘

Take a look at the Security considerations section for more information on security when implementing this integration.

3. Enable prequalification events

Reach out to your Partner Engineering contact and request to enable prequalification events.

Callback data object

Refer to the table below for the schema of the event data:

ParameterDescription
amount string
optional
Only available when the value of status is approved.
status string
required
The decision outcome of the user’s prequalification. May have the following values:

- approved: The user opted into data sharing and the prequalification was successful.
- not_approved: The user opted into data sharing but the prequalification was not successful.
- unknown: The user did not opt into data sharing.
terms array
optional
Only available when the value of status is approved.

Financing term object

ParameterDescription
apr string
required
A unique identifier representing the cart of the customer. A maximum of 500 characters.
created string
optional
The name of the cart. A maximum of 500 characters.
id string
required
An Affirm-specific unique identifier for the financing program used.
installment_amount integer
required
The payment amount due per installment amount in the term.
installment_count integer
required
The total number of installments in the term.
interest_amount integer
required
The total interest that would be charged over the duration of the term.
prequal_amount integer
required
The amount the user was prequalified for. The value must be non-negative and represented in minor units, such as cents instead of dollars

Security considerations

By default, web browsers prevent pages in different domains from affecting each other via cross-site scripting for security and privacy reasons. This is an important security feature, but it also prevents documents from different domains from communicating with each other, even if the pages aren't hostile.

In order to enable cross-origin communication, modern browsers support the Window.postMessage() API which allows pages to communicate with each other regardless of their source domain, in a way designed to not enable cross-site scripting attacks. We use this API to safely transmit data for Prequalification Callbacks.