# Payload webhook affiliate

> JSON yang BCL hantar ke URL webhook anda apabila affiliate menyertai program anda atau referral diluluskan, ruangan demi ruangan.
>
> Source: https://docs.bcl.my/ms/webhook-affiliate/

Webhook affiliate memberitahu sistem anda sendiri apabila seseorang menyertai program affiliate anda atau apabila sesuatu referral diluluskan. BCL menghantar HTTP `POST` dengan body JSON ke satu URL yang anda tetapkan untuk seluruh program. Page ini menyenaraikan setiap ruangan.

Untuk API BCL yang penuh, lihat [rujukan API](https://bcl.my/docs/api).

## Tetapkan URL webhook anda

Webhook affiliate ditetapkan sekali untuk program anda, bukan untuk setiap payment form:

1. Pergi ke **Affiliate** → **Settings**.
2. Buka tab **Webhook Settings**.

   *(Screenshot: Page Manage Affiliate Commission Settings dengan tab Webhook Settings ditanda)*

3. On-kan **Enable Webhook**.
4. Masukkan **Webhook URL** anda.
5. Tandakan event yang anda mahu: **Affiliate Joined**, **Referral Approved** atau **Payout Request**.
6. Klik **Save Webhook Settings**.

   *(Screenshot: Enable Webhook on, satu URL webhook, Affiliate Joined dan Referral Approved ditandakan, dan butang Save Webhook Settings ditanda)*

> **Caution**
> **Payout Request** ada dalam senarai, tetapi versi BCL sekarang tidak menghantarnya. Jangan bina proses yang bergantung padanya buat masa ini.

## Event

Body ialah objek JSON rata tanpa pembalut `data`. Key `event` memberitahu anda event yang mana:

| `event` | Bila BCL menghantarnya |
| --- | --- |
| `affiliate_joined` | Seseorang menyertai program affiliate anda, termasuk apabila anda masih perlu meluluskan mereka. |
| `referral_approved` | Sesuatu referral diluluskan dan komisennya disahkan. |
| `payout_request` | Ada dalam senarai, tetapi tidak dihantar buat masa ini. |

Setiap payload ada `event`, `team_id`, `team_name`, objek `affiliate` dan `timestamp`.

## Affiliate joined

Ini ialah request `affiliate_joined`. Nilai-nilainya rekaan.

```json
{
  "event": "affiliate_joined",
  "team_id": "9ce445a9-21f4-4e2a-b6fa-226dbb2a14f3",
  "team_name": "Contoh Trading",
  "affiliate": {
    "id": 12,
    "name": "Siti binti Ahmad",
    "email": "siti@example.com",
    "phone": "+60198765432"
  },
  "timestamp": "2026-09-27 12:46:53 +08"
}
```

Maksud setiap ruangan:

| Ruangan | Jenis | Maksud |
| --- | --- | --- |
| `event` | string | `affiliate_joined`. |
| `team_id` | string | ID akaun BCL anda. |
| `team_name` | string | Nama perniagaan anda dalam BCL. |
| `affiliate.id` | number | ID affiliate. Sama dengan `affiliate_id` dalam webhook payment form. |
| `affiliate.name`, `affiliate.email`, `affiliate.phone` | string | Butiran affiliate. |
| `timestamp` | string | Masa BCL menghantarnya, `YYYY-MM-DD HH:MM:SS +08` (waktu Malaysia). |

## Referral approved

Request `referral_approved` menambah objek `referral`:

```json
{
  "event": "referral_approved",
  "team_id": "9ce445a9-21f4-4e2a-b6fa-226dbb2a14f3",
  "team_name": "Contoh Trading",
  "affiliate": {
    "id": 12,
    "name": "Siti binti Ahmad",
    "email": "siti@example.com",
    "phone": "+60198765432"
  },
  "referral": {
    "id": 82,
    "form_title": "Online Cooking Class",
    "transaction_id": "01jnszhdng1z4mxqwsfqd27k5w",
    "order_number": "LINK-05912",
    "amount": "100.00",
    "commission_amount": "10.00",
    "status": "approved",
    "referral_source": "direct",
    "ip_address": "203.0.113.10",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  },
  "timestamp": "2026-09-27 12:18:27 +08"
}
```

Maksud ruangan `referral`:

| Ruangan | Jenis | Maksud |
| --- | --- | --- |
| `id` | number | ID referral. Sama dengan `affiliate_data.referral_id` dalam webhook payment form. |
| `form_title` | string atau null | Tajuk payment form tempat jualan itu dibuat. Null jika referral itu tidak dipautkan kepada payment form. |
| `transaction_id` | string | ID dalaman jualan itu. |
| `order_number` | string | Nombor pesanan BCL bagi jualan itu. |
| `amount` | string | Amaun jualan yang menjadi asas komisen. |
| `commission_amount` | string | Komisen yang diperoleh. |
| `status` | string | Status referral, `approved`. |
| `referral_source` | string | Bagaimana pembeli sampai, contohnya `direct`. |
| `ip_address`, `user_agent` | string | Alamat IP dan browser pembeli semasa referral itu direkodkan. |

## Payout request

Sebagai rujukan, payload `payout_request` yang BCL sudah bina tetapi belum hantar menambah objek `payout_request` dengan `id`, `total_amount`, `status`, `requested_at`, `referral_count` dan senarai `referrals`. Setiap referral ada `id`, `order_number`, `commission_amount`, `status` dan `transaction_id`.

## Perubahan daripada contoh lama

Bentuk payload sama seperti contoh lama. Bezanya, BCL tidak menghantar `payout_request` buat masa ini, walaupun event itu ditandakan.

## Semak sama ada webhook itu tulen

BCL tidak menandatangani webhook. Tiada signature header atau shared secret. Untuk kekal selamat, guna URL yang sukar diteka, sahkan jualan itu melalui [API BCL](https://bcl.my/docs/api) sebelum membayar komisen, dan pastikan sistem anda selamat menerima event yang sama dua kali.

BCL menghantar setiap event sekali dan tidak menghantar semula secara automatik jika penghantaran gagal. Sebarang respons 2xx dikira sebagai berjaya dihantar. Setiap cubaan disenaraikan di bawah **Tools** → **Webhook Logs**, dan anda boleh **Resend** dari situ.

## Isu biasa

### Boleh saya hantar webhook affiliate ke lebih daripada satu URL?

Tidak boleh. Webhook affiliate hanya menerima satu Webhook URL untuk seluruh program. Jika beberapa sistem memerlukan data itu, halakan webhook ke satu endpoint yang forward data itu kepada sistem lain.

### Bagaimana saya tahu jualan mana untuk sesuatu webhook referral_approved?

Guna referral.order_number. Ia ialah nombor pesanan BCL, nilai yang sama dengan record_id dalam webhook payment form (/ms/webhook-payment-form/).

### Endpoint saya tidak berfungsi semasa seorang affiliate menyertai program. Boleh saya dapatkan webhook itu semula?

Boleh. Pergi ke Tools → Webhook Logs, cari baris yang gagal pada tab All dan klik Resend dalam menunya. Webhook affiliate tiada form, jadi ia tidak dipaparkan di bawah tab jenis form.