Payload webhook payment form

Webhook membolehkan BCL memberitahu sistem anda sendiri tentang sesuatu jualan sebaik sahaja ia berlaku. Apabila pelanggan menghantar payment form, atau bayaran mereka berjaya atau gagal, BCL menghantar HTTP POST dengan body JSON ke setiap URL yang anda tetapkan. Page ini menyenaraikan setiap ruangan dalam body itu.

Untuk API BCL yang penuh, lihat rujukan API.

Tetapkan URL webhook anda

Anda menetapkan webhook untuk setiap payment form. Untuk on-kan webhook:

1. Pergi ke Payments → Forms dan buka payment form anda.

2. Klik Advanced di bahagian atas.

   

3. Buka tab Webhook Settings dan on-kan Enable Webhook.

   

4. Di bawah Webhook URLs, masukkan endpoint anda. Jika tiada kotak dipaparkan, klik Add Webhook URL dahulu. Klik Add Webhook URL sekali lagi untuk menambah lebih banyak URL, sehingga 10. Setiap URL mesti bermula dengan https://, dan setiap URL menerima event yang sama.

5. Di bawah Webhook Events, tandakan event yang anda mahu.

6. Klik Save Advanced Settings.

Untuk mencuba endpoint anda tanpa jualan sebenar, klik Send Test dalam bahagian Webhook Configuration. Butang ini dipaparkan selepas webhook di-on-kan dan ada URL. Pilih Event Type, semak Webhook URL dan Payload Preview, kemudian klik Send Test Webhook. Payload test menggunakan nilai contoh rawak.

BCL kemudian memaparkan Test Webhook Sent dengan kod status endpoint anda, atau Webhook Failed dengan status dan permulaan reply-nya. Webhook test tidak disenaraikan dalam Webhook Logs.

Event form dan booking form ada tab Webhook Settings yang sama di bawah Advanced, dengan payload bayaran yang sama seperti di page ini.

Event

Setiap body request ada dua key: event (nama event) dan data (payload). Event ini menggunakan payload di page ini:

Event	Bila BCL menghantarnya
form-submit	Pelanggan menghantar payment form, sebelum bayaran.
payment-success	Bayarcash mengesahkan bayaran.
payment-failed	Bayaran gagal atau dibatalkan.

Untuk payment form Direct Debit, lihat Payload webhook Direct Debit. Event form juga boleh menghantar ticket-checked-in, dan booking form pula booking-confirmed dan booking-cancelled. Event ini menggunakan payload yang berbeza.

Contoh payload

Ini ialah request payment-success. Nilai-nilainya rekaan.

{
  "event": "payment-success",
  "data": {
    "formable_type": "payment_form",
    "formable_id": 210,
    "form_title": "Online Cooking Class",
    "form_url": "https://shop.example.com/form/online-cooking-class",
    "form_featured_image": "https://cdn.example.com/banner.jpg",
    "record_type": "Transaction",
    "record_id": "LINK-02046",
    "main_data": {
      "id": "01jfps609t08vjb8d5exq27bz6",
      "payer_name": "Ali bin Abu",
      "payer_email": "ali@example.com",
      "payer_telephone_number": "+60123456789",
      "order_number": "LINK-02046",
      "transaction_type": "live",
      "currency": "MYR",
      "subtotal_amount": "100.00",
      "fee_amount": "1.00",
      "amount": "101.00",
      "payment_channel": "FPX",
      "status": 3,
      "status_description": "Approved",
      "created_at": "27/09/2026 14:05:09",
      "customer_id": "01jfps5zq1m2k8c4x7v9b3n6td",
      "is_paid": 1,
      "retry_count": 0,
      "source_type": "payment_form",
      "items": [
        {
          "id": 5501,
          "index": 101,
          "productable_type": "product_item",
          "productable_id": 101,
          "item": "Cooking Class Recording",
          "sku": "CC-001",
          "option": "",
          "quantity": 1,
          "unit_amount": "100.00",
          "normal_price": "120.00",
          "sale_price": "100.00",
          "amount": "100.00",
          "access_url": null,
          "weight": "0.00",
          "total_weight": "0.00",
          "metadata": null,
          "product_image": "https://cdn.example.com/class.jpg",
          "protected_content": [
            {
              "title": "Module 1",
              "url": "https://shop.example.com/content/abc123token",
              "access_finder_url": "https://shop.example.com/content/7/access"
            }
          ]
        }
      ]
    },
    "tracking_params": {
      "utm_source": "facebook",
      "utm_campaign": "september-promo"
    },
    "receipt_url": "https://bcl.my/storage/pdf/LINK-02046.pdf",
    "custom_fields_data": {
      "address_line1": "1 Jalan Contoh",
      "city": "Kajang",
      "state": "Selangor",
      "postal_code": "43000",
      "country": "MY"
    },
    "affiliate_data": {
      "referral_id": 57,
      "affiliate_id": 12,
      "affiliate_username": "siti",
      "affiliate_name": "Siti binti Ahmad",
      "affiliate_email": "siti@example.com",
      "affiliate_phone": "+60198765432",
      "commission_type": "percentage",
      "commission_rate": "10.00",
      "commission_amount": "10.00",
      "commission_breakdown": null,
      "status": "approved",
      "referral_source": "direct"
    }
  }
}

Ruangan peringkat atas

Objek data mengandungi key berikut:

Ruangan	Jenis	Maksud
formable_type	string	Jenis form: payment_form, event_form atau booking_form.
formable_id	number	ID payment form. Menggantikan form_id yang lama.
form_title	string	Tajuk form. Untuk event form, nama event itu.
form_url	string	Link awam ke payment form. Kosong jika payment form itu tiada slug atau domain.
form_featured_image	string	URL featured image, atau kosong.
record_type	string	Sentiasa Transaction di page ini.
record_id	string	Nombor pesanan BCL, contohnya LINK-02046. Guna nombor ini untuk memadankan rekod.
main_data	object	Pesanan itu. Lihat bahagian seterusnya.
tracking_params	object atau null	UTM dan click ID yang direkodkan semasa pelanggan membuka payment form: utm_source, utm_medium, utm_campaign, utm_content, utm_term, utm_id, fbclid, ttclid, gclid. Hanya yang ada dihantar.
receipt_url	string	payment-success sahaja. Link ke resit PDF. Sesiapa yang membukanya perlu mengesahkan dengan kod sekali guna dahulu.
custom_fields_data	object	Custom field dan ruangan alamat payment form, dengan nama ruangan sebagai key. Tiada jika payment form itu tidak ada ruangan tersebut.
affiliate_data	object	Hanya ada apabila affiliate yang membawa jualan itu.

Ruangan pesanan (main_data)

BCL menghantar rekod pesanan dan membuang nilai kosong. Ruangan tanpa nilai (null, kosong, atau 0.00 untuk kebanyakan amaun) tidak dihantar, jadi jangan bergantung pada setiap ruangan sentiasa ada.

Ruangan	Jenis	Maksud
id	string	ID transaksi dalaman.
payer_name, payer_email, payer_telephone_number	string	Butiran pembeli.
order_number	string	Sama seperti record_id.
transaction_type	string	live atau test.
currency	string	Biasanya MYR.
subtotal_amount	string	Jumlah item sebelum caj. Sentiasa dihantar.
discount_amount	string	Diskaun kupon.
coupon_code, coupon_usage_id	string, number	Kupon yang digunakan.
fee_amount	string	Caj yang dikenakan kepada pembeli. Sentiasa dihantar.
additional_fee_amount	string	Caj tambahan yang ditetapkan pada payment form.
rounding_adjustment	string	Pembundaran yang dikenakan pada jumlah.
tax_amount	object	Butiran cukai, seperti nama cukai, kadar dan amaun.
shipping	object	name, cost dan total_weight kaedah penghantaran.
bank_transfer_details	object	Butiran bank, untuk pesanan manual transfer.
amount	string	Jumlah yang pembeli bayar.
payment_channel	string	Nama saluran, contohnya FPX, DuitNow QR, Credit Card, Cash on Delivery (COD) atau Manual Bank Transfer.
status	number	Kod status bayaran. 3 bermaksud berjaya dan 2 bermaksud gagal. Mungkin tiada pada form-submit.
status_description	string	Teks status dari Bayarcash. payment-success dan payment-failed sahaja.
is_paid	number	1 selepas dibayar, jika tidak 0.
retry_count	number	Berapa kali pembeli mencuba semula bayaran.
created_at	string	Masa pesanan, DD/MM/YYYY HH:MM:SS, waktu Malaysia.
customer_id	string	ID pelanggan BCL.
classification_code	string	Kod klasifikasi e-invois.
affiliate_id, cookie_id	string	Atribusi affiliate, jika ada.
source_type	string	Sama seperti formable_type.
items	array	Item yang dibeli. Lihat bahagian seterusnya.

Ruangan item

Setiap entri dalam items ada key berikut:

