GuidesWebhooks

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    "event_table_pk": 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    "event_table_pk": 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    "event_table_pk": 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    "event_table_pk": 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    "event_table_pk": 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    "event_table_pk": 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    "event_table_pk": 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    "event_table_pk": 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    "event_table_pk": 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}

VAR Complete Event

boarding.varcomplete

Triggered when boarding VAR (Visa Account Range) process is complete.

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

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
  4. Credential Management: Securely store and distribute gateway credentials after activation
  5. VAR Completion: Update merchant records when VAR completion occurs

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
  • Failed Activations: Handle cases where activation may be reversed due to compliance issues