Webhooks & Notifications
Overview
This document describes the webhook payloads sent by the Tap payment system for merchant lifecycle events. These webhooks notify your system about important changes to merchant accounts and terminal devices.
1. Merchant Signup Webhook
Triggered when a merchant completes the signup process with Tap.
Webhook Payload Structure
{
"id": "merchant_rERhB10261042KkoF21mq0i34",
"object": "merchant",
"live_mode": false,
"api_version": "v2",
"feature_version": "v1",
"status": "Active",
"created": 1768992141194,
"display_name": "Test Brand",
"business_id": "bus_0P4N14261040C2Ct21810Y286",
"business_entity_id": "ent_qJRhB3261042TpYA21uP04710",
"brand_id": "brd_kaRhB14261040JLMn21lM0C880",
"wallet_id": "wal_NfRhB10261042UQJb219i0a33",
"terminal_id": "terminal_YTRhB21261042CaXF212q0u584",
"board_id": "board_uPRhB24261042WXGo21WL01703",
"marketplace": false,
"country": "KW",
"base_currency": "KWD",
"charge_currenices": ["KWD"],
"legacy_id": "68014756",
"present_payments": true,
"is_acceptance_allowed": false,
"is_payout_allowed": false,
"acceptance_status": "disabled",
"payout_status": "disabled",
"metadata": {
"mtd": "metadata"
},
"payment_provider": {
"technology_id": "technology_EqJf46231515pLzg7GN84113",
"settlement_by": "payment_facilitator_0XGK1123156l5bx7eB7q584"
},
"platforms": [
{
"id": "retail_platform_HOUd1251118hhYW11H22i947",
"segment": "retailplatform",
"brand": {
"id": "brd_XhBj59251015Bxf7119s2Q863",
"name": [
{
"lang": "en",
"text": "khgjbknjkm Test"
}
],
"logo": ""
},
"plugins": [
{
"id": "plugin_ig494624102jcQk177E2E481",
"status": "Active"
}
]
}
],
"operator": {
"id": "opr_85RhB23261042hAly21Oh0T193",
"status": "Active",
"created": 1768992143873,
"object": "operator",
"live_mode": false,
"api_version": "v2",
"feature_version": "v1",
"name": "MERCHANT",
"business_entity_id": "ent_qJRhB3261042TpYA21uP04710",
"developer_id": "dev_U84N11261042igPs21Ro0F305",
"wallet_id": "wal_NfRhB10261042UQJb219i0a33",
"is_merchant": true,
"api_credentials": {
"test": {
"secret": "sk_test_85RhBamAuqzMYOVsGpwnt6cD0S9Hv",
"public": "pk_test_85RhBrgCxDU3qc6lz7P5denTVoZ1J"
}
}
},
"data_status": {
"base_currency": "editable",
"charge_currenices": "editable",
"acceptance_status": "editable",
"segment": "editable",
"country": "editable"
},
"data_verification": {
"base_currency": "entered",
"charge_currenices": "entered",
"acceptance_status": "entered",
"segment": "entered",
"country": "entered"
},
"data_state": "incomplete",
"post": {
"terminal_url": "https://webhook.site/71f7b4cf-4682-48c8-8566-eb5d960646cb",
"url": "https://webhook.site/71f7b4cf-4682-48c8-8566-eb5d960646cb"
},
"retailplatform": {
"id": "retail_platform_HOUd1251118hhYW11H22i947",
"name": {
"en": "khgjbknjkm Test"
},
"logo": "",
"operator_id": "opr_YTKT21251118TzR9115a2G600"
}
}2. Terminal Link Webhook
Triggered when a merchant registers or links a new terminal device via Connect Board.
Webhook Payload Structure
{
"id": "terminal_NCRhB30261047Z6Ej21Fq0Y662",
"status": "Inactive",
"created": 1768992455484,
"object": "terminal",
"live_mode": false,
"api_version": "v2",
"feature_version": "v1",
"name": {
"en": "Test Brand SM_4327939499"
},
"legacy_id": "68014759",
"linked": true,
"linking_date": 1768992455576,
"acceptance_status": "disabled",
"acceptance_status_control": "legacy",
"merchant": {
"id": "merchant_rERhB10261042KkoF21mq0i34",
"country": "KW",
"base_currency": "KWD",
"legacy_id": "68014756"
},
"brand": {
"id": "brd_kaRhB14261040JLMn21lM0C880",
"name": {
"textId": "txt_vaiL14261040aEvL21LS0K781",
"ar": "Test Brand",
"en": "Test Brand"
}
},
"wallet": {
"id": "wal_P7RhB30261047y2Gy21SJ0M662",
"base_currency": "KWD"
},
"authorizes": {
"status": "Not Active",
"status_message": "No Transactions available"
},
"charges": {
"status": "Not Active",
"status_message": "No Transactions available"
},
"refunds": {
"status": "Not Active",
"status_message": "No Transactions available"
},
"virtual": false,
"device": {
"id": "pos_device_j6RhB26261042O59R21Ig0H44",
"reference": "23927382838",
"display_name": "Test POS Device"
},
"terminal_device": {
"id": "terminal_device_WyRhB28261047xo4g21gq0k678",
"serial_number": "SM_4327939499",
"display_name": "Test Brand SM_4327939499",
"model": {
"id": "terminal_device_model_40oo1311012e8vJ527056",
"status": "active",
"object": "device",
"live_mode": false,
"api_version": "v2",
"feature_version": "v1",
"model": "A920Pro",
"type": "PHYSICAL",
"name": [
{
"lang": "en",
"text": "A920Pro"
}
],
"image": "file_ZXec45251131Olkh12jD4j987",
"image_url": "https://api.tap.company/v2/file_links/fl_live_1371449772174823425/content/live"
},
"appearance": {
"background": {
"color": "#ffffff"
}
}
},
"platform": {
"id": "retail_platform_HOUd1251118hhYW11H22i947",
"segment": "RETAILPLATFORM",
"brand": {
"id": "brd_XhBj59251015Bxf7119s2Q863",
"name": [
{
"lang": "en",
"text": "khgjbknjkm Test"
}
],
"logo": ""
}
},
"retailplatform": {
"id": "retail_platform_HOUd1251118hhYW11H22i947",
"name": {
"en": "khgjbknjkm Test"
},
"logo": "",
"operator_id": "opr_YTKT21251118TzR9115a2G600"
}
}3. Terminal Unlink Webhook
Triggered when a terminal is unlinked from the POS system.
Webhook Payload Structure
{
"id": "terminal_L1RhB23261156k7VT21jE0e466",
"status": "Inactive",
"created": 1768996588984,
"object": "terminal",
"live_mode": false,
"api_version": "v2",
"feature_version": "v1",
"name": {
"en": "Test Brand SM_1678183305"
},
"legacy_id": "68014795",
"linked": false,
"acceptance_status": "disabled",
"acceptance_status_control": "legacy",
"merchant": {
"id": "merchant_rERhB10261042KkoF21mq0i34",
"country": "KW",
"base_currency": "KWD",
"legacy_id": "68014756"
},
"brand": {
"id": "brd_kaRhB14261040JLMn21lM0C880",
"name": {
"textId": "txt_vaiL14261040aEvL21LS0K781",
"ar": "Test Brand",
"en": "Test Brand"
}
},
"wallet": {
"id": "wal_B2RhB23261156qdTd21XB0N466",
"base_currency": "KWD"
},
"authorizes": {
"status": "Not Active",
"status_message": "No Transactions available"
},
"charges": {
"status": "Not Active",
"status_message": "No Transactions available"
},
"refunds": {
"status": "Not Active",
"status_message": "No Transactions available"
},
"virtual": false,
"terminal_device": {
"id": "terminal_device_a8RhB21261156oE5A21v80e233",
"serial_number": "SM_1678183305",
"display_name": "Test Brand SM_1678183305",
"model": {
"id": "terminal_device_model_40oo1311012e8vJ527056",
"status": "active",
"object": "device",
"live_mode": false,
"api_version": "v2",
"feature_version": "v1",
"model": "A920Pro",
"type": "PHYSICAL",
"name": [
{
"lang": "en",
"text": "A920Pro"
}
],
"image": "file_ZXec45251131Olkh12jD4j987",
"image_url": "https://api.tap.company/v2/file_links/fl_live_1371449772174823425/content/live"
},
"appearance": {
"background": {
"color": "#ffffff"
}
}
},
"platform": {
"id": "retail_platform_HOUd1251118hhYW11H22i947",
"segment": "RETAILPLATFORM",
"brand": {
"id": "brd_XhBj59251015Bxf7119s2Q863",
"name": [
{
"lang": "en",
"text": "khgjbknjkm Test"
}
],
"logo": ""
}
},
"retailplatform": {
"id": "retail_platform_HOUd1251118hhYW11H22i947",
"name": {
"en": "khgjbknjkm Test"
},
"logo": "",
"operator_id": "opr_YTKT21251118TzR9115a2G600"
}
}4. Board URL Webhook
Webhook Payload Structure
{
"bi": "xxx",
"merchant": {
"id": "merchant_xxx",
"legacy_id": "68013440"
},
"brand": {
"id": "brd_xxx",
"name": {
"textId": "txt_Yv2a526152Po3f16870l93",
"en": "Merchant Name"
}
},
"board": {
"id": "board_VhErA3xxxxxY06342",
"url": "https://url-shortner.dev.tap.company/xxxxx"
},
"operator": {
"id": "opr_exxx",
"status": "Active",
"created": 1768575873150,
"object": "operator",
"live_mode": false,
"api_version": "v2",
"feature_version": "v1",
"name": "MERCHANT",
"business_entity_id": "ent_xxx",
"developer_id": "dev_xxx",
"wallet_id": "wal_xxx",
"is_merchant": true,
"api_credentials": {
"test": {
"secret": "sk_test_xxx",
"public": "pk_test_xxx"
}
}
},
"entity": {
"id": "ent_xxxx",
"country": "AE"
},
"authentication_id": "authentication_xxx"
}Updated 3 days ago
What’s Next
Did this page help you?