Skip to navigation
Boarding API

Update a merchant

Fully replace a merchant application and, optionally, change its status to retract or (re)send it for signature. Available only while the application is in the edit window — a merchant_status of new or sent_for_signature. Once signed or beyond, the record is locked and this returns 409.

Semantics:

  • Full replace. The request body is the complete merchant application (the same schema as POST /merchants); it replaces the merchant’s data in full. Send the application as it should now stand — the typical flow is read-modify-write: GET the merchant, apply your changes, PUT it back.
  • merchant_status: "new" retracts the application: every outstanding signature link is invalidated immediately. This is also the cancel flow — nothing is deleted, the record simply returns to new.
  • merchant_status: "sent_for_signature" issues a fresh single-use signature link to the signer as updated in the same request; if the application was already out for signature it is retracted first, so retract and resend happen atomically.
  • Any update to an application currently out for signature auto-retracts it back to new, so changed data can never sit under a live link. Include merchant_status: "sent_for_signature" in the same request to immediately reissue.
  • rep_code and platform must match the existing application and cannot be changed on update.
  • Sending can be expressed either way: merchant_status: "sent_for_signature", or the create-style auto_send_for_signature: true when merchant_status is omitted. An explicit merchant_status always wins — merchant_status: "new" retracts and does not send even if auto_send_for_signature is true.

Status changes fire the standard merchant.new and merchant.sent_for_signature webhooks.

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.

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.

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.

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