Merchants

Create Merchant

Creates a sub-merchant under the authenticated partner and starts underwriting lifecycle tracking.

For the partner API contract, id is server-managed and is not accepted in the request payload. Resolve derives/assigns the merchant identifier from merchant naming inputs (dba_name or legal_business_name) with random alphanumeric fallback for collisions.

Core merchant validation includes:

business_phone must be a valid US phone number
formation_state must map to a valid US state
US business addresses validate state and postal_code
beneficial owner US addresses validate state and postal_code
authorized_signer.phone, when provided, must be a valid US phone number
ein must be a valid EIN format
banking fields validate account-number shape and ABA routing number format
bank_account_number must be different from bank_routing_number

This endpoint also supports optional inline document URL ingestion. If document arrays are provided (bank_statements, financial_statements, credit_references, personal_guarantee, other_documents), Resolve queues download_url ingestion jobs equivalent to the document endpoint.

Inline document requests require:

filename with an extension
supported filetype for the merchant underwriting document profile
download_url using http or https
matching filename extension and filetype

Merchant creation is not rolled back for inline document ingestion failures.

Inline download dispatch is performed after database commit. Dispatch failures are surfaced per-item in document_ingestion.results, and the affected merchant document/file metadata is marked failed even though the merchant and some/all document rows were already persisted.

post/merchants

Request

Base URL
https://app-sandbox.resolvepay.com/api
Auth
- HTTP bearer
- or HTTP basic
TypeScript
https://skmtc.dev/resolvepay/apis/resolve-partners-api-reference/docs/merchants/post.ts
A function with typed inputs. Its response is checked against the schema.

Request body

reference_idstring nullable

Partner-supplied identifier for this merchant in your own system.

Stored as provided and returned on every merchant response. Filter on it with filter[reference_id][eq]=<value> when listing merchants.

Values are not required to be unique across your merchants, are limited to 255 characters, and may not be blank. Send null to clear a previously stored value.

legal_business_namestring required

business_emailstring email required

business_phonestring required

Business phone number. Must be a valid US phone number and is normalized to E.164.

entity_type'corporation' | 'llc' | 'sole_proprietorship' | 'partnership' | 'non_profit' required

formation_statestring required

Business formation state. Must map to a valid US state and is normalized to the state code.

einstring required

Employer Identification Number. Must be a valid EIN format.

dba_namestring

annual_revenueinteger

years_in_businessinteger

industrystring

business_descriptionstring

websitestring uri

estimated_monthly_net_terms_volumeinteger

existing_net_terms_infoobject

plaid_access_tokenstring

Plaid access token when a bank connection has already been established.

bank_account_numberstring

Bank account number. Must satisfy Resolve account-number validation and must be different from bank_routing_number.

bank_routing_numberstring

ABA routing number. Must be a valid routing number.

metadataobject

Example request

{
  "reference_id": "partner-crm-12345",
  "legal_business_name": "Acme Supply LLC",
  "business_address": {
    "line1": "100 Main St",
    "line2": "Suite 200",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  },
  "business_email": "ops@acmesupply.com",
  "business_phone": "+15125550123",
  "entity_type": "llc",
  "formation_state": "TX",
  "ein": "12-3456789",
  "dba_name": "Acme Industrial",
  "annual_revenue": 4500000,
  "years_in_business": 6,
  "industry": "Manufacturing",
  "business_description": "Industrial hardware distributor",
  "website": "https://acmesupply.com",
  "estimated_monthly_net_terms_volume": 350000,
  "existing_net_terms_info": {
    "provider": "Internal",
    "average_days_past_due": 12
  },
  "beneficial_owners": [
    {
      "first_name": "John",
      "last_name": "Owner",
      "date_of_birth": "1987-04-14",
      "address": {
        "line1": "100 Main St",
        "line2": "Suite 200",
        "city": "Austin",
        "state": "TX",
        "postal_code": "78701",
        "country": "US"
      },
      "ssn_last_4": "1234",
      "ownership_percentage": 35
    }
  ],
  "authorized_signer": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@acmesupply.com",
    "title": "Controller",
    "phone": "+15125550123"
  },
  "plaid_access_token": "access-sandbox-1234567890",
  "bank_account_number": "****6789",
  "bank_routing_number": "*****021",
  "metadata": {
    "partner_reference": "mt-merchant-1029"
  },
  "bank_statements": [
    {
      "filename": "bank_statement_2026_01.pdf",
      "filetype": "application/pdf",
      "download_url": "https://partner-files.example.com/bank_statement_2026_01.pdf"
    }
  ],
  "financial_statements": [
    {
      "filename": "bank_statement_2026_01.pdf",
      "filetype": "application/pdf",
      "download_url": "https://partner-files.example.com/bank_statement_2026_01.pdf"
    }
  ],
  "credit_references": [
    {
      "filename": "bank_statement_2026_01.pdf",
      "filetype": "application/pdf",
      "download_url": "https://partner-files.example.com/bank_statement_2026_01.pdf"
    }
  ],
  "personal_guarantee": [
    {
      "filename": "bank_statement_2026_01.pdf",
      "filetype": "application/pdf",
      "download_url": "https://partner-files.example.com/bank_statement_2026_01.pdf"
    }
  ],
  "other_documents": [
    {
      "filename": "bank_statement_2026_01.pdf",
      "filetype": "application/pdf",
      "download_url": "https://partner-files.example.com/bank_statement_2026_01.pdf"
    }
  ]
}

Response

A merchant object.

idstring

Resolve merchant identifier (lowercase alphanumeric).

For partner API create flows, ID assignment behavior is:

Resolve may derive a human-friendly alphanumeric candidate from merchant naming fields.
If the candidate collides with an existing merchant ID, Resolve generates a random lowercase alphanumeric ID.

reference_idstring nullable

Partner-supplied identifier for this merchant in your own system. null when never set.

legal_business_namestring

dba_namestring nullable

business_emailstring email

business_phonestring

entity_type'corporation' | 'llc' | 'sole_proprietorship' | 'partnership' | 'non_profit'

formation_statestring

industrystring nullable

websitestring uri nullable

underwriting_statusstring

Current underwriting lifecycle status for the merchant.

seller_amount_approvedinteger nullable

Merchant approved limit (MAL), when available.

metadataobject

created_atstring date-time

updated_atstring date-time

Example response

{
  "id": "mrc_1234567890abcdef",
  "reference_id": "partner-crm-12345",
  "legal_business_name": "Acme Supply LLC",
  "dba_name": "Acme Industrial",
  "business_address": {
    "line1": "100 Main St",
    "line2": "Suite 200",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  },
  "business_email": "ops@acmesupply.com",
  "business_phone": "+15125550123",
  "entity_type": "llc",
  "formation_state": "TX",
  "industry": "Manufacturing",
  "website": "https://acmesupply.com",
  "underwriting_status": "pending",
  "seller_amount_approved": 50000,
  "active_subscription": {
    "id": "sub_1234567890abcdef",
    "tier": "trial"
  },
  "document_ingestion": {
    "requested_count": 2,
    "queued_count": 1,
    "failed_count": 1,
    "results": [
      {
        "document_id": "md_1234567890abcdef"
      }
    ]
  },
  "created_at": "2026-02-26T10:00:00.000Z",
  "updated_at": "2026-02-26T10:05:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.