Submerchant Status Changed

📘

The Launchpay team sets up webhook subscriptions for you. To subscribe, send a request on the Customer Support Portal with the destination URL of your webhook endpoint.

Overview

The SubmerchantStatusChanged webhook (Type 10) fires when a submerchant's account status changes in Backoffice, including when a submerchant is cancelled, reopened, held, or released. Use this event to keep submerchant statuses in your system in sync without polling, and to record when and why a submerchant was closed.

Trigger Conditions

This event fires when a submerchant's account status changes through any of the following:

  • Backoffice: the Launchpay team changes the submerchant's status, including when it closes or reopens a submerchant at your request.
  • Automatic holds and releases: Backoffice moves a submerchant to HoldAllFunding when it fails underwriting or a deposit to it is returned, and to Active when it passes underwriting.

The event fires only when the status actually changes. It does not fire when a submerchant is boarded, or when a change sets the status the submerchant already has.

Payload Schema

Top-Level Fields

FieldTypeDescription
TenantSlugStringUnique identifier for the tenant.
MerchantMidStringMerchant ID (MID) assigned by the processor. Null if the submerchant has no MID.
MerchantIdIntegerInternal submerchant identifier. Use it with Review Submerchant Information.
EventIdStringUnique identifier (UUID) for this event. Retries and replays of the same event carry the same value.
EventTypeStringThe kind of status change. Values: Cancelled (an open status became a closed one), Escalated (one closed status became another), Reactivated (a closed status became an open one), StatusChanged (any change between open statuses).
PreviousStatusIntegerThe submerchant's status before the change. See Status Values below.
NewStatusIntegerThe submerchant's status after the change. See Status Values below.
ChangedAtStringWhen the status changed, in ISO 8601 format with a UTC offset.
CancelledDateStringThe date the submerchant was first closed, in ISO 8601 format with a UTC offset. Populated while the new status is closed, and keeps the original date when one closed status changes to another. Null otherwise.
CloseReasonTextStringThe close reason recorded with this change. Populated only for Cancelled and Escalated events that include a reason.
NotesStringThe close notes recorded with this change, up to 2,000 characters. Populated only for Cancelled and Escalated events that include notes.

Status Values

ValueStatus
0Active
1HoldAllFunding
2Canceled
3WaitingForFirstTrans
4WaitingForFirstAuth
5CancelledWithProcessor
99Deleted
📘

Note

Values 6 to 98 are not used. Statuses 2, 5, and 99 are closed statuses.

Example Payloads

A submerchant cancelled with a close reason:

{
  "TenantSlug": "examplepayfac",
  "MerchantMid": "123456789012",
  "MerchantId": 4821,
  "EventId": "3f2c9b1e-7a4d-4c8e-9a51-2b7d0e6c1f90",
  "EventType": "Cancelled",
  "PreviousStatus": 0,
  "NewStatus": 2,
  "ChangedAt": "2026-10-09T15:04:05.1234567+00:00",
  "CancelledDate": "2026-10-09T15:04:05.1234567+00:00",
  "CloseReasonText": "Business closed / ceased operations",
  "Notes": "Owner retired and closed the storefront."
}

The same submerchant reopened. The closure details return as null:

{
  "TenantSlug": "examplepayfac",
  "MerchantMid": "123456789012",
  "MerchantId": 4821,
  "EventId": "c7a41e95-2b6d-4f08-9d3c-5e8f1a2b7c64",
  "EventType": "Reactivated",
  "PreviousStatus": 2,
  "NewStatus": 0,
  "ChangedAt": "2026-10-12T14:31:07.2804926+00:00",
  "CancelledDate": null,
  "CloseReasonText": null,
  "Notes": null
}

A submerchant moved to HoldAllFunding:

{
  "TenantSlug": "examplepayfac",
  "MerchantMid": "123456789012",
  "MerchantId": 4821,
  "EventId": "9b7e4a2c-1d3f-4e6a-8c5b-0f2d7e9a4b16",
  "EventType": "StatusChanged",
  "PreviousStatus": 0,
  "NewStatus": 1,
  "ChangedAt": "2026-10-09T16:20:41.5550000+00:00",
  "CancelledDate": null,
  "CloseReasonText": null,
  "Notes": null
}

Handling This Event

Your webhook endpoint should handle each delivery as follows:

  1. Use EventId to detect duplicates. A retried or replayed delivery carries the same EventId as the original, so skip any event that was already processed.
  2. Check EventType to decide what to update. For Cancelled, mark the submerchant closed in your system and store CancelledDate, CloseReasonText, and Notes. For Reactivated, mark it open and clear the stored closure details. For Escalated and StatusChanged, update the stored status from NewStatus.
  3. Compare PreviousStatus with the status you have stored. If they differ, you may have missed an event or received events out of order. Use ChangedAt to order events, and call Review Submerchant Information with MerchantId to get the current status.
  4. Store MerchantId and MerchantMid to match events to submerchants in your system.

Did this page help you?