iPay88 dari CFML: integrasi hosted payment

iPay88 dari CFML: integrasi hosted payment

iPay88 ialah gerbang pembayaran Malaysia yang membawa pelanggan ke halaman pembayaran milik iPay88 sendiri, bukan memproses kad di pelayan anda. Anda hantar satu borang POST, pelanggan membayar di laman iPay88, kemudian iPay88 memulangkan dua jenis maklum balas ke laman anda: satu redirect untuk pelayar dan satu panggilan server-to-server. Semua ini boleh dibina dengan CFML tanpa SDK khas, dan kunci keselamatannya ialah satu tandatangan SHA256 daripada gabungan medan mengikut susunan tetap. Artikel ini menunjukkan cara membina tandatangan itu dan mengesahkan maklum balas yang masuk, dengan bukti pengiraan yang dijalankan dalam Lucee.

Aliran hosted payment iPay88

Aliran hosted payment bermakna anda tidak menyentuh data kad langsung. Langkahnya empat. Pertama, pelanggan menekan butang bayar di laman anda. Kedua, anda menghantar borang POST ke hujung iPay88 yang mengandungi medan transaksi dan tandatangan. Ketiga, pelanggan dibawa ke halaman pembayaran iPay88 dan membayar di sana menggunakan FPX, kad, atau e-dompet. Keempat, iPay88 memulangkan hasil pembayaran melalui dua laluan: Response URL untuk redirect pelayar pelanggan, dan Backend URL untuk panggilan server-to-server yang tidak kelihatan kepada pelanggan. Didokumenkan dalam panduan integrasi iPay88 dan PDF teknikal API 2.0 yang disenaraikan di bahagian Sumber.

Kedua-dua laluan membawa medan yang serupa tetapi tiba pada masa berbeza: redirect sampai dahulu dan mudah dimuat semula, manakala backend response ialah sumber status yang boleh dipercayai jika tandatangannya sah.

Akaun peniaga: apa yang anda perlukan dahulu

Integrasi ini memerlukan akaun peniaga iPay88. Anda mendapat dua nilai semasa pendaftaran: MerchantCode yang mengenal pasti akaun anda, dan MerchantKey yang menjadi rahsia bersama antara anda dan iPay88. MerchantKey tidak boleh disimpan dalam kod sumber, dan panduan penuh serta butiran sandbox diberikan melalui portal peniaga selepas log masuk. Tanpa akaun ini anda tidak boleh membuat transaksi sebenar atau ujian hujung ke hujung, dan artikel ini tidak mendakwa ujian sedemikian dilakukan.

Perkara yang boleh anda sahkan tanpa akaun ialah pengiraan tandatangan itu sendiri, kerana ia hanya SHA256 ke atas rentetan teks, dan artikel ini membuktikannya dengan kunci ujian rekaan.

Medan yang dihantar ke iPay88

Borang POST ke iPay88 membawa medan berikut. Amaun mesti dalam format dua tempat perpuluhan, dan RefNo mesti unik bagi setiap transaksi anda.

Selain sebelas medan ini, borang klasik juga menghantar PaymentId (kaedah pembayaran), Lang, ResponseURL dan BackendURL, yang tidak menyertai pengiraan tandatangan permintaan.

Membina tandatangan SHA256 mengikut susunan MARPCCS

Tandatangan permintaan ialah SHA256 daripada gabungan lima medan yang dicantum tanpa pemisah, mengikut susunan tetap: MerchantKey dahulu, diikuti MerchantCode, RefNo, Amount dan Currency. Susunan ini menentukan keputusan kerana SHA256 ialah fungsi satu rentetan tepat: menukar susunan, menambah pemisah, atau menggugurkan satu medan menghasilkan hash yang berbeza sepenuhnya. iPay88 mengira semula rentetan yang sama dengan cara yang sama di pihak mereka, jadi apa-apa sisihan bermakna tandatangan tidak sepadan dan permintaan ditolak. Bahagian ini didokumenkan dalam PDF teknikal iPay88 dan diuji pengiraannya dalam Lucee.

merchantKey = "KUNCI-UJIAN-123";
merchantCode = "M12345";
refNo = "ORDER-1001";
amount = "150.00";
currency = "MYR";

// Susunan mesti tepat: MerchantKey, MerchantCode, RefNo, Amount, Currency
sumberTandatangan = merchantKey & merchantCode & refNo & amount & currency;
signature = lcase(hash(sumberTandatangan, "SHA-256"));

Fungsi hash Lucee memulangkan huruf besar manakala contoh iPay88 menggunakan huruf kecil. Nilainya sama, jadi bandingkan tanpa mengira huruf besar kecil dengan lcase atau compareNoCase; jangan bandingkan terus tanpa menormalkan huruf.

Borang POST ke hujung iPay88

Setelah tandatangan sedia, bina borang dan hantar ke hujung iPay88. Hujung produksi ialah https://payment.ipay88.com.my/ePayment/entry.asp. Ini didokumenkan dalam pustaka awam dan dokumentasi WooCommerce yang disenaraikan di bahagian Sumber, tetapi sahkan hujung sebenar dalam panduan yang diberikan bersama akaun peniaga anda kerana ia boleh berubah.

<cfoutput>
<form action="https://payment.ipay88.com.my/ePayment/entry.asp" method="post" name="bayar">
    <input type="hidden" name="MerchantCode" value="#merchantCode#">
    <input type="hidden" name="RefNo" value="#refNo#">
    <input type="hidden" name="Amount" value="#amount#">
    <input type="hidden" name="Currency" value="#currency#">
    <input type="hidden" name="ProdDesc" value="#prodDesc#">
    <input type="hidden" name="UserName" value="#userName#">
    <input type="hidden" name="UserEmail" value="#userEmail#">
    <input type="hidden" name="UserContact" value="#userContact#">
    <input type="hidden" name="Remark" value="#remark#">
    <input type="hidden" name="SignatureType" value="SHA256">
    <input type="hidden" name="Signature" value="#signature#">
    <input type="hidden" name="ResponseURL" value="https://anda.my/ipay88-response">
    <input type="hidden" name="BackendURL" value="https://anda.my/ipay88-backend">
</form>
</cfoutput>

Dalam halaman sebenar anda, medan ini dibina daripada rekod pesanan dan kunci yang dibaca daripada pemboleh ubah persekitaran, bukan dikod terus. Borang ini boleh dihantar automatik dengan JavaScript selepas halaman dimuat. Perhatikan bahawa nilai seperti MerchantCode dan RefNo disuntik melalui cfoutput, jadi pastikan ia telah di-escape jika ia datang daripada input pengguna, seperti yang dibincangkan dalam panduan keselamatan web XSS dan CSRF.

Dua laluan pulang: response dan backend response

Selepas pembayaran, iPay88 menghantar maklum balas melalui dua laluan. Response URL ialah redirect pelayar yang membawa pelanggan kembali ke laman anda untuk memaparkan hasil. Backend URL ialah panggilan POST server-to-server daripada iPay88 yang membawa status muktamad transaksi bersama tandatangan, dan inilah sumber yang anda percayai untuk menutup pesanan.

Tandatangan backend response dikira daripada gabungan tujuh medan mengikut susunan: MerchantKey, MerchantCode, PaymentId, RefNo, Amount, Currency dan Status. Perhatikan bahawa PaymentId dan Status menyertai pengiraan ini walaupun tidak menyertai pengiraan permintaan, jadi jangan guna semula kod tandatangan permintaan untuk mengesahkan respons. Ini didokumenkan dalam PDF teknikal iPay88.

Mengesahkan respons: jangan percaya tanpa tandatangan

Peraturan emasnya mudah: jangan percaya apa-apa medan dalam respons sehingga anda mengira semula tandatangan dan ia sepadan. Tanpa semakan ini, sesiapa sahaja boleh POST medan palsu ke Backend URL anda dan menandakan pesanan sebagai dibayar. Kira semula dengan medan yang diterima dan bandingkan dengan Signature yang dihantar.

merchantKey = "KUNCI-UJIAN-123";
merchantCode = form.MerchantCode;
paymentId = form.PaymentId;
refNo = form.RefNo;
amount = form.Amount;
currency = form.Currency;
status = form.Status;

sumberTandatangan = merchantKey & merchantCode & paymentId & refNo & amount & currency & status;
dijangka = lcase(hash(sumberTandatangan, "SHA-256"));

if (compareNoCase(dijangka, form.Signature) != 0) {
    cfheader(statuscode = 403);
    writeOutput("tandatangan tidak sah");
    abort;
}

Bahagian ini diuji pengiraannya dalam Lucee dengan kunci ujian rekaan, dan hasil sebenar daripada rig adalah seperti berikut.

SUMBER-MINTA=KUNCI-UJIAN-123M12345ORDER-1001150.00MYR
SHA256-MINTA=f4758bc82ae39d5c80a001224a9394d17f9ea3923a371005d741d8262369f943
SHA256-MINTA-ULANG=f4758bc82ae39d5c80a001224a9394d17f9ea3923a371005d741d8262369f943

SUMBER-BALAS=KUNCI-UJIAN-123M123452ORDER-1001150.00MYR1
SHA256-BALAS=eb316426676c7a5076ceda5b6e880ccf53fbf359e6743427f793c41f6cd34d74
SHA256-BALAS-ULANG=eb316426676c7a5076ceda5b6e880ccf53fbf359e6743427f793c41f6cd34d74

SEMAK-BETUL=SAH
SEMAK-SALAH=TIDAK-SAH

Dua baris terakhir menunjukkan semakan yang lengkap: tandatangan yang betul diterima sebagai SAH, manakala tandatangan yang ditukar satu aksara ditolak sebagai TIDAK-SAH. Pengiraan berulang memulangkan nilai yang sama, yang membuktikan hash itu deterministik. Nilai ini dijana dengan kunci ujian rekaan KUNCI-UJIAN-123 dan tidak berkaitan dengan mana-mana akaun sebenar.

Idempotensi dalam backend response

iPay88 menghantar semula backend response beberapa kali jika ia tidak menerima pengakuan daripada anda. Dalam aliran klasik, pengakuannya ialah perkataan RECEIVEOK, dan iPay88 mencuba sehingga tiga kali, jadi endpoint anda mesti idempoten: memproses transaksi yang sama dua kali tidak boleh menghasilkan kesan berganda.

Cara paling mudah ialah dedupe mengikut TransId, iaitu ID transaksi iPay88 yang unik. Simpan TransId bersama status pesanan, dan jika TransId sudah wujud dalam pangkalan data, langkau pemprosesan dan balas RECEIVEOK serta-merta. Gabungkan semakan ini dengan semakan tandatangan di atas, dan balas pengakuan secepat mungkin supaya iPay88 berhenti menghantar semula. Corak ini sama dengan mana-mana webhook pembayaran, seperti yang diterangkan dalam panduan webhook tempatan dalam CFML.

Apa yang diuji dan apa yang belum

Untuk bersikap jujur tentang bukti: pengiraan tandatangan SHA256 diuji dan disahkan dalam Lucee 7.1 pada rig tempatan. Yang belum diuji ialah aliran transaksi penuh, kerana itu memerlukan akaun peniaga iPay88 yang sebenar, dan pendaftaran sedemikian tidak dilakukan untuk artikel ini. Medan, susunan tandatangan dan aliran dua laluan didokumenkan daripada sumber yang disenaraikan, bukan disahkan dengan transaksi sebenar. Jangan anggap kod di atas berfungsi dalam persekitaran langsung sehingga anda mengujinya dalam sandbox akaun anda sendiri.

Berbanding gerbang lain, iPay88 berada di tengah dari segi kerumitan: lebih rumit daripada ToyyibPay yang hanya menghantar kunci sebagai medan borang, tetapi lebih ringkas daripada Billplz yang memerlukan pengisihan kunci dan HMAC. Jika anda mahu memanggil API secara terus dan bukannya borang redirect, lihat panduan REST API dalam Lucee.

Soalan Lazim

Adakah saya boleh menguji iPay88 tanpa akaun peniaga?

Tidak untuk transaksi sebenar. Pengiraan tandatangan boleh diuji secara bebas kerana ia hanya SHA256, tetapi untuk menghantar transaksi atau menerima backend response sebenar anda memerlukan MerchantCode dan MerchantKey daripada akaun peniaga, bersama akses sandbox yang diberikan melalui portal peniaga.

Kenapa susunan medan dalam tandatangan penting?

SHA256 ialah fungsi satu rentetan tepat. Menukar susunan medan, menambah pemisah, atau menggugurkan satu medan menghasilkan hash yang berbeza sepenuhnya, dan iPay88 mengira rentetan yang sama dengan cara yang sama. Susunan yang berbeza bermakna tandatangan tidak sepadan dan permintaan ditolak.

Bagaimana saya tahu backend response itu benar daripada iPay88?

Kira semula tandatangan daripada medan yang diterima mengikut susunan MerchantKey, MerchantCode, PaymentId, RefNo, Amount, Currency dan Status, kemudian bandingkan dengan Signature yang dihantar. Jika tidak sepadan, tolak permintaan itu tanpa memprosesnya.

Apa yang perlu saya balas kepada backend response iPay88?

Balas pengakuan dengan segera supaya iPay88 berhenti menghantar semula. Dalam aliran klasik pengakuan itu ialah perkataan RECEIVEOK, dan iPay88 mencuba sehingga tiga kali jika tidak menerimanya. Sahkan perkataan sebenar dalam panduan akaun anda kerana ia boleh berbeza antara versi.

Adakah amaun mesti ada dua tempat perpuluhan?

Ya, dalam aliran klasik amaun dihantar dengan dua tempat perpuluhan, contohnya 150.00 untuk RM150. Format ini penting kerana amaun menyertai pengiraan tandatangan, jadi 150.00 dan 150 menghasilkan hash yang berbeza. Pastikan nilai yang sama digunakan untuk tandatangan dan borang.

Sumber

• iPay88 API 2.0 Technical Documentation (PDF)
• iPay88 Payment Gateway Documentation, WooCommerce
• karyamedia/ipay88 (pustaka PHP awam)