merchants.invalid_statusmerchantsRule R11Rule R14Rule R15Rule R16Rule R18Rule R21Rule R22Rule R23Rule R25Rule R27Rule R29Rule R34The merchant is not in a status that allows this
Twelve rules share this code — the whole onboarding and lifecycle state machine. Submit requires draft; start-review requires submitted; request-information, approve and reject require in_review (approving lands the merchant in sandbox); promote requires sandbox and moves it to approved; activate requires draft, sandbox or approved; suspend requires active; reinstate requires suspended; close refuses an already-closed merchant; bank-account verification requires pending or needs_review. The response names the statuses it moved between.
Why the API refuses
WHEN SubmitOnboarding is executed on a merchant in any other status, THE SYSTEM SHALL reject it naming the statuses it moved between.
WHEN StartReview is executed, THE SYSTEM SHALL reject it unless the status is submitted, and SHALL record the reviewer and emit MerchantInReview.
WHEN RequestMoreInformation is executed, THE SYSTEM SHALL reject it unless the status is in_review, and SHALL set information_requested true, record the message and emit MerchantInformationRequested.
WHEN ApproveMerchant is executed, THE SYSTEM SHALL reject it unless the status is in_review; WHERE the merchant's risk tier is at or above the platform setting dual_control_from_tier, THE SYSTEM SHALL require a second compliance operator's approval before the approval takes effect, and SHALL otherwise approve at once. Approving moves the merchant to sandbox (R17), never straight to approved.
WHEN RejectMerchant is executed, THE SYSTEM SHALL reject it unless the status is in_review, and SHALL record the reason and emit MerchantRejected.
WHEN VerifyBankAccount is executed, THE SYSTEM SHALL reject it unless the account's verification status is pending or needs_review, and SHALL record the method, the verifying operator and the instant, and emit BankAccountVerified.
WHEN ActivateMerchant is executed, THE SYSTEM SHALL reject it unless the merchant status is draft, sandbox or approved, and SHALL emit MerchantActivated.
WHEN SuspendMerchant is executed, THE SYSTEM SHALL reject it unless the status is active, and SHALL record the reason and the instant and emit MerchantSuspended in the same transaction.
WHEN ReinstateMerchant is executed, THE SYSTEM SHALL reject it unless the status is suspended, and SHALL require an approval by a second operations operator before the reinstatement takes effect.
WHEN CloseMerchant is executed, THE SYSTEM SHALL reject it if the status is already closed, and SHALL record the reason and the instant and emit MerchantClosed.
WHEN MarkBankAccountNeedsReview is executed, THE SYSTEM SHALL move the named account to needs_review so that compliance verifies it again before it receives a payout.
WHEN PromoteMerchant is executed, THE SYSTEM SHALL reject it unless the status is sandbox, and SHALL move the merchant to approved, emit MerchantApproved and tell the merchant's owners that it may now ask for live mode. It is one operator's decision: no second approval is required.
What to do
Read status and branch on it rather than on what the operator last clicked. Two of these transitions also need a second operator — approval above the dual_control_from_tier risk tier, and reinstatement always — so a call that looks accepted may be waiting on an approval rather than done.