Ruangan	Jenis	Maksud
id	number	ID baris item.
index, productable_id	number	ID produk. index dikekalkan untuk integrasi lama.
productable_type	string	Contohnya product_item, event_ticket atau booking_service.
item, sku, option	string	Nama produk, SKU dan variasi yang dipilih.
quantity	number	Kuantiti.
unit_amount, normal_price, sale_price	string	Harga yang dibayar seunit, harga biasa dan harga jualan.
amount	string	Jumlah baris.
access_url	string atau null	Link download untuk produk digital.
weight, total_weight	string	Berat seunit dan untuk baris itu.
metadata	object atau null	Data tambahan item.
product_image	string	URL gambar produk, atau kosong.
protected_content	array	payment-success sahaja: setiap item ada title, url (link akses peribadi pembeli) dan access_finder_url (page tempat pembeli yang hilang link boleh mencarinya semula). Kosong pada event lain.

Ruangan affiliate

Objek affiliate_data ada referral_id, affiliate_id, affiliate_username, affiliate_name, affiliate_email dan affiliate_phone. Objek ini juga ada commission_type (flat, percentage atau per_item), commission_rate dan commission_amount. Untuk komisen per item, commission_rate ialah null dan commission_breakdown menyenaraikan setiap item. Akhir sekali, status (contohnya pending atau approved) dan referral_source.

Perubahan daripada contoh lama

Jika anda membina integrasi anda berdasarkan contoh lama, semak perubahan ini:

• form_id sudah tiada. Guna formable_id, dan formable_type untuk jenis form.
• Ruangan peringkat atas baru: formable_type, form_url, form_featured_image dan tracking_params.
• Ruangan pesanan baru: subtotal_amount, created_at, customer_id, is_paid, retry_count, source_type dan ruangan diskaun, kupon, cukai dan penghantaran.
• Ruangan item baru: id, productable_type, productable_id, sku, normal_price, sale_price, weight, total_weight, metadata, product_image dan protected_content.
• Ruangan affiliate baru: commission_breakdown.
• Event baru: payment-failed.

Semak sama ada webhook itu tulen

BCL tidak menandatangani webhook. Tiada signature header atau shared secret, jadi sesiapa yang tahu URL anda boleh menghantar request kepadanya. Untuk kekal selamat:

• Sebelum anda menghantar pesanan atau memberi akses, cari pesanan itu dengan record_id melalui API BCL dan sahkan statusnya di situ. Dalam Test Mode, guna GET /transaction/{order_number}: GET /transactions/{order_number} hanya menjumpai bayaran live. Hantar header User-Agent anda sendiri, kerana BCL menyekat header default daripada tool seperti curl dan python-requests.
• Guna URL yang sukar diteka, contohnya dengan token rawak yang panjang dalam path.
• Pastikan sistem anda selamat menerima event yang sama lebih daripada sekali. Guna record_id dan event bersama untuk mengesan ulangan.

Penghantaran & log

BCL menghantar setiap event sekali ke setiap URL, satu request bagi setiap URL. Sebarang respons 2xx dikira sebagai berjaya dihantar. Balas dengan cepat dan buat kerja berat selepas itu.

Setiap cubaan direkodkan di bawah Tools → Webhook Logs, dengan payload, respons anda dan sebarang ralat. BCL tidak menghantar semula secara automatik jika penghantaran gagal. Untuk menghantarnya semula:

1. Pergi ke Tools → Webhook Logs.

2. Klik menu di hujung baris, kemudian klik Resend dan sahkan.

   

Klik View Details dalam menu yang sama untuk melihat payload yang BCL hantar dan reply endpoint anda.

Isu-isu biasa

Kenapa sistem saya tidak menerima apa-apa walaupun saya sudah menambah URL webhook? Bagaimana saya mengujinya?

Buka tab Webhook Settings payment form itu dan klik Send Test. Pilih Event Type, semak Webhook URL dan hantar. Jika test itu sampai tetapi bayaran sebenar tidak, pastikan anda menandakan Payment Success, bukan hanya Form Submit. Jika test itu tidak sampai, pastikan URL anda terbuka kepada umum, bermula dengan https://, menerima POST dan membalas dengan status 2xx.

Bagaimana sistem saya sendiri boleh tahu apabila bayaran masuk?

On-kan webhook untuk payment form itu dan tandakan Payment Success. BCL menghantar pesanan, pembeli, item dan custom field ke URL anda sebaik sahaja bayaran disahkan. Padankan dengan rekod anda menggunakan record_id, iaitu nombor pesanan BCL.

Adakah import rekod lama akan mencetuskan webhook saya?

Hanya jika anda tandakan Run webhooks and automations pada page import. Setiap baris yang di-import kemudian mencetuskan webhook anda seolah-olah ia bayaran sebenar, jadi biarkan pilihan itu off jika anda hanya mahu rekod itu dalam BCL.

Artikel berkaitan

• Payload webhook Direct Debit
• Payload webhook affiliate
• Cipta payment form pertama anda
• Semak butiran transaksi