Sambung Billplz ke Lucee: bil, webhook dan pembayaran FPX

Sambung Billplz ke Lucee: bil, webhook dan pembayaran FPX

Billplz ialah gerbang pembayaran Malaysia yang memodelkan pembayaran sebagai dua objek, iaitu Collection dan Bill. Anda sahkan panggilan API dengan HTTP Basic Auth, cipta bil melalui POST ke /api/v4/bills, dan sahkan webhook menggunakan X Signature yang dikira dengan HMAC-SHA256. Artikel ini membimbing anda daripada mencipta bil hingga memproses webhook dengan selamat dalam CFML.

Model Collection dan Bill dalam Billplz

Billplz menggunakan dua objek utama. Collection ialah kumpulan bil, dan Bill ialah permintaan bayaran kepada seorang pelanggan. Setiap Bill milik tepat satu Collection, dan had seumur hidup akaun ialah 20,000 Collection. Mata wang hanyalah MYR tanpa penukaran, dan semua nilai wang dinyatakan dalam sen sebagai integer. Memahami model ini penting kerana anda mesti mencipta Collection dahulu sebelum boleh mencipta Bill.

Dapatkan Secret Key dan sediakan Collection

Billplz menggunakan dua kunci berbeza dengan tujuan berbeza. API Secret Key diperoleh dari halaman Settings akaun dan digunakan untuk panggilan API. X Signature Key diperoleh dari Settings > Keys & Integration dan digunakan untuk mengesahkan callback dan redirect. Jangan campurkan kedua-duanya.

Pengesahan API ialah HTTP Basic Auth dengan Secret Key sebagai username dan tanpa password, dan wajib melalui HTTPS. Simpan kedua-dua kunci ini sebagai rahsia dan bukan dalam kod sumber; rujuk panduan menyimpan rahsia dalam CFML.

Cipta Collection sekali sahaja dengan POST ke https://www.billplz.com/api/v4/collections. Medan wajib hanyalah title:

local.auth = "Basic " & toBase64(variables.apiSecretKey & ":");
local.resp = "";
http url="https://www.billplz.com/api/v4/collections" method="post" result="local.resp" charset="utf-8" {
    httpparam type="header" name="Authorization" value=local.auth;
    httpparam type="formfield" name="title" value="Kedai Contoh";
}

local.koleksi = deserializeJSON(local.resp.fileContent);
local.collectionId = local.koleksi.id;

Balasan JSON mengandungi medan id yang diperlukan untuk mencipta bil. Simpan collectionId ini dan gunakannya semula untuk semua bil dalam kumpulan tersebut.

Cipta bil dengan cfhttp dan Basic Auth (contoh penuh)

Bil dicipta dengan POST ke https://www.billplz.com/api/v4/bills. Medan wajib ialah collection_id, email (wajib jika tiada mobile), mobile (wajib jika tiada email), name (maks 255 aksara), amount dalam sen, callback_url yang wajib, dan description (maks 200 aksara). Contoh penuh, dengan pengepala Authorization yang dihantar kepada cfhttp:

local.auth = "Basic " & toBase64(variables.apiSecretKey & ":");
local.resp = "";
http url="https://www.billplz.com/api/v4/bills" method="post" result="local.resp" charset="utf-8" {
    httpparam type="header" name="Authorization" value=local.auth;
    httpparam type="formfield" name="collection_id" value=variables.collectionId;
    httpparam type="formfield" name="email" value="ali@example.com";
    httpparam type="formfield" name="name" value="Ali Bin Abu";
    httpparam type="formfield" name="amount" value="200";
    httpparam type="formfield" name="callback_url" value="https://anda.my/webhook-billplz";
    httpparam type="formfield" name="description" value="Bayaran untuk pesanan 1001";
}

local.bil = deserializeJSON(local.resp.fileContent);
local.billId = local.bil.id;
local.billUrl = local.bil.url;

Nombor mobile mesti dalam format seperti +60123456789 atau 60123456789 tanpa ruang atau sempang. Balasan mengandungi id bil dan url pembayaran. Medan pilihan lain termasuk due_at (format YYYY-MM-DD, hanya rujukan dan tidak menyekat pembayaran), redirect_url, deliver untuk e-mel atau SMS, serta reference_1_label dan reference_1. Integrasi dengan callback_url adalah wajib, jadi anda mesti menyediakan endpoint callback sebelum mencipta bil. Cara cfhttp menghantar pengepala dan medan borang dibincangkan lebih lanjut dalam panduan cfhttp API luar.

Redirect pelanggan dan terus-ke-FPX

Selepas mencipta bil, alihkan pelanggan ke url yang dipulangkan oleh Billplz:

location(local.billUrl, false);

Pelanggan akan memilih kaedah pembayaran pada halaman Billplz, contohnya FPX, kad atau e-dompet. Untuk membawa pelanggan terus ke FPX tanpa halaman pilihan, hantar reference_1_label bernilai "Bank Code" dan reference_1 bernilai kod bank, kemudian tambahkan ?auto_submit=true pada URL bil. Senarai kod bank FPX diperoleh melalui GET ke /api/v3/fpx_banks.

Webhook X Signature: sahkan HMAC-SHA256 dalam CFML

Selepas pembayaran, Billplz menghantar callback server-side sebagai POST dengan Content-Type application/x-www-form-urlencoded ke callback_url. Medan yang dihantar termasuk id, collection_id, paid, state, amount, paid_amount, due_at, email, mobile, name, url dan paid_at.

Terdapat dua varian callback. Basic Callback URL tidak mempunyai pengesahan dan dilumpuhkan secara lalai untuk akaun yang didaftarkan sejak September 2018. X Signature Callback URL disyorkan dan menjadi lalai untuk akaun tersebut. Sentiasa gunakan varian X Signature.

X Signature dikira dengan HMAC-SHA256. Langkahnya ialah ambil semua pasangan key-value kecuali x_signature, gabungkan setiap key dengan value tanpa pemisah, susun menaik secara case-insensitive, cantumkan dengan aksara pipe, kemudian kira HMAC-SHA256 menggunakan X Signature Key:

local.parts = [];
local.keys = structKeyArray(form);
loop array=local.keys item=local.k {
    if (local.k != "x_signature") {
        arrayAppend(local.parts, local.k & form[local.k]);
    }
}
arraySort(local.parts, "textnocase");
local.source = arrayToList(local.parts, "|");
local.expected = hmac(local.source, variables.xSignatureKey, "HmacSHA256");

if (compareNoCase(local.expected, form.x_signature) != 0) {
    cfheader(statuscode = 403);
    writeOutput("signature tidak sah");
    abort;
}

Penting untuk membezakan dua algoritma tandatangan Billplz. Pengesahan x_signature pada callback dan redirect menggunakan HMAC-SHA256, seperti di atas. HMAC-SHA512 pula digunakan hanya untuk checksum signature pada Payment Order V5, bukan untuk callback bil biasa. Jangan campurkan kedua-duanya kerana ia mengesahkan perkara yang berbeza.

Selepas tandatangan sah, balas HTTP 200 secepat mungkin supaya Billplz berhenti menghantar semula. Proses kerja berat secara tak segerak selepas mengakui penerimaan, dan dedupe mengikut id bil dan paid supaya callback yang berulang tidak memproses pesanan dua kali. Rujuk panduan webhook tempatan dan panduan keselamatan aplikasi web.

Jadual retry Billplz dan cara menghentikannya

Billplz menghantar semula callback sehingga lima kali jika endpoint anda tidak membalas HTTP 200 dalam masa 20 saat. Jadualnya ialah cubaan kedua selepas 15 saat ditambah rawak 0 hingga 300 saat, cubaan ketiga selepas 15 minit, cubaan keempat selepas 15 minit, dan cubaan kelima selepas 24 jam. Selepas lima cubaan, callback dibuang daripada giliran, dan kedudukan akaun merosot satu tahap bagi setiap cubaan gagal. Oleh itu endpoint callback mesti balas 200 segera dan bersifat idempoten.

Semak status dan padam bil (Delete Bill)

Jangan bergantung pada callback semata-mata. Semak status melalui API dengan GET ke https://www.billplz.com/api/v3/bills/ diikuti id bil:

local.auth = "Basic " & toBase64(variables.apiSecretKey & ":");
local.resp = "";
http url="https://www.billplz.com/api/v3/bills/" & variables.billId method="get" result="local.resp" charset="utf-8" {
    httpparam type="header" name="Authorization" value=local.auth;
}

local.bil = deserializeJSON(local.resp.fileContent);
local.sudahBayar = local.bil.paid;
local.keadaan = local.bil.state;

Medan paid ialah boolean dan state bernilai due, paid atau deleted. Billplz tidak menggalakkan polling kerana kadar permintaan dihadkan, jadi gunakan callback sebagai sumber utama dan API ini sebagai pengesahan silang. Untuk memadam bil yang belum dibayar, hantar DELETE ke endpoint yang sama. Hanya bil berstatus due boleh dipadam; bil paid mengembalikan HTTP 422. Perhatikan bahawa bil yang dipadam boleh muncul semula jika pelanggan tetap menyelesaikan pembayaran, jadi jangan anggap pemadaman sebagai jaminan.

Sandbox billplz-sandbox.com dan kod simulator

Persekitaran sandbox berada di https://www.billplz-sandbox.com/api/ dengan akaun dan kelayakan yang berasingan daripada production. Data kekal dalam sandbox. Untuk ujian Payment Order, gunakan bank_code bernilai DUMMYBANKVERIFIED. Simulator FPX untuk staging pula menggunakan kod BP-FKR01, iaitu Billplz Simulator.

Rate limit dan kod ralat

Panggilan GET dihadkan kepada 100 atau 10 permintaan dalam tempoh lima minit bergantung pada endpoint. Pengepala RateLimit-Limit, RateLimit-Remaining dan RateLimit-Reset melaporkan keadaan had, dan melebihi had mengembalikan HTTP 429. Kod ralat lazim lain ialah 401 untuk pengesahan gagal, 404 untuk sumber tidak wujud, dan 422 untuk permintaan yang tidak dapat diproses seperti memadam bil yang sudah dibayar.

Soalan Lazim (FAQ)

Mengapa callback sampai berulang kali?

Billplz menghantar semula callback sehingga lima kali jika endpoint anda tidak membalas HTTP 200 dalam 20 saat. Balas 200 segera dan dedupe mengikut id bil dan paid supaya pesanan tidak diproses dua kali.

Bagaimana saya sahkan callback itu benar-benar daripada Billplz?

Gunakan X Signature Callback URL dan kira semula HMAC-SHA256 daripada medan yang diterima, kemudian bandingkan dengan x_signature. Jangan guna Basic Callback URL kerana ia tidak mempunyai pengesahan.

Bolehkah saya terus bawa pelanggan ke FPX?

Ya. Hantar reference_1_label bernilai "Bank Code" dan reference_1 bernilai kod bank semasa mencipta bil, kemudian tambahkan ?auto_submit=true pada URL bil.

Apa yang berlaku apabila bil tamat tempoh?

Bil tamat tempoh 30 hari selepas dicipta secara lalai, dan due_at hanyalah maklumat rujukan yang tidak menyekat pembayaran. Padam bil berstatus due yang tidak diperlukan lagi melalui DELETE ke /api/v3/bills/ diikuti id bil.

Apakah perbezaan HMAC-SHA256 dan HMAC-SHA512 di Billplz?

HMAC-SHA256 digunakan untuk x_signature pada callback dan redirect bil. HMAC-SHA512 digunakan hanya untuk checksum signature pada Payment Order V5. Kedua-duanya mengesahkan perkara berbeza dan tidak boleh ditukar ganti.

Sumber

• Billplz API Documentation
• Billplz Support API