HomeGetting StartedSolutionsPlatformsGlobal Integration
API reference

Managing Merchants

Overview

The Merchant API enables partners to manage merchant accounts within Affirm's system. This guide covers the processes of creating merchants, initiating underwriting procedures, managing approval states, and updating merchant attributes.

Create Merchants

The Create Merchant endpoint is used to create a merchant in the Affirm system. You can use the APIs to create and manage merchants, including setting up merchants with a specific financing program.

See the request below for creating a new merchant:

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/merchants \
     --header 'Country-Code: USA' \
     --header 'Locale: en_US' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "business_address": {
    "street1": "650 California Street",
    "city": "San Francisco",
    "region1_code": "CA",
    "postal_code": "94108",
    "country_code": "US"
  },
  "legal_business_name": "Suzie  Store LLC",
  "url": "suizestore.com",
  "first_name": "Suzie",
  "last_name": "Smith",
  "email_address": "[email protected]",
  "financing_package_uuid": "192c664c-d583-49ed-8dfd-11b4ba7b9af7",
  "ein": "123456789",
  "settlement_bank_account_number": "1234567890",
  "settlement_bank_routing_number": "123456789",
  "mcc": "2791",
  "business_type": "LLC",
  "remittance_name": "Suzie Smith",
  "pre_approved": true,
  "external_merchant_id": "EXTERNAL-MERCHANT-ID",
  "phone_number": "+1-123-123-1234",
  "business_phone": "+1-123-123-1234",
  "annual_volume": "1000000",
  "average_order_value": "1000",
  "capture_to_shipment_time": 5,
  "business_owner_dob": "1992-05-11T00:00:00.000Z",
  "business_owner_ssn": "123456789"
}
'

On success, Affirm returns a 201 response including the associated merchantId and their API keys. 

{
  "id": "21FA1V8NLZAQGOK6",
  "live_public_key": "live_pub_ky9F8x2Gp",
  "live_private_key": "live_priv_ky7N4d6Sj",
  "sandbox_public_key": "sand_pub_ty4M3z7Qk",
  "sandbox_private_key": "sand_priv_ty2D5v8Pn",
  "status": "net_new",
  "api_key_pairs": [
    {
      "public_key": "live_pub_ky9F8x2Gp",
      "private_key": "live_priv_ky7N4d6Sj",
      "env": "live",
      "active": true,
      "date_created": "2022-11-01T12:00:00Z",
      "date_updated": "2022-11-15T08:00:00Z"
    }
  ],
  "parent_id": "parent_67890"
}

Update Merchants

Use the Update Merchant endpoint to update details about the merchant. The following request updates the merchants business name to Suzie Store Inc. and other details. 

curl --request PUT \
     --url https://www.affirm.com/api/partner/v1/merchants/21FA1V8NLZAQGOK65 \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "legal_business_name": "Suzie  Store Inc.",
  "settlement_bank_account_number": "11111567890",
  "business_type": "Partnership"
}
'

On success, Affirm returns a 200 response and includes the date the merchant was updates. 

{
  "api_key_pairs": [
    {
      "public_key": "ABCDEFGH1234",
      "private_key": "ABCDEFGH1234",
      "env": "live",
      "active": true,
      "date_created": "2021-02-20T00:00:00Z",
      "date_updated": "2021-02-20T00:00:00Z"
    }
  ]
}

Retrieve Merchants

Use the Get Merchant endpoint to retrieve the details of a specific merchant.

The following example retrieves a merchant by ID. 

curl --request GET \
     --url https://www.affirm.com/api/partner/v1/merchants/21FA1V8NLZAQGOK6 \
     --header 'accept: application/json'

See the example response below:

{
  "api_key_pairs": [
    {
      "public_key": "ABCDEFGH1234",
      "private_key": "ABCDEFGH1234",
      "env": "live",
      "active": true,
      "date_created": "2021-02-20T00:00:00Z",
      "date_updated": "2021-02-20T00:00:00Z"
    }
  ]
}

Delete Merchants

Use the Delete Merchant endpoint to delete a merchant by merchantId.

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/merchants/21FA1V8NLZAQGOK6/delete_event \
     --header 'Idempotency-Key: 0ddb9813-e62d-4370-93c5-476cb93038a9' \
     --header 'accept: application/json'

See the example response below:

{
  "resource_id": "21FA1V8NLZAQGOK6",
  "delete_id": "123a4567-abcd-12ab-a345-123456789012"
}

Create New Merchant API Key Pair

Use the Create Merchant API Keys endpoint to create a new API key pair for the merchant's current environment. 

curl --request POST \
     --url https://www.affirm.com/api/partner/v1/merchants/21FA1V8NLZAQGOK6/api_keys \
     --header 'accept: application/json'

See the example response below:

{
  "api_key_pair": {
    "public_key": "ABCDEFGH1234",
    "private_key": "ABCDEFGH1234",
    "env": "live",
    "active": true,
    "date_created": "2021-02-20T00:00:00Z",
    "date_updated": "2021-02-20T00:00:00Z"
  },
  "status": "api_key_created"
}

Update new merchant API key pair

Use the Update Merchant API Keys endpoint to update the state of existing merchant API keys. 

curl --request PUT \
     --url https://www.affirm.com/api/partner/v1/merchants/21FA1V8NLZAQGOK6/api_keys \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "active": true,
  "public_key": "ABCDEFGH1234"
}
'

See the example response below:

{
  "status": "api_key_created"
}

Test merchant API Keys

Use the Test Merchant API Keys endpoint to test if the merchant's API keys are valid.

curl --request GET \
     --url https://www.affirm.com/api/partner/v1/merchants/21FA1V8NLZAQGOK6/test \
     --header 'accept: application/json'

See the example response below:

{
  "code": "api-key-pair-valid",
  "message": "The API keys are valid."
}