Boarding Webhooks

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

Merchant Status Events

The following webhooks are triggered when a merchant’s status changes during the boarding process:

`merchant.new`

Triggered when merchant status changes to “New”.

1 {
2   "event_type": "merchant.new",
3   "source_id": "88001",
4   "timestamp": "2025-09-11T15:30:45.123Z",
5   "payload": {
6     "merchant_id": 88001,
7     "mid": null,
8     "rep_code_id": 7105,
9     "customer_id": 88001,
10     "dba_name": "New Business Venture",
11     "merchant_status_id": 1,
12     "external_crm_id": null,
13     "custom_01": null,
14     "timestamp": "2025-09-11T15:30:45.100+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562401",
18     "attempt": 1,
19     "idempotency_key": "a1b2c3d4e5f6789012345678901234567890abcd"
20   }
21 }

`merchant.sent_for_signature`

Triggered when merchant status changes to “Sent For Signature”.

1 {
2   "event_type": "merchant.sent_for_signature",
3   "source_id": "91569",
4   "timestamp": "2025-09-11T19:42:24.438Z",
5   "payload": {
6     "merchant_id": 91569,
7     "mid": null,
8     "rep_code_id": 7107,
9     "customer_id": 88005,
10     "dba_name": "The Bagel Shop - Breckenridge",
11     "merchant_status_id": 2,
12     "external_crm_id": null,
13     "custom_01": null,
14     "timestamp": "2025-09-11T19:42:24.420+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562459",
18     "attempt": 1,
19     "idempotency_key": "97667363c9d970ba458dc90c1e92a374"
20   }
21 }

`merchant.signed`

Triggered when merchant status changes to “Signed”.

1 {
2   "event_type": "merchant.signed",
3   "source_id": "88003",
4   "timestamp": "2025-09-12T08:15:30.456Z",
5   "payload": {
6     "merchant_id": 88003,
7     "mid": null,
8     "rep_code_id": 7107,
9     "customer_id": 88003,
10     "dba_name": "Downtown Coffee Shop",
11     "merchant_status_id": 3,
12     "external_crm_id": null,
13     "custom_01": null,
14     "timestamp": "2025-09-12T08:15:30.420+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562461",
18     "attempt": 1,
19     "idempotency_key": "b2c3d4e5f6789012345678901234567890abcde"
20   }
21 }

`merchant.in_underwriting`

Triggered when merchant status changes to “In Underwriting”.

1 {
2   "event_type": "merchant.in_underwriting",
3   "source_id": "88004",
4   "timestamp": "2025-09-12T14:20:15.789Z",
5   "payload": {
6     "merchant_id": 88004,
7     "mid": null,
8     "rep_code_id": 7108,
9     "customer_id": 88004,
10     "dba_name": "Mountain View Restaurant",
11     "merchant_status_id": 4,
12     "external_crm_id": null,
13     "custom_01": null,
14     "timestamp": "2025-09-12T14:20:15.750+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562475",
18     "attempt": 1,
19     "idempotency_key": "c3d4e5f6789012345678901234567890abcdef"
20   }
21 }

`merchant.boarded`

Triggered when merchant status changes to “Boarded”.

1 {
2   "event_type": "merchant.boarded",
3   "source_id": "88006",
4   "timestamp": "2025-09-13T10:45:22.334Z",
5   "payload": {
6     "merchant_id": 88006,
7     "mid": "496581123456789",
8     "rep_code_id": 7109,
9     "customer_id": 88006,
10     "dba_name": "Tech Solutions Inc",
11     "merchant_status_id": 5,
12     "external_crm_id": "CRM-2025-001",
13     "custom_01": "APPROVED",
14     "timestamp": "2025-09-13T10:45:22.300+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562490",
18     "attempt": 1,
19     "idempotency_key": "d4e5f6789012345678901234567890abcdef01"
20   }
21 }

`merchant.live`

Triggered when merchant status changes to “Live”.

1 {
2   "event_type": "merchant.live",
3   "source_id": "88007",
4   "timestamp": "2025-09-13T16:20:33.567Z",
5   "payload": {
6     "merchant_id": 88007,
7     "mid": "496581987654321",
8     "rep_code_id": 7110,
9     "customer_id": 88007,
10     "dba_name": "Online Retail Store",
11     "merchant_status_id": 6,
12     "external_crm_id": "CRM-2025-002",
13     "custom_01": "LIVE",
14     "timestamp": "2025-09-13T16:20:33.520+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562510",
18     "attempt": 1,
19     "idempotency_key": "e5f6789012345678901234567890abcdef0123"
20   }
21 }

