Submerchant Status Changed webhook
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: a user changes the Status on the Edit Submerchant page, selects Delete Submerchant, or selects Cancel with Processor on the submerchant's details page.
- API: a call to Update Submerchant Information with an
/AccountStatusoperation, Disable a Submerchant, Hold a Submerchant, or Release a Held Submerchant. - Automatic holds and releases: Backoffice moves a submerchant to
HoldAllFundingwhen it fails underwriting or a deposit to it is returned, and toActivewhen it passes underwriting.
The event fires only when the status actually changes. It does not fire when a submerchant is boarded, or when a request sets the status the submerchant already has.
Payload Schema
Top-Level Fields
| Field | Type | Description |
|---|---|---|
TenantSlug | String | Unique identifier for the tenant. |
MerchantMid | String | Merchant ID (MID) assigned by the processor. Null if the submerchant has no MID. |
MerchantId | Integer | Internal submerchant identifier. Use it with Review Submerchant Information. |
EventId | String | Unique identifier (UUID) for this event. Retries and replays of the same event carry the same value. |
EventType | String | The 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). |
PreviousStatus | Integer | The submerchant's status before the change. See Status Values below. |
NewStatus | Integer | The submerchant's status after the change. See Status Values below. |
ChangedAt | String | When the status changed, in ISO 8601 format with a UTC offset. |
CancelledDate | String | The 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. |
CloseReasonText | String | The close reason used with this change. Populated only for Cancelled and Escalated events that include a reason. |
Notes | String | The close notes entered with this change, up to 2,000 characters. Populated only for Cancelled and Escalated events that include notes. |
Status Values
| Value | Status |
|---|---|
0 | Active |
1 | HoldAllFunding |
2 | Canceled |
3 | WaitingForFirstTrans |
4 | WaitingForFirstAuth |
5 | CancelledWithProcessor |
99 | Deleted |
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:
- Use
EventIdto detect duplicates. A retried or replayed delivery carries the sameEventIdas the original, so skip any event that was already processed. - Check
EventTypeto decide what to update. ForCancelled, mark the submerchant closed in your system and storeCancelledDate,CloseReasonText, andNotes. ForReactivated, mark it open and clear the stored closure details. ForEscalatedandStatusChanged, update the stored status fromNewStatus. - Compare
PreviousStatuswith the status you have stored. If they differ, you may have missed an event or received events out of order. UseChangedAtto order events, and call Review Submerchant Information withMerchantIdto get the current status. - Store
MerchantIdandMerchantMidto match events to submerchants in your system.
Updated 23 days ago

