Skip to main content

Merchant Help

 

Affirm Merchant Help

Status Visibility

Overview

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

  • Enters checkout
  • Receives a credit decision
  • Confirms their loan
Customer Experience Affirm Event Webhook Event
Selects Affirm as payment option and is sent to Affirm Checkout created Correlates to created timestamp in webhooks, see below
Creates or signs in to an Affirm account none none
Processing screen Approval decision
  • approved
  • not_approved
  • more_information_needed
Selects loan terms and agrees to disclosures none none
Clicks Confirm and is sent back to merchant site Checkout confirmation confirmed

You can use this information for customer service purposes, such as phone support, or to identify potential customers for email marketing campaigns. You can also use Status Visibility for in-checkout session (push) notifications and feedback. This guide covers how to receive Status Visibility updates from Affirm.

Integration

To receive Status Visibility updates from Affirm:

  1. Set up a server page/endpoint that can receive Affirm's webhook (POST) requests
  2. Parse and store the received webhook contents for later reconciliation

The order_id and webhook_session_id sent in the checkout object is in all incoming webhook requests for that checkout attempt. You can reconcile this data with your customer records.

Set up webhook endpoint

Affirm will send an HTTP POST request to a URL 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. The URL requirements are:

Endpoint requirements

  • HTTP/HTTPS
  • Receives POST method
  • Returns 20x status
  • Rate dependent on merchant checkout traffic
  • Inbound IP is dynamic

Authentication

We can support Basic Authentication in the URL:

"AB123:ZXY987@www.test.com/affirm_webhook"

Parse webhook request

Our request properties are:

Properties

  • POST method
  • Content type: application/x-www-form-urlencoded
  • 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

Formats

Request body data is passed as a URL-encoded form:


    checkout_token=XVCZEXIR8NSJC5GK
    &event_timestamp=2017-09-27T06%3A25%3A12.901233
    &created=2017-09-27T06%3A24%3A35.787108
    &event=approved
    &order_id=1234 //optional
    &webhook_session_id=A1b2C3 //optional
Parameter Type Description
checkout_token string When the user exits, cancels, or is declined in the Affirm checkout flow.
event enum
  • sent
  • approved
  • not_approved
  • confirmed
event_timestamp timestamp UTC (YYYY-MM-DDTHH:MM:SS.SSSSSS)
created timestamp UTC (YYYY-MM-DDTHH:MM:SS.SSSSSS)
order_id string Only passed back if order_id is included in the checkout_object (Optional, Affirm must enable).
webhook_session_id string Customer or session id, only passed back if webhook_session_id is included in the checkout_object

 

Approved

The customer has been approved for their Affirm purchase.

{
    "checkout_token": "XVCZEXIR8NSJC5GK",
    "event_timestamp": "2017-09-27T06:25:12.901233",
    "created": "2017-09-27T06:24:35.787108",
    "event": "approved"
}

Not Approved

The customer has been declined credit for some reason. The reason is purposely ambiguous and may be due to credit-worthiness, inability to verify identity, or insufficient financial records.

{
    "checkout_token": "XVCZEXIR8NSJC5GK",
    "event_timestamp": "2017-09-27T06:23:12.901233",
    "created": "2017-09-27T06:23:12.901233",
    "event": "not_approved"
}

Confirmed

The customer has confirmed the loan. This is the last step of the Affirm checkout flow, which should subsequently trigger charge authorization.

{
    "checkout_token": "XVCZEXIR8NSJC5GK",
    "event_timestamp": "2017-09-27T06:25:31.316430",
    "created": "2017-09-27T06:24:35.787108",
    "event": "confirmed"
}

Examples

{
    "checkout_token": "XVCZEXIR8NSJC5GK",
    "event_timestamp": "2017-09-27T06:23:12.901233",
    "created": "2017-09-27T06:23:12.901233",
    "event": "sent"
}

{
    "checkout_token": "XVCZEXIR8NSJC5GK",
    "event_timestamp": "2017-09-27T06:25:12.901233",
    "created": "2017-09-27T06:24:35.787108",
    "event": "approved"
}

{
    "checkout_token": "XVCZEXIR8NSJC5GK",
    "event_timestamp": "2017-09-27T06:23:12.901233",
    "created": "2017-09-27T06:23:12.901233",
    "event": "not_approved"
}

{
    "checkout_token": "XVCZEXIR8NSJC5GK",
    "event_timestamp": "2017-09-27T06:25:31.316430",
    "created": "2017-09-27T06:24:35.787108",
    "event": "confirmed"
}