`merchant.cancelled`

Triggered when merchant status changes to “Cancelled”.

1 {
2   "event_type": "merchant.cancelled",
3   "source_id": "88008",
4   "timestamp": "2025-09-13T11:30:45.234Z",
5   "payload": {
6     "merchant_id": 88008,
7     "mid": null,
8     "rep_code_id": 7111,
9     "customer_id": 88008,
10     "dba_name": "Cancelled Business",
11     "merchant_status_id": 7,
12     "external_crm_id": null,
13     "custom_01": "CANCELLED",
14     "timestamp": "2025-09-13T11:30:45.200+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562520",
18     "attempt": 1,
19     "idempotency_key": "f6789012345678901234567890abcdef012345"
20   }
21 }

`merchant.declined`

Triggered when merchant status changes to “Declined”.

1 {
2   "event_type": "merchant.declined",
3   "source_id": "88009",
4   "timestamp": "2025-09-13T13:15:22.890Z",
5   "payload": {
6     "merchant_id": 88009,
7     "mid": null,
8     "rep_code_id": 7112,
9     "customer_id": 88009,
10     "dba_name": "High Risk Venture",
11     "merchant_status_id": 8,
12     "external_crm_id": "CRM-2025-DECLINED",
13     "custom_01": "DECLINED",
14     "timestamp": "2025-09-13T13:15:22.850+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562530",
18     "attempt": 1,
19     "idempotency_key": "g789012345678901234567890abcdef0123456"
20   }
21 }

`merchant.unknown`

Triggered when merchant status changes to “Unknown”.

1 {
2   "event_type": "merchant.unknown",
3   "source_id": "88010",
4   "timestamp": "2025-09-13T09:45:11.123Z",
5   "payload": {
6     "merchant_id": 88010,
7     "mid": null,
8     "rep_code_id": 7113,
9     "customer_id": 88010,
10     "dba_name": "Status Unknown Business",
11     "merchant_status_id": 9,
12     "external_crm_id": null,
13     "custom_01": "ERROR",
14     "timestamp": "2025-09-13T09:45:11.100+00:00"
15   },
16   "metadata": {
17     "webhook_id": "wh_562540",
18     "attempt": 1,
19     "idempotency_key": "h89012345678901234567890abcdef01234567"
20   }
21 }

`merchant.deleted`

Triggered when merchant record is deleted from Partner.

1 {
2   "event_type": "merchant.deleted",
3   "source_id": "102398",
4   "timestamp": "2026-01-07T04:11:13.499Z",
5   "payload": {
6     "merchant_id": 102398,
7     "mid": null,
8     "rep_code_id": 13308,
9     "customer_id": 99092,
10     "dba_name": "Test Merchant",
11     "merchant_status_id": 1,
12     "external_crm_id": "external 100010",
13     "custom_01": "custom01222",
14     "deleted_by": "integrations@runpayments.io",
15     "timestamp": "2026-01-07T04:10:38.170+00:00"
16   },
17   "metadata": {
18     "webhook_id": "wh_562934",
19     "attempt": 1,
20     "idempotency_key": "5c672af3e79155fcaf7dbae89279c294"
21   }
22 }

VAR Complete Event

`boarding.varcomplete`

Triggered when the TSYS VAR Only process is complete.

1 {
2   "event_type": "boarding.varcomplete",
3   "source_id": "12345",
4   "timestamp": "2024-01-17T15:30:00.000Z",
5   "payload": {
6     "merchant_id": "88001",
7     "acquirer_bin": "496581",
8     "agent_bank_number": "000001",
9     "agent_chain_number": "111111",
10     "city": "Commerce City",
11     "zip_code": "90210",
12     "contact_phone": "5551234567",
13     "merchant_aba_number": "123456789",
14     "merchant_category_code": "5812",
15     "merchant_location_number": "00001",
16     "dba_name": "Acme Store",
17     "mid": "496581000123456",
18     "merchant_settlement_agent_number": "A001",
19     "state": "CA",
20     "store_number": "0001",
21     "terminal_id": "T001ABC",
22     "terminal_number": "0001",
23     "time_zone": "America/Los_Angeles"
24   },
25   "metadata": {
26     "webhook_id": "wh_var_001",
27     "attempt": 1,
28     "idempotency_key": "boarding-varcomplete-12345-20240117153000"
29   }
30 }

Integration Tips

Status Tracking: Maintain merchant status in your system based on webhook events
Automated Communications: Send status updates and next steps to merchants automatically
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