Create a new merchant in Run Partner. A successful request returns a `201` status with a `merchant_id` that can be used in subsequent API calls to retrieve updated merchant data.
Validation notes:
- `in_person_pct` + `online_pct` + `telephone_pct` must sum to 100 when provided.
- `tax_id`, when provided, must be a 9-digit number (dashes allowed).
- Phone numbers, when provided, must be 10 digits in the format `###-###-####`.
- The `platform` must match the platform of the supplied `rep_code`.
- The sum of `signer_ownership_pct` and all `owners[].ownership_pct` values must not exceed 100.
Request
This endpoint expects an object.
platformenumRequired
Currently supporting Fiserv and Payroc. Additional platforms may be added in the future. Must match the platform of the supplied rep_code.
rep_codestringRequired
Must be a rep_code that exists on your account. See the /rep_codes endpoint.
dba_namestringRequired<=150 characters
Doing Business As (DBA) name.
signer_first_namestringRequired<=100 characters
First name of the signer.
signer_last_namestringRequired<=100 characters
Last name of the signer.
signer_emailstringRequired<=150 characters
Email address of the signer.
signer_ownership_pctdoubleRequired
Ownership percentage of the signer (0-100). The sum of the signer’s and all additional owners’ ownership percentages must not exceed 100.
customer_iddoubleOptional
Used if adding to an existing account.
application_template_iddoubleOptional
ID of the application template to use. Must be an application template available to your rep codes. If provided, mcc_code, business_desc, transaction percentages, volume fields, pricing, fees, and products are taken from the template.
legal_namestringOptional<=150 characters
Legal name of the business.
tax_idstringOptional<=12 characters
Tax identification number. Must be a 9-digit number (dashes allowed).
years_in_businessdoubleOptional
Number of years the business has been operating.
websitestringOptional<=250 characters
Business website URL.
phonestringOptional<=12 characters
Phone number in the format ###-###-####.
mcc_codestringOptional<=4 characters
Merchant Category Code (MCC). See /mcc for valid values. Ignored if application_template_id is provided.
business_descstringOptional<=400 characters
Description of the business.
when_card_chargedenumOptional
When the card is charged.
services_provided_inenumOptional
Timeframe for when services or goods are provided.
refund_policyenumOptional
Refund policy.
seasonalbooleanOptional
Indicates if the business is seasonal.
seasonal_monthsstringOptional<=30 characters
Colon-delimited month numbers (e.g., 1:2:10 for January, February, and October). Required if seasonal is true.
annual_volumedoubleOptional
Annual transaction volume in dollars.
average_ticketdoubleOptional
Average transaction amount in dollars.
in_person_pctdoubleOptional
Percentage of in-person transactions. Must sum to 100 with online_pct and telephone_pct.
online_pctdoubleOptional
Percentage of online transactions. Must sum to 100 with in_person_pct and telephone_pct.
telephone_pctdoubleOptional
Percentage of telephone transactions. Must sum to 100 with in_person_pct and online_pct.
ownership_typeenumOptional
Additional platform-specific ownership types:
Fiserv - tax_exempt, public_corp, private_corp.
Payroc - s_corp, c_corp, other.
signer_dobstringOptionalformat: "date"
Date of birth of the signer in the format mm/dd/yyyy.
signer_ssnstringOptional
Social Security number of the signer.
signer_res_address1stringOptional<=150 characters
Residential address line 1 of the signer.
signer_res_address2stringOptional<=150 characters
Residential address line 2 of the signer.
signer_res_citystringOptional<=150 characters
Residential city of the signer.
signer_res_statestringOptional<=2 characters
Residential state of the signer (uppercase 2-character abbreviation).
signer_res_zipstringOptional<=10 characters
Residential ZIP code of the signer.
signer_phonestringOptional<=12 characters
Phone number in the format ###-###-####.
ownerslist of objectsOptional
Additional non-signing owners. The signer is always submitted via the top-level signer_* fields; use this array only for other owners.
addresseslist of objectsOptional
List of addresses associated with the merchant.
pricingobjectOptional
Pricing details for the merchant. See the /pricing_types endpoint for the pricing types and fields available for each platform. Ignored if application_template_id is provided.
feesobjectOptional
Fee details for the merchant. See the /platform_fees endpoint for the fees available for each platform. Ignored if application_template_id is provided.
productslist of objectsOptional
List of products associated with the merchant. See the /products endpoint for the product catalog. Ignored if application_template_id is provided.
auto_send_for_signaturebooleanOptional
If true, the application is emailed to the signer for signature once this request completes. On create (POST) this sends the initial signature request. On update (PUT) it (re)issues a fresh signature link and applies only when merchant_status is omitted — an explicit merchant_status takes precedence.
prospect_sourcestringOptional<=350 characters
Source attribution for the prospect record.
prospect_source_1stringOptional<=1000 characters
Additional source attribution for the prospect record.
prospect_source_2stringOptional<=1000 characters
Additional source attribution for the prospect record.
is_testbooleanOptional
If true, the merchant is created as a test record.
Response
Merchant created successfully.
merchant_idstring or nullOptional
Unique identifier for the created merchant. Null if the request failed.
error_messagestring or nullOptional
Description of the validation failure. Null if the request succeeded.
