> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runpayments.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server.

# Boarding Webhooks

Boarding webhooks notify you about merchant onboarding status changes and specific boarding process events.

## Event Context: `trigger` and `reason`

Every `merchant.*` payload carries two fields describing **how** and **why** the change happened. The event type tells you the state the merchant is now in; these tell you what caused it.

| Field     | Values                                                                                               |
| --------- | ---------------------------------------------------------------------------------------------------- |
| `trigger` | `api` — a Boarding API call · `ui` — someone acting in Run Partner · `system` — an automated process |
| `reason`  | the business action, listed below                                                                    |

### Why this matters

Four different things can produce a `merchant.new` event:

| What happened                                                                   | `trigger` | `reason`            |
| ------------------------------------------------------------------------------- | --------- | ------------------- |
| A rep clicked **Recall Signature Request** in Run Partner                       | `ui`      | `retracted`         |
| An API caller sent `PUT /merchants/{merchant_id}` with `merchant_status: "new"` | `api`     | `retracted`         |
| An API caller updated an application that was out for signature                 | `api`     | `updated`           |
| Our 30-day sweep expired an unsigned application                                | `system`  | `signature_expired` |

Previously all four arrived as an indistinguishable `merchant.new`. If your integration takes action on `merchant.new` — creating a record, notifying a team — branch on `reason` rather than treating every occurrence as a brand-new application.

### `reason` values

`created` · `sent_for_signature` · `resent` · `retracted` · `updated` · `signed` · `in_underwriting` · `boarded` · `live` · `cancelled` · `declined` · `signature_expired` · `deleted` · `status_changed`

> **Warning**
>
> Treat `reason` as **open-ended, not a fixed enum**. `status_changed` is a fallback for transitions with no more specific meaning, and new values may be added over time. Ignore a value you do not recognise rather than failing on it.

### Resending emits a single event

Re-sending an application that is already out for signature retracts the outstanding link and issues a fresh one. That produces **one** event — `merchant.sent_for_signature` with `reason: resent` — not a `merchant.new` followed by a `merchant.sent_for_signature`.

A first send from `new` also produces one `merchant.sent_for_signature`, with `reason: sent_for_signature`. So the event type is the same either way, and `reason` tells you whether a previous link was replaced.

> **Note**
>
> There is no way to suppress webhooks for an individual request. The event stream is the record of what happened, so silencing it for one caller would leave other subscribers out of sync. Use `trigger` and `reason` to decide which events your integration should act on.

## Merchant Status Events

The following webhooks are triggered when a merchant's status changes during the boarding process. Each payload also carries `trigger` and `reason` — see [Event Context](#event-context-trigger-and-reason) above.

### `merchant.new`

Triggered when merchant status changes to "New".

```json
{
  "event_type": "merchant.new",
  "source_id": "88001",
  "timestamp": "2025-09-11T15:30:45.123Z",
  "payload": {
    "merchant_id": 88001,
    "mid": null,
    "rep_code_id": 7105,
    "customer_id": 88001,
    "dba_name": "New Business Venture",
    "merchant_status_id": 1,
    "external_crm_id": null,
    "custom_01": null,
    "trigger": "api",
    "reason": "created",
    "timestamp": "2025-09-11T15:30:45.100+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562401",
    "attempt": 1,
    "idempotency_key": "a1b2c3d4e5f6789012345678901234567890abcd"
  }
}
```

### `merchant.sent_for_signature`

Triggered when merchant status changes to "Sent For Signature".

```json
{
  "event_type": "merchant.sent_for_signature",
  "source_id": "91569",
  "timestamp": "2025-09-11T19:42:24.438Z",
  "payload": {
    "merchant_id": 91569,
    "mid": null,
    "rep_code_id": 7107,
    "customer_id": 88005,
    "dba_name": "The Bagel Shop - Breckenridge",
    "merchant_status_id": 2,
    "external_crm_id": null,
    "custom_01": null,
    "trigger": "api",
    "reason": "sent_for_signature",
    "timestamp": "2025-09-11T19:42:24.420+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562459",
    "attempt": 1,
    "idempotency_key": "97667363c9d970ba458dc90c1e92a374"
  }
}
```

### `merchant.signed`

Triggered when merchant status changes to "Signed".

```json
{
  "event_type": "merchant.signed",
  "source_id": "88003",
  "timestamp": "2025-09-12T08:15:30.456Z",
  "payload": {
    "merchant_id": 88003,
    "mid": null,
    "rep_code_id": 7107,
    "customer_id": 88003,
    "dba_name": "Downtown Coffee Shop",
    "merchant_status_id": 3,
    "external_crm_id": null,
    "custom_01": null,
    "trigger": "ui",
    "reason": "signed",
    "timestamp": "2025-09-12T08:15:30.420+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562461",
    "attempt": 1,
    "idempotency_key": "b2c3d4e5f6789012345678901234567890abcde"
  }
}
```

### `merchant.in_underwriting`

Triggered when merchant status changes to "In Underwriting".

```json
{
  "event_type": "merchant.in_underwriting",
  "source_id": "88004",
  "timestamp": "2025-09-12T14:20:15.789Z",
  "payload": {
    "merchant_id": 88004,
    "mid": null,
    "rep_code_id": 7108,
    "customer_id": 88004,
    "dba_name": "Mountain View Restaurant",
    "merchant_status_id": 4,
    "external_crm_id": null,
    "custom_01": null,
    "trigger": "system",
    "reason": "in_underwriting",
    "timestamp": "2025-09-12T14:20:15.750+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562475",
    "attempt": 1,
    "idempotency_key": "c3d4e5f6789012345678901234567890abcdef"
  }
}
```

### `merchant.boarded`

Triggered when merchant status changes to "Boarded".

```json
{
  "event_type": "merchant.boarded",
  "source_id": "88006",
  "timestamp": "2025-09-13T10:45:22.334Z",
  "payload": {
    "merchant_id": 88006,
    "mid": "496581123456789",
    "rep_code_id": 7109,
    "customer_id": 88006,
    "dba_name": "Tech Solutions Inc",
    "merchant_status_id": 5,
    "external_crm_id": "CRM-2025-001",
    "custom_01": "APPROVED",
    "trigger": "system",
    "reason": "boarded",
    "timestamp": "2025-09-13T10:45:22.300+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562490",
    "attempt": 1,
    "idempotency_key": "d4e5f6789012345678901234567890abcdef01"
  }
}
```

### `merchant.live`

Triggered when merchant status changes to "Live".

```json
{
  "event_type": "merchant.live",
  "source_id": "88007",
  "timestamp": "2025-09-13T16:20:33.567Z",
  "payload": {
    "merchant_id": 88007,
    "mid": "496581987654321",
    "rep_code_id": 7110,
    "customer_id": 88007,
    "dba_name": "Online Retail Store",
    "merchant_status_id": 6,
    "external_crm_id": "CRM-2025-002",
    "custom_01": "LIVE",
    "trigger": "system",
    "reason": "live",
    "timestamp": "2025-09-13T16:20:33.520+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562510",
    "attempt": 1,
    "idempotency_key": "e5f6789012345678901234567890abcdef0123"
  }
}
```

### `merchant.cancelled`

Triggered when merchant status changes to "Cancelled".

```json
{
  "event_type": "merchant.cancelled",
  "source_id": "88008",
  "timestamp": "2025-09-13T11:30:45.234Z",
  "payload": {
    "merchant_id": 88008,
    "mid": null,
    "rep_code_id": 7111,
    "customer_id": 88008,
    "dba_name": "Cancelled Business",
    "merchant_status_id": 7,
    "external_crm_id": null,
    "custom_01": "CANCELLED",
    "trigger": "ui",
    "reason": "cancelled",
    "timestamp": "2025-09-13T11:30:45.200+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562520",
    "attempt": 1,
    "idempotency_key": "f6789012345678901234567890abcdef012345"
  }
}
```

### `merchant.declined`

Triggered when merchant status changes to "Declined".

```json
{
  "event_type": "merchant.declined",
  "source_id": "88009",
  "timestamp": "2025-09-13T13:15:22.890Z",
  "payload": {
    "merchant_id": 88009,
    "mid": null,
    "rep_code_id": 7112,
    "customer_id": 88009,
    "dba_name": "High Risk Venture",
    "merchant_status_id": 8,
    "external_crm_id": "CRM-2025-DECLINED",
    "custom_01": "DECLINED",
    "trigger": "ui",
    "reason": "declined",
    "timestamp": "2025-09-13T13:15:22.850+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562530",
    "attempt": 1,
    "idempotency_key": "g789012345678901234567890abcdef0123456"
  }
}
```

### `merchant.unknown`

Triggered when merchant status changes to "Unknown".

```json
{
  "event_type": "merchant.unknown",
  "source_id": "88010",
  "timestamp": "2025-09-13T09:45:11.123Z",
  "payload": {
    "merchant_id": 88010,
    "mid": null,
    "rep_code_id": 7113,
    "customer_id": 88010,
    "dba_name": "Status Unknown Business",
    "merchant_status_id": 9,
    "external_crm_id": null,
    "custom_01": "ERROR",
    "trigger": "system",
    "reason": "status_changed",
    "timestamp": "2025-09-13T09:45:11.100+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562540",
    "attempt": 1,
    "idempotency_key": "h89012345678901234567890abcdef01234567"
  }
}
```

### `merchant.deleted`

Triggered when merchant record is deleted from Partner.

```json
{
  "event_type": "merchant.deleted",
  "source_id": "102398",
  "timestamp": "2026-01-07T04:11:13.499Z",
  "payload": {
    "merchant_id": 102398,
    "mid": null,
    "rep_code_id": 13308,
    "customer_id": 99092,
    "dba_name": "Test Merchant",
    "merchant_status_id": 1,
    "external_crm_id": "external 100010",
    "custom_01": "custom01222",
    "deleted_by": "integrations@runpayments.io",
    "trigger": "ui",
    "reason": "deleted",
    "timestamp": "2026-01-07T04:10:38.170+00:00"
  },
  "metadata": {
    "webhook_id": "wh_562934",
    "attempt": 1,
    "idempotency_key": "5c672af3e79155fcaf7dbae89279c294"
  }
}
```

## VAR Complete Event

### `boarding.varcomplete`

Triggered when the TSYS VAR Only process is complete.

```json
{
  "event_type": "boarding.varcomplete",
  "source_id": "12345",
  "timestamp": "2024-01-17T15:30:00.000Z",
  "payload": {
    "merchant_id": "88001",
    "acquirer_bin": "496581",
    "agent_bank_number": "000001",
    "agent_chain_number": "111111",
    "city": "Commerce City",
    "zip_code": "90210",
    "contact_phone": "5551234567",
    "merchant_aba_number": "123456789",
    "merchant_category_code": "5812",
    "merchant_location_number": "00001",
    "dba_name": "Acme Store",
    "mid": "496581000123456",
    "merchant_settlement_agent_number": "A001",
    "state": "CA",
    "store_number": "0001",
    "terminal_id": "T001ABC",
    "terminal_number": "0001",
    "time_zone": "America/Los_Angeles"
  },
  "metadata": {
    "webhook_id": "wh_var_001",
    "attempt": 1,
    "idempotency_key": "boarding-varcomplete-12345-20240117153000"
  }
}
```

## Integration Tips

1. **Status Tracking**: Maintain merchant status in your system based on webhook events
2. **Automated Communications**: Send status updates and next steps to merchants automatically
3. **Team Notifications**: Alert sales and support teams about status changes

## Error Handling

Handle potential issues in boarding webhooks:

* **Missing Data**: Some optional fields may be null depending on application completeness
* **Status Transitions**: Ensure your system can handle status changes in any order
* **Duplicate Events**: Use idempotency keys to prevent duplicate processing