Skip to navigation
Boarding API

Create a new merchant

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.
  • When section_locks.mode_of_transaction is true (sent in the request or inherited from the application_template_id), those three values must total exactly 100, or the request is rejected with 422 and no merchant is created.
  • 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.

Authentication

AuthorizationBearer
This API uses OAuth 2.0 for authentication.

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.

Allowed values:
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. On create, a merchant created from a template whose mode of transaction is locked starts locked, unless section_locks.mode_of_transaction is sent in the same request.

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.
Allowed values:
services_provided_inenumOptional
Timeframe for when services or goods are provided.
Allowed values:
refund_policyenumOptional
Refund policy.
Allowed values:
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.

section_locksobjectOptional

Locks sections of the merchant application so the merchant cannot change them while completing it. Each key is a lock group and each value is a boolean. Run Partner users can still edit locked values.

  • On create, an omitted key means unlocked (or the template’s lock state when application_template_id is provided).
  • On update, an omitted key keeps the merchant’s stored lock state.
  • When mode_of_transaction is true, in_person_pct + online_pct + telephone_pct must total exactly 100 (after any values taken from application_template_id), or the request returns 422.
  • An unknown key, a non-boolean value, or a section_locks that is not an object returns 400.
ownership_typeenumOptional

Additional platform-specific ownership types:
Fiserv - tax_exempt, public_corp, private_corp.
Payroc - s_corp, c_corp, other.

Allowed values:
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 when this request completes.
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.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error