Skip to navigation
Boarding API

Update a merchant

Replace a merchant application in full. Send the whole application, the same body as Create a merchant: GET the merchant, change what you need, and PUT it back.

You can update an application while its merchant_status is new or sent_for_signature. After it is signed, this returns 409.

  • To update an application and keep it out for signature, set merchant_status to sent_for_signature (or leave merchant_status out and send auto_send_for_signature: true). The signer gets a new link for the updated application, and you receive one merchant.sent_for_signature webhook with reason resent. No merchant.new webhook is sent.
  • Any other update voids the signature links and moves the application back to new. You receive merchant.new with reason updated, or retracted when you set merchant_status to new.
  • rep_code and platform can’t be changed.
  • If you leave out section_locks, the merchant’s locks stay as they are.

Authentication

AuthorizationBearer
This API uses OAuth 2.0 for authentication.

Path parameters

merchant_idintegerRequired
The unique identifier for the merchant

Request

This endpoint expects an object.
dba_namestringRequired<=150 characters

Doing Business As (DBA) name.

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.

signer_emailstringRequired<=150 characters
Email address of the signer.
signer_first_namestringRequired<=100 characters
First name of the signer.
signer_last_namestringRequired<=100 characters
Last name 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.

addresseslist of objectsOptional
List of addresses associated with the merchant.
annual_volumedoubleOptional
Annual transaction volume in dollars.
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.

auto_send_for_signaturebooleanOptional
If true, the application is emailed to the signer for signature when this request completes.
average_ticketdoubleOptional
Average transaction amount in dollars.
business_descstringOptional<=400 characters
Description of the business.
customer_iddoubleOptional
Used if adding to an existing account.
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.

in_person_pctdoubleOptional

Percentage of in-person transactions. Must sum to 100 with online_pct and telephone_pct.

is_testbooleanOptional
If true, the merchant is created as a test record.
legal_namestringOptional<=150 characters
Legal name of the business.
mcc_codestringOptional<=4 characters

Merchant Category Code (MCC). See /mcc for valid values. Ignored if application_template_id is provided.

merchant_statusenumOptional

Optional status action. new retracts (invalidates outstanding signature links); sent_for_signature (re)issues a fresh signature link to the signer. Omit to update application data without a status change.

Allowed values:
messagestringOptional<=4000 characters

Optional custom message included in the signature email. Only meaningful when merchant_status is sent_for_signature.

online_pctdoubleOptional

Percentage of online transactions. Must sum to 100 with in_person_pct and telephone_pct.

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.

ownership_typeenumOptional

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

Allowed values:
phonestringOptional<=12 characters

Phone number in the format ###-###-####.

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.

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.

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.
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.

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.
services_provided_inenumOptional
Timeframe for when services or goods are provided.
Allowed values:
signer_dobstringOptionalformat: "date"

Date of birth of the signer in the format mm/dd/yyyy.

signer_phonestringOptional<=12 characters

Phone number in the format ###-###-####.

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_ssnstringOptional
Social Security number of the signer.
tax_idstringOptional<=12 characters

Tax identification number. Must be a 9-digit number (dashes allowed).

telephone_pctdoubleOptional

Percentage of telephone transactions. Must sum to 100 with in_person_pct and online_pct.

websitestringOptional<=250 characters
Business website URL.
when_card_chargedenumOptional
When the card is charged.
Allowed values:
years_in_businessdoubleOptional
Number of years the business has been operating.

Response

Merchant updated successfully. Returns the full merchant record, the same shape as GET /merchants/{merchant_id}.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error