Midtrans Payment Gateway

Panduan ini ditujukan untuk pemilik toko dan admin PrestaShop yang ingin menerima pembayaran melalui Midtrans.

Apa fungsi modul ini?

Modul ini menambahkan pilihan pembayaran “Pay with Midtrans” di halaman checkout. Saat dipilih pembeli, mereka bisa membayar dengan berbagai metode yang disediakan Midtrans, misalnya:

• Transfer bank / Virtual Account (BCA, BNI, BRI, Mandiri, Permata, dll.)
• E-wallet (GoPay, ShopeePay, dll.)
• QRIS
• Kartu kredit/debit
• Dan metode lain yang diaktifkan di akun Midtrans

Requirement

Pastikan hal-hal dibawah sudah terpenuhi sebelum proses instalasi.

Penting: Sandbox dan Production punya pasangan key yang berbeda. Pastikan key yang Anda masukkan sesuai dengan mode yang dipilih.

Instalasi

Dari Back Office

1. Masuk ke back office PrestaShop.
2. Buka Modules → Module Manager, lalu klik Upload a module dan pilih file pidn_midtrans.zip.
3. Cari Midtrans Payment di daftar modul, lalu klik Install.
4. Setelah terpasang, klik Configure untuk mengisi pengaturan.

Dari command line

unzip midtrans.zip -d modules/
php bin/console prestashop:module install pidn_midtrans
php bin/console cache:clear

Konfigurasi

Buka Modules → Module Manager → Midtrans Payment → Configure.

Pengaturan

Klik Save setelah selesai.

Redirect atau Popup?

• Redirect — pembeli dibawa ke halaman pembayaran Midtrans, lalu otomatis kembali ke toko Anda setelah membayar. Paling sederhana dan paling kompatibel.
• Popup — pembeli tetap di halaman toko Anda; jendela pembayaran Midtrans muncul di atas halaman checkout. Terasa lebih menyatu dengan toko, tapi membutuhkan Client Key.

Metode pembayaran yang muncul sama saja di kedua pilihan. Silakan pilih mana yang Anda sukai.

Mendaftarkan Payment Notification URL (disarankan)

1. Salin alamat Payment Notification URL dari halaman pengaturan modul.
2. Buka Midtrans Dashboard → Settings → Configuration.
3. Tempel alamat tersebut di kolom Payment Notification URL, lalu simpan.

Dengan ini, Midtrans langsung memberi tahu toko Anda begitu pembayaran masuk, sehingga pesanan tercatat lebih cepat — terutama untuk pembayaran yang tidak langsung selesai, seperti transfer Virtual Account.

Jika langkah ini dilewati, modul tetap berfungsi: pembayaran dicek ulang ke Midtrans ketika pembeli kembali ke toko dari halaman pembayaran.

Mata uang

Midtrans hanya memproses pembayaran dalam Rupiah (IDR). Pastikan toko Anda memakai mata uang IDR, dan di halaman pengaturan pembayaran PrestaShop (Payment → Preferences) Midtrans sudah dicentang untuk IDR.

Metode pembayaran yang tampil

Metode pembayaran apa saja yang muncul (VA, e-wallet, QRIS, kartu, dll.) diatur dari Midtrans Dashboard, bukan dari modul ini. Untuk menambah atau menyembunyikan metode, ubah pengaturannya di dashboard Midtrans.

Cara kerja

1. Di halaman checkout, pembeli memilih Pay with Midtrans lalu melanjutkan.
2. Halaman (atau popup) pembayaran Midtrans terbuka. Pembeli memilih metode dan menyelesaikan pembayaran.
3. Setelah itu, pembeli kembali ke toko Anda:
   • Jika pembayaran sudah berhasil → pembeli melihat halaman konfirmasi pesanan.
   • Jika pembayaran masih menunggu (misalnya belum transfer ke Virtual Account) → pembeli diarahkan ke halaman riwayat pesanan. Pesanan akan muncul otomatis begitu pembayaran diterima.
   • Jika pembayaran gagal atau dibatalkan → pembeli juga diarahkan ke halaman riwayat pesanan, dan tidak ada pesanan yang dibuat. Isi keranjangnya tetap tersimpan, jadi pembeli bisa checkout ulang.

Kapan pesanan muncul di back office?

Pesanan baru dibuat setelah pembayaran benar-benar diterima oleh Midtrans. Jadi:

• Anda tidak akan melihat pesanan “menunggu pembayaran” dari Midtrans di daftar Orders.
• Setiap pesanan Midtrans yang muncul sudah berstatus Payment accepted (pembayaran diterima) dan siap diproses.
• Nomor transaksi Midtrans tercatat di detail pembayaran pesanan, sehingga mudah dicocokkan dengan data di Midtrans Dashboard.

Sebelum pesanan dibuat, modul selalu mengecek langsung ke Midtrans bahwa pembayaran benar-benar sukses dan nominalnya sesuai dengan total belanja. Jika nominalnya tidak cocok, pesanan tidak dibuat dan kejadiannya dicatat di log toko.

Uji coba sebelum go-live

1. Setel Mode ke Sandbox dan masukkan Server Key (dan Client Key, bila perlu) versi Sandbox.
2. Lakukan pembelian percobaan di toko Anda dan pilih Pay with Midtrans.
3. Selesaikan pembayaran memakai simulator pembayaran Sandbox dari Midtrans (lihat dokumentasi Midtrans untuk nomor kartu uji dan simulator VA/QRIS).
4. Pastikan pesanan muncul di Orders dengan status pembayaran diterima.

Jika semuanya berjalan lancar:

5. Ganti Mode ke Production.
6. Ganti Server Key dan Client Key dengan key Production.
7. Pastikan Payment Notification URL juga sudah didaftarkan di dashboard Production Midtrans (pengaturan Sandbox dan Production terpisah).

Uninstall

Dari Back Office

Buka Modules → Module Manager → Midtrans Payment → Uninstall. Proses ini akan menghapus seluruh konfigurasi modul.

Dari command line

php bin/console prestashop:module uninstall pidn_midtrans
php bin/console cache:clear

Pertanyaan umum & kendala

Pilihan “Pay with Midtrans” tidak muncul di checkout. Periksa hal-hal berikut:

• Modul sudah aktif (enabled).
• Server Key sudah diisi dan disimpan.
• Pembeli berbelanja dalam Rupiah (IDR), dan IDR sudah dicentang untuk Midtrans (lihat bagian Mata uang).
• Total keranjang lebih dari nol.
• Jika semua sudah benar tapi tetap tidak muncul, klik tombol Repair currency restrictions di halaman pengaturan modul (sekali saja).

Pembeli melihat pesan “Unable to start a Midtrans payment right now”. Biasanya karena Server Key salah, atau key Sandbox dipakai di mode Production (atau sebaliknya). Periksa kembali key dan mode Anda. Detail kesalahan tercatat di Advanced Parameters → Logs.

Pembeli sudah membayar, tapi pesanan belum muncul.

• Untuk pembayaran VA/transfer, pesanan muncul setelah Midtrans mengonfirmasi dana masuk. Pastikan Payment Notification URL sudah didaftarkan agar konfirmasi diterima secepatnya.
• Cek status transaksi di Midtrans Dashboard. Jika di sana sudah sukses, cek Advanced Parameters → Logs di PrestaShop untuk melihat apakah ada catatan kesalahan (misalnya nominal tidak cocok).

Popup tidak terbuka. Pastikan Display mode = Popup sudah disertai Client Key yang benar dan sesuai mode (Sandbox/Production). Sebagai alternatif, ganti Display mode ke Redirect.

Pembeli me-refresh halaman atau kembali lalu membayar lagi — apakah tertagih dua kali? Tidak. Selama transaksi sebelumnya untuk keranjang yang sama masih menunggu pembayaran (berlaku sekitar 24 jam), modul memakai ulang transaksi tersebut dan tidak membuat tagihan baru. Pesanan juga hanya dibuat satu kali per keranjang.

Bagaimana dengan refund? Refund dilakukan dari Midtrans Dashboard. Modul ini tidak memproses refund dari back office PrestaShop, jadi sesuaikan status pesanan di PrestaShop secara manual setelah melakukan refund.

DISCLAIMER (Ketergantungan pada layanan pihak ketiga)

Modul ini bergantung pada layanan pihak ketiga, Midtrans. Pemrosesan pembayaran, biaya transaksi, pencairan dana, dan ketersediaan layanan sepenuhnya dikendalikan oleh Midtrans. Jika layanan Midtrans sedang gangguan atau mengubah sistemnya, pembayaran lewat modul ini dapat terganggu sampai layanan pulih atau modul diperbarui. Untuk pertanyaan seputar akun, biaya, atau pencairan dana, hubungi Midtrans secara langsung.

Untuk bantuan terkait modul ini atau kebutuhan kustomisasi, hubungi kami.

Changelog