Webhooks Documentation

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": "Hala 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": "BH",
  "base_currency": "BHD",
  "charge_currenices": ["BHD"],
  "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": "Hala Brand SM_4327939499"
  },
  "legacy_id": "68014759",
  "linked": true,
  "linking_date": 1768992455576,
  "acceptance_status": "disabled",
  "acceptance_status_control": "legacy",
  "merchant": {
    "id": "merchant_rERhB10261042KkoF21mq0i34",
    "country": "BH",
    "base_currency": "BHD",
    "legacy_id": "68014756"
  },
  "brand": {
    "id": "brd_kaRhB14261040JLMn21lM0C880",
    "name": {
      "textId": "txt_vaiL14261040aEvL21LS0K781",
      "ar": "Hala Brand",
      "en": "Hala Brand"
    }
  },
  "wallet": {
    "id": "wal_P7RhB30261047y2Gy21SJ0M662",
    "base_currency": "BHD"
  },
  "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": "Hala POS Device"
  },
  "terminal_device": {
    "id": "terminal_device_WyRhB28261047xo4g21gq0k678",
    "serial_number": "SM_4327939499",
    "display_name": "Hala 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": "Hala Brand SM_1678183305"
  },
  "legacy_id": "68014795",
  "linked": false,
  "acceptance_status": "disabled",
  "acceptance_status_control": "legacy",
  "merchant": {
    "id": "merchant_rERhB10261042KkoF21mq0i34",
    "country": "BH",
    "base_currency": "BHD",
    "legacy_id": "68014756"
  },
  "brand": {
    "id": "brd_kaRhB14261040JLMn21lM0C880",
    "name": {
      "textId": "txt_vaiL14261040aEvL21LS0K781",
      "ar": "Hala Brand",
      "en": "Hala Brand"
    }
  },
  "wallet": {
    "id": "wal_B2RhB23261156qdTd21XB0N466",
    "base_currency": "BHD"
  },
  "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": "Hala 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"
  }
}