Skip to main content

Merchant Help

 

Affirm Merchant Help

Status Visibility

Overview

When customers go through the Affirm checkout flow, you can see the status of that checkout attempt in real-time from the Affirm API. A webhook request will be sent to your server when a customer enters checkout, receives a credit decision, and confirms their loan. This information can be used for customer-service purposes, or to identify potential customers for email marketing campaigns.

Walkthrough

Customer Experience Affirm Event Webhook Event Notes
Select Affirm, is redirected to Affirm Checkout created n/a Correlates to 'created' timestamp in webhooks
Creates or logs into an Affirm account n/a n/a  
Processing screen Approval decision 'approved', 'not_approved', or 'more_information_needed'  
Selects loan terms, reads and agrees to disclosures n/a n/a  
Reads loan terms, clicks 'Confirm', redirect back to merchant site initiated Checkout Confirmation 'confirmed'  

Integration

In order to receive Status Visibility updates from Affirm, there are two main steps:

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

Webhook Endpoint

Affirm will be sending a HTTP POST request to a URL you'll provide to your Client Success or Partner Engineer contact at Affirm.

That URL will be a page or endpoint that your team has setup to receive requests from our servers. The requirements for the URL you setup, and the request we'll be sending are below:The properties/format of that request are below:

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"

Webhook Request

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
    
checkout_token
string. Called when the user exits from, cancels, or is declined in the Affirm checkout flow
event
enum. sent | approved | not_approved | confirmed
event_timestamp
UTC timestamp (YYYY-MM-DDTHH:MM:SS.SSSSSS)
created
UTC timestamp (YYYY-MM-DDTHH:MM:SS.SSSSSS)
order_id
optional. string. Has to be enabled by Affirm staff, only passed back if order_id is included in the checkout_object.

Approved

Trigger: When the customer has 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

Trigger: When the customer has been declined credit for some reason. The reason is purposely ambiguous, and could 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

Trigger: When the customer has confirmed the loan. This is the last step of the Affirm checkout flow, and 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"
}

Reconciliation

Order ID

The order_id that you send in the checkout object will also be present in any incoming webhook requests for that checkout attempt.

You'll reconcile this with your own customer records.

Use cases

Visibility into the status of a customer's checkout attempt can be utilized in multiple ways:

  • Phone order support
  • In-checkout-session (push) notifications and feedback
  • Email marketing
    • Mention