Webhooks
Webhooks are commonly used to automatically send data from one application to another. Learn how you can use webhooks to track Affirm events.
Overview
Affirm uses webhooks to notify your application any time events happen.
Webhook endpoints are not self-serve. Please reach out to Affirm via the support widget.
Affirm creates a checkout event object for each occurrence that is worth notifying you about. Some of these occurrences could be a new checkout from a customer or a confirmed checkout, and each event will have its own status.
When you create a webhook endpoint, it normally listens for specific events, and then takes action whenever those events are being received. Technically, a webhook endpoint is hosted on your server-side code (e.g., in python, node, etc.), which handles any push from third and/or specific parties.
About Affirm's Webhooks
Affirm will send an HTTP POST
request to a URL that you provide us with. The provided URL should be a page or endpoint that has been set up to receive requests from our servers.
Merchants cannot add a webhook endpoint or manage events by themselves via Affirm Dashboard. Please reach out to Affirm via the support widget for details.
Affirm Policies
Customers must opt-in for the approval decisions to be included. The confirmed event is the only webhook event that is guaranteed to be present for each successful Affirm checkout attempt. All other events (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.
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 and application/json
- Accept-Encoding: gzip
Webhook Request Properties
- POST method
- User-Agent: Affirm-Webhook
- Origin IP is dynamic
Data Fields
Data Field Configurations
Data fields are not self-service configurable. To enable or modify the data included in your webhook payloads, please contact your Technical Account Manager or reach out to the Affirm Partnerships Team for assistance.
Webhook data fields allow you to customize the information included in webhook payloads sent from Affirm to your system. These fields represent key data points related to customer identity, loan terms, and transaction details. By selecting specific fields, you ensure that only relevant information is transmitted to your backend systems, enabling accurate order tracking, and reporting.
Customer Information
Field | Description |
---|---|
First Name | The customer's first name. |
Last Name | The customer's last name. |
Email Address | The customer's email address. |
Loan/Payment Terms
Field | Description |
---|---|
Down Payment Amount | The upfront payment made by the customer before financing the remainder. |
Has Down Payment | Indicates if the customer had a down payment. |
Amount Financed | The amount of the total cost that is being financed (after any down payment). |
Approved Amount | The total loan amount approved for the customer. |
Finance Charge | The cost of financing, including interest and fees. |
APR | The interest rate applied to the financed amount. |
Number Of Payments | The total number of installments the customer is expected to make. |
First Payment Date | The scheduled date for the customer’s first payment. |
Expiration Date | The date after which the loan offer or terms are no longer valid. |
Prequal Terms | Terms shown during the prequalification process. |
Remaining Credit Amount | The unused or remaining portion of the customer's Affirm credit. |
Order and Transaction Details
Field | Description |
---|---|
Order ID | Unique identifier for the transaction/order. |
Total | The total amount of the customer's transaction. |
Charge ARI | Internal identifier related to the charge. |
Respond to a Webhook Event
Your endpoint should respond to Affirm with a 2xx status code to communicate that you have 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.
Webhook Requirements
For checkout events, the requests sent from Affirm to your webhook endpoint come with the
content-type
application/x-www-form-urlencoded
and aapplication/x-www-form-urlencoded
version of the data in the body field. Prequal events are sent with thecontent-type
application/json
and aJSON
version of the data in the body field.
Affirm does not currently resend a webhook event if your endpoint did not successfully receive it.
Webhook Events
Checkout Events
When your customers go through Affirm's checkout flow, you can receive different checkout status events in real-time via your webhook endpoint.
- Enters checkout.
- Receives a credit decision.
- Confirms their loan.
User Experience | Affirm Event | Webhook Event |
---|---|---|
The Affirm checkout flow is opened and the customer is asked to login. | Checkout created | opened |
Creates or signs into an Affirm account. | None | None |
Processing Screen | Approval decision | approved not_approved |
The Affirm checkout flow opened by the user. | None | None |
Clicks confirm and is sent back to merchant site. | Checkout confirmation | confirmed |
Prequal Events
When your customers go through Affirm's prequalification flow, you can receive different prequalification status events via your webhook endpoint.
- Receives a credit decision.
- The prequalification expires.
User experience | Affirm event | Webhook event |
---|---|---|
Customer clicks the “See if you qualify” button in the “Learn More” modal. | None | None |
Creates or signs into an Affirm account. | None | None |
Processing Screen | Approval decision | prequal_decision |
Prequalification expires, could occur within or up to 7 days later. | Prequalification Expiration | prequal_expiry |
When to use Webhooks
Webhooks are optional but sometimes preferred for behind-the-scenes or asynchronous transactions, such as In-store integration since we are waiting on the customer to complete their checkout to receive the checkout_id
. In APIs like these, Affirm needs to notify your integration about changes to the status of the object so that you can act on them.
Some Affirm requests (e.g., checkout or prequalification) generate events that Affirm catches and these events allow you to share information with other systems as well. You can also use webhooks to automate business tasks:
- Performance metrics (e.g., funnel conversion, etc.).
- Streamline and automate operation processes.
Including a session ID in the Webhook Response
You can include a session ID in the webhook responses by including the session ID in the checkout object that is sent, or by including a session ID in Affirm.js
.
To include the session ID in Affirm.js
, follow the format included in the example below:
_affirm_config =
{ public_api_key: "YOUR_PUBLIC_KEY",
script: "https://cdn1-sandbox.affirm.com/js/v2/affirm.js",
session_id: "YOUR_VISITOR_SESSION_ID" }
Webhook Practice
For additional information about webhooks, check out our Changelog article, "How to use webhooks with Affirm," a step-by-step guide on how to create webhooks.
Updated 14 days ago