HomeGetting StartedSolutionsPlatformsGlobal Integration
Docs

Programmatic Merchant Onboarding API and Webhooks

Programmatically onboard merchants with Affirm’s API and get real-time status updates via webhooks for a streamlined approval process.

Suggest Edits

Overview

Affirm’s Programmatic Merchant Onboarding API and webhook system enables partners to seamlessly create and monitor merchants through automated processes. This integration is designed to streamline the onboarding workflow by allowing direct merchant creation via API and receiving real-time status updates through webhooks.

📘

Merchant Creation

To create a merchant programmatically, use Affirm’s Merchant API.

Webhooks

As part of the merchant onboarding flow, Affirm assesses merchant details during the underwriting process. Once an underwriting decision is made, Affirm sends a webhook to communicate the status update (e.g., approved or denied).

Webhook: merchant_update

FieldDescription TypeRequired/Optional
event_type Type of webhook event. String (enum)

- merchant_update		Required
event_idID of the specific webhook event. StringRequired
merchant_id Affirm merchant ID. StringRequired
external_merchant_id External merchant ID (as provided by the partner). StringRequired
status Status of the merchant. String (enum)Required
messageMessage related to the update.StringOptional

Initial Status

Upon creation, a merchant's initial status will typically be:

  • net_new: The default status for all new merchants unless the merchant is created with the pre_approved flag. This status is used while OFAC (sanctions) checks are pending.
  • After sanctions screening, merchants transition to:
    • prelaunch: Indicates the merchant successfully passed sanctions checks and is eligible to receive live traffic. The merchant remains in this status until the Merchant Risk team performs a full risk review.
    • ofac_hit: Indicates a match was found during OFAC screening (e.g., on the U.S. Treasury's sanctions list).
      • approved: The OFAC match was determined to be a false positive, and the merchant passed all subsequent risk checks.
      • denied_pbp: The OFAC match was a false positive, but the merchant did not satisfy all additional risk evaluation criteria.
      • denied_ofac: The OFAC match was confirmed as valid.

Possible Status Values

StatusDescription
net_new Default initial status for merchants unless pre_approved. This is updated once sanctions checks (OFAC) are completed.
prelaunch Assigned after the merchant passes sanctions screening. Merchants in this status can begin receiving traffic. They remain here until they reach a GMV threshold (typically $150), which then triggers a Merchant Risk review.
ofac_hit Assigned if the merchant has a match in the OFAC (Office of Foreign Assets Control) watchlist during sanctions checks.
approved Set in two cases: (1) Immediately upon creation if the pre_approved flag is used, or (2) after Merchant Risk manually reviews and approves the merchant.
denied_ofac After a merchant is assigned the ofac_hit status, Affirm will investigate the potential sanctions match. If the match is confirmed to be valid, the merchant will be terminated using this status reason.
denied_pbpThis status is assigned when a merchant passes sanctions screening (OFAC) but fails to meet other risk assessment criteria.

Example Status Payloads

Approved Merchant

{
  "event_type": "merchant_update",
  "event_id": "string",
  "merchant_id": "string",
  "status": "approved",
  "external_merchant_id": "external-partner-id",
  "message": "update_success"
}

Denied Merchant (e.g., OFAC)

{
  "event_type": "merchant_update",
  "event_id": "string",
  "merchant_id": "string",
  "status": "denied_ofac",
  "external_merchant_id": "external-partner-id",
  "message": "update_success"
}

Updated 2 days ago