Skip to content
Partners API/
/
Create Merchant

Create Merchant

Request

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.

Security
bearerAuth or basicAuth
Bodyapplication/jsonrequired

Request body for creating a partner sub-merchant.

legal_business_namestringrequired
Example:"Acme Supply LLC"
business_addressobject(Address)required
business_emailstring, (email)required
Example:"ops@acmesupply.com"
business_phonestringrequired

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

Example:"+15125550123"
entity_typestringrequired
Enum:"corporation""llc""sole_proprietorship""partnership""non_profit"
Example:"llc"
formation_statestringrequired

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

Example:"TX"
einstringrequired

Employer Identification Number. Must be a valid EIN format.

Example:"12-3456789"
dba_namestring
Example:"Acme Industrial"
annual_revenueinteger
Example:4500000
years_in_businessinteger, >= 0
Example:6
industrystring
Example:"Manufacturing"
business_descriptionstring
Example:"Industrial hardware distributor"
websitestring, (uri)
Example:"https://acmesupply.com"
estimated_monthly_net_terms_volumeinteger
Example:350000
existing_net_terms_infoobject
Example:
{
  "provider": "Internal",
  "average_days_past_due": 12
}
beneficial_ownersArray of objects(BeneficialOwner)

Initial beneficial owner list.

authorized_signerobject(AuthorizedSigner)
plaid_access_tokenstring

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

Example:"access-sandbox-1234567890"
bank_account_numberstring

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

Example:"****6789"
bank_routing_numberstring

ABA routing number. Must be a valid routing number.

Example:"*****021"
metadataobject
Example:
{
  "partner_reference": "mt-merchant-1029"
}
bank_statementsArray of objects(InlineDocumentDownloadRequest)

Optional document ingestion on merchant create. Each item queues a background download job (equivalent to calling the document endpoint with download_url).

financial_statementsArray of objects(InlineDocumentDownloadRequest)

Optional inline financial_statements document ingestion requests.

credit_referencesArray of objects(InlineDocumentDownloadRequest)

Optional inline credit_references document ingestion requests.

personal_guaranteeArray of objects(InlineDocumentDownloadRequest)

Optional inline personal_guarantee document ingestion requests.

other_documentsArray of objects(InlineDocumentDownloadRequest)

Optional inline other document ingestion requests.

curl -i -X POST \
  https://docs.resolvepay.com/_mock/partners-api/openapi/merchants \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "legal_business_name": "Acme Supply LLC",
    "business_address": {
      "line1": "100 Main St",
      "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",
    "website": "https://acmesupply.com",
    "metadata": {
      "partner_reference": "mt-merchant-1029"
    }
  }'

Responses

A merchant object.

Bodyapplication/json
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.
Example:"mrc_1234567890abcdef"
legal_business_namestring
Example:"Acme Supply LLC"
dba_namestring or null
Example:"Acme Industrial"
business_addressobject(Address)
business_emailstring, (email)
Example:"ops@acmesupply.com"
business_phonestring
Example:"+15125550123"
entity_typestring
Enum:"corporation""llc""sole_proprietorship""partnership""non_profit"
Example:"llc"
formation_statestring
Example:"TX"
industrystring or null
Example:"Manufacturing"
websitestring or null, (uri)
Example:"https://acmesupply.com"
underwriting_statusstring

Current underwriting lifecycle status for the merchant.

Example:"pending"
seller_amount_approvedinteger or null

Merchant approved limit (MAL), when available.

Example:50000
active_subscriptionobject or null
metadataobject
document_ingestionobject(DocumentIngestionSummary)
created_atstring, (date-time)
Example:"2026-02-26T10:00:00.000Z"
updated_atstring, (date-time)
Example:"2026-02-26T10:05:00.000Z"
Response
{
  "id": "mrc_1234567890abcdef",
  "legal_business_name": "Acme Supply LLC",
  "dba_name": "Acme Industrial",
  "business_address": {
    "line1": "100 Main St",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  },
  "business_email": "ops@acmesupply.com",
  "business_phone": "+15125550123",
  "entity_type": "llc",
  "formation_state": "TX",
  "underwriting_status": "pending",
  "seller_amount_approved": 0,
  "active_subscription": {
    "id": "sub_1234567890abcdef",
    "tier": "trial"
  },
  "metadata": {
    "partner_reference": "mt-merchant-1029"
  },
  "created_at": "2026-02-26T10:00:00.000Z",
  "updated_at": "2026-02-26T10:00:00.000Z"
}