Pembayaran (Teknis)

Ringkasan

Pembayaran Maubisa dipusatkan di Pusat Akun dan diproses menggunakan Midtrans Core API (Application Programming Interface, kontrak teknis yang memungkinkan dua sistem berkomunikasi secara terprogram). Halaman ini ditujukan untuk developer dan partner yang perlu memahami kontrak teknis, batas tanggung jawab, dan mekanisme aktivasi akses secara mendalam, termasuk kasus tepi yang sering menimbulkan kebingungan saat menelusuri masalah transaksi.

Pusat Akun menjadi sumber kebenaran untuk harga, invoice, status pembayaran, dan provisioning akses (proses otomatis mengaktifkan hak akses pengguna setelah suatu syarat, misalnya pembayaran, terpenuhi). Produk lain hanya mengirim konteks pembelian, bukan nominal final.

Midtrans Core API, bukan Snap

Maubisa menggunakan Midtrans Core API untuk alur utama checkout, bukan Snap (produk popup pembayaran siap pakai dari Midtrans). Pengecualian ada pada DANA dan Danamon: Midtrans tidak menyediakan keduanya lewat Core API, jadi Pusat Akun membuat transaksi Snap khusus untuk metode itu dan mengalihkan pembeli ke halaman pembayaran Midtrans. Dengan Core API, Maubisa dapat membuat antarmuka pembayaran yang konsisten dengan pengalaman Pusat Akun, menyimpan instruksi bayar yang dibutuhkan, dan mengendalikan aktivasi akses dari server.

Implikasinya:

• UI checkout dan halaman bayar dikelola oleh Pusat Akun, bukan iframe atau popup bawaan Midtrans.
• Produk tidak langsung mengakses Midtrans dari frontend publik. Server key Midtrans tidak pernah dikirim ke browser.
• Server Pusat Akun membuat charge dan menyimpan respons yang relevan, misalnya nomor virtual account atau URL QR code.
• Webhook Midtrans tetap menjadi jalur utama untuk memperbarui invoice dan akses, bukan respons langsung dari API charge.

Aturan emas harga server-side

Produk Maubisa dapat mengirim parameter seperti product, event, judul, atau redirect ke bayar.maubisa.id/beli (checkout tamu) atau akun.maubisa.id/checkout (pengguna login) untuk membantu Pusat Akun memahami konteks pembelian. Parameter tersebut bukan sumber harga final. Server Pusat Akun mengambil data produk, acara, atau katalog yang otoritatif, lalu membuat invoice berdasarkan hasil perhitungan server. Detail parameter ada di Integrasi Produk Baru.

Pendekatan ini mencegah:

• manipulasi harga dari browser, misalnya mengubah nilai di query string atau devtools sebelum request charge dikirim;
• perbedaan harga antara produk dan invoice, misalnya jika halaman produk menampilkan harga promo yang sudah kedaluwarsa;
• invoice dengan nominal yang tidak sesuai;
• aktivasi akses dari pembayaran yang tidak cocok, misalnya membayar Rp50.000 tetapi mengklaim entitlement seharga Rp500.000;
• kesalahan saat harga acara berubah di sumber data, misalnya panitia menaikkan harga tiket setelah early bird berakhir tetapi ada pengguna yang masih membuka tab lama.

Full charge flow untuk pengguna login

Polling pada halaman /bayar/[orderId] hanya memperbarui tampilan pengguna. Polling bukan mekanisme aktivasi resmi. Aktivasi resmi dilakukan melalui notifikasi server-to-server dari Midtrans yang tervalidasi.

Contoh konseptual request charge

Contoh berikut adalah ilustrasi kontrak konseptual, bukan skema API final yang wajib direplikasi produk lain:

{
  "orderId": "MB-webinar-kari-mslvvi0o-555d85307b",
  "amount": 150000,
  "currency": "IDR",
  "paymentMethod": "qris",
  "items": [
    { "sku": "webinar-karier", "name": "Webinar Karier", "qty": 1, "price": 150000 }
  ],
  "customer": { "email": "pembeli@contoh.id", "name": "Contoh Pengguna" }
}

Nominal amount di atas selalu dihitung dan diisi oleh server Pusat Akun berdasarkan items yang divalidasi terhadap katalog resmi, bukan dikirim apa adanya dari frontend produk asal.

Format order ID

Order ID yang dibuat Pusat Akun, baik untuk checkout maupun tautan pembayaran, memakai format MB-<hint>-<ts36>-<rand10hex>:

Pada checkout tamu yang mengirim kunci idempotensi, dua segmen terakhir diturunkan dari kunci itu, sehingga klik ganda atau dua tab untuk pesanan dan metode yang sama menghasilkan order ID yang sama dan tidak melahirkan VA atau QR kedua. Jika transaksi lama sudah gagal atau kedaluwarsa, order ID diberi akhiran pendek tambahan supaya pembeli bisa mencoba lagi. Order ID lama dan tagihan perpanjangan otomatis yang dibuat Midtrans bisa berbentuk lain, jadi jangan mengurai order ID untuk logika bisnis. Gunakan sebagai kunci pencarian saja.

Guest checkout melalui /beli

Guest checkout di bayar.maubisa.id/beli memungkinkan pembelian tanpa login terlebih dahulu. Pengguna mengisi nama, email, nomor telepon (wajib dan harus nomor Indonesia yang wajar), memilih metode pembayaran, lalu menyelesaikan pembayaran. Untuk acara berbayar yang punya pertanyaan khusus, layar bayar menampilkan kartu "Tentang kamu" sebelum pilihan metode. Jawabannya tidak ikut dalam permintaan charge: dikirim otomatis setelah pembayaran lunas. Route guest charge tidak membuat user atau invoice sebelum pembayaran berhasil.

Data pembeli dibawa sebagai custom field Midtrans dan diproses kembali oleh webhook.

Setelah webhook valid dengan status paid diterima, sistem membuat atau menemukan akun berdasarkan email, membuat invoice, dan memberikan entitlement. Jika akun baru dibuat, pembeli menerima tautan masuk sekali klik (magic link), jadi tidak perlu mengatur password lebih dulu. Email ini, seperti seluruh email transaksional lain di ekosistem, dikirim oleh Pusat Akun yang juga menjadi Notification Service hub (ADR-013), bukan lewat SMTP terpisah.

Halaman bayar dan polling status

Halaman /bayar/[orderId] menampilkan instruksi pembayaran yang berasal dari charge Midtrans Core API. Instruksi dapat berupa QR (QRIS), nomor virtual account, kode pembayaran Mandiri, tautan e-wallet, atau langkah verifikasi kartu, sesuai metode.

Halaman ini dapat melakukan polling ke status pembayaran agar tampilan pengguna diperbarui. Polling berguna untuk pengalaman pengguna, tetapi bukan mekanisme aktivasi resmi.

Webhook sebagai sumber aktivasi

Webhook Midtrans adalah satu-satunya jalur yang boleh mengaktifkan akses. Pusat Akun menerima notifikasi server-to-server, memverifikasi keamanan, lalu memperbarui invoice dan entitlement.

Paid sticky-forward penting karena notifikasi pembayaran tidak selalu tiba dalam urutan ideal. Jika invoice sudah sah paid, notifikasi antara yang datang terlambat tidak boleh mencabut akses. Refund ditangani dengan aturan terminal tersendiri.

Contoh konseptual payload webhook

Contoh berikut adalah ilustrasi struktur konseptual notifikasi Midtrans, bukan dokumentasi API Midtrans resmi:

{
  "order_id": "MB-webinar-kari-mslvvi0o-555d85307b",
  "transaction_status": "settlement",
  "status_code": "200",
  "gross_amount": "150000.00",
  "payment_type": "qris",
  "signature_key": "a1b2c3...sha512hash",
  "transaction_time": "2026-08-09 21:14:03"
}

Server Pusat Akun menghitung ulang signature yang diharapkan dari order_id, status_code, gross_amount, dan server key, lalu membandingkannya dengan signature_key yang diterima. Jika tidak cocok, notifikasi ditolak dan dicatat sebagai percobaan mencurigakan.

Kasus tepi urutan webhook tidak berurutan

Midtrans dapat mengirim beberapa notifikasi untuk order yang sama pada rentang waktu singkat, misalnya pending diikuti settlement, atau dalam kasus jaringan yang tidak stabil, notifikasi settlement dapat tiba lebih dulu sebelum retry pending yang tertunda baru sampai belakangan. Pusat Akun menangani ini dengan aturan status berikut:

1. Jika invoice sudah berstatus paid, notifikasi baru dengan status lebih lemah (pending, cancel, expire, deny) diabaikan dan tidak mengubah status, tetapi tetap dicatat untuk audit.
2. Jika invoice belum paid dan notifikasi baru menyatakan settlement atau capture dengan fraud_status yang aman, invoice diperbarui menjadi paid dan entitlement diaktifkan.
3. Jika invoice sudah refunded, notifikasi apa pun setelahnya tidak dapat mengembalikan status ke paid, karena refunded bersifat terminal.
4. Jika dua notifikasi dengan order_id yang sama dan status yang sama tiba berkali-kali (duplikat karena retry Midtrans), pemrosesan kedua dan seterusnya bersifat idempoten, artinya tidak membuat entitlement ganda atau mengirim email konfirmasi ganda ke pengguna.

Invoice status engine

Status paid bersifat sticky-forward terhadap notifikasi yang datang terlambat dengan status lebih lemah seperti pending, cancel, atau expire. Status refunded bersifat terminal untuk mencegah notifikasi lama mengaktifkan kembali akses yang sudah dihentikan karena refund.

Metode pembayaran dan keamanan kartu

Metode pembayaran disediakan melalui Midtrans. Kode mendukung QRIS, GoPay, ShopeePay, DANA, virtual account bank (BCA, BNI, BRI, Permata, CIMB, Danamon), Mandiri Bill Payment, dan kartu kredit atau debit dengan 3DS. Metode yang benar-benar ditawarkan ke pembeli adalah irisan dari daftar itu dengan saluran yang diaktifkan di akun Midtrans dan pengaturan Pusat Akun, jadi tidak semua metode selalu tampil. Batas waktu pembayaran berbeda per metode: QRIS, GoPay, ShopeePay, dan DANA berlaku 60 menit supaya QR atau tautan tetap segar, sedangkan virtual account dan Mandiri berlaku 24 jam supaya pembeli sempat transfer. Kartu mengikuti sesi verifikasi 3DS-nya sendiri.

Untuk kartu, browser mendapatkan token dari integrasi kartu Midtrans. Server Maubisa tidak menerima, menyimpan, atau meminta nomor kartu penuh dan CVV. Jika kartu disimpan, yang disimpan adalah token aman dari Midtrans dan metadata tampilan seperti merek atau empat digit terakhir jika tersedia.

Pendekatan tokenisasi ini penting untuk kepatuhan PCI DSS (Payment Card Industry Data Security Standard, standar keamanan data kartu pembayaran), karena mengurangi jejak data kartu mentah yang harus dijaga langsung oleh server Maubisa.

Refund

Keputusan refund mengikuti Syarat dan Ketentuan dan ditinjau kasus per kasus. Permintaan pengguna masuk lewat halo@maubisa.id, dan kebijakannya dijelaskan di Refund. Bagian ini hanya menjelaskan mekanisme teknisnya.

Refund diproses oleh admin dari halaman invoice di Pusat Akun. Pengguna tidak bisa memicu refund sendiri.

Cara dana kembali bergantung pada metode pembayaran awal:

Refund manual tidak menghasilkan notifikasi refund dari Midtrans, sehingga status invoice tidak berubah otomatis. Penyesuaian akses untuk kasus ini ditangani admin secara terpisah.

Notifikasi refund sebagian diperlakukan sama dengan refund penuh: invoice menjadi refunded dan entitlement terkait diakhiri. Karena status refunded bersifat terminal, tim operasional perlu memastikan keputusan refund, termasuk refund sebagian, sudah final sebelum diproses. Tidak ada jalur otomatis untuk mengembalikan status ke paid setelah refund tercatat.

Informasi operasional untuk bantuan

Saat menelusuri masalah transaksi, informasi berikut biasanya diperlukan:

Komisi dan payout (teknis)

Pencatatan komisi mentor dan tutor berada di Pusat Akun (core), mengikuti prinsip "uang di core" (ADR-011 dan ADR-012). Produk spoke tidak menyimpan tabel komisi, saldo, atau payout. Ringkasan aturan per lini untuk pembaca nonteknis ada di Integrasi Produk Baru.

Sebutan peran mengikuti lini: tutor untuk lini Thesis (Maubisa Lulus) dan mentor untuk lini MBG+ (Maubisa Berkembang).

Model data

• Commission (core): ledger komisi yang hanya ditambah, tidak pernah diubah nilainya. Sumber yang aktif adalah thesis (70% harga paket bimbingan, untuk tutor) dan signup_bonus (bonus daftar mentor MBG+ Rp50.000, sekali per mentor, berstatus tertahan sampai gerbang lini MBG+ terbuka). Setiap sumber dipetakan ke tepat satu lini. Sumber yang tidak dikenal tidak masuk saldo lini mana pun dan ditahan untuk diklasifikasi admin.
• Kunci unik (transaction_id, source, user_id) mencegah satu transaksi melahirkan dua baris komisi untuk penerima yang sama. Untuk thesis, transaction_id adalah order ID invoice klien.
• payout_bank_accounts (core): satu rekening tujuan per pengguna, bank BCA, Mandiri, BRI, atau BNI, dengan nomor rekening 5 sampai 25 digit.
• payout_requests (core): pengajuan penarikan dengan status pending, completed, atau rejected, yang di antarmuka tampil sebagai Menunggu, Lunas, dan Ditolak. Data rekening disalin ke pengajuan saat diajukan, jadi riwayat tidak ikut berubah bila rekening diganti. Plafon satu pengajuan Rp100 juta.

Saldo dan aturan per lini

Saldo tidak disimpan sebagai kolom, tetapi dihitung dari ledger setiap kali dibaca, terpisah untuk tiap lini. Pengajuan berstatus pending dan completed mengurangi saldo, sedangkan pengajuan yang ditolak atau dibatalkan tidak, sehingga saldonya kembali dengan sendirinya. Selama gerbang sebuah lini tertutup, saldo bersihnya tampil sebagai saldo tertahan, bukan saldo tersedia.

Model pool watch-time (bagi hasil berbasis persentase omzet langganan MBG+) sudah dicabut dan tidak lagi menjadi sumber komisi. MBG Forge tidak masuk ledger, narasumber dibayar manual.

Aturan pengajuan yang ditegakkan server:

• Lini penarikan ditentukan server. Lini yang dikirim klien hanya permintaan, dan harus lini yang memang dimiliki pemohon. Selain itu permintaan ditolak.
• Satu pengajuan berlaku untuk satu lini, dan saldo lini tidak pernah digabung.
• Pembacaan saldo dan penulisan pengajuan terjadi dalam satu transaksi database, sehingga dua pengajuan bersamaan tidak bisa menarik saldo yang sama.
• Laju pengajuan dibatasi, dan penarikan dapat dilindungi CAPTCHA di edge bila diaktifkan.
• Satu lini hanya boleh punya satu pengajuan pending, dan pemohon tidak bisa membatalkannya sendiri. Kalau ada yang salah, admin menolak pengajuan itu lalu pemohon mengajukan ulang.
• Hanya admin yang boleh mengubah pending menjadi completed atau rejected. Status final tidak bisa diubah lagi. Setiap aksi tercatat di audit log, dan pemohon menerima email.
• Pencairan dilakukan manual lewat transfer bank. Bukti transfer dapat dilampirkan admin.

Alur pencatatan komisi

Admin memilih bimbingan yang sedang berjalan di panel thesis Pusat Akun
  |
  v
Pusat Akun memanggil POST /admin/v1/bimbingan/{id}/complete di thesis
(token federasi, idempoten)
  |
  v
Pusat Akun mencari invoice thesis lunas milik klien
  |
  v
Komisi 70% ditulis ke ledger (kunci unik mencegah baris ganda)
  |
  v
Saldo tutor di lini thesis bertambah

Komisi tidak dicatat per sesi. Jika invoice lunas klien tidak ditemukan atau identitas tutor tidak lengkap, bimbingan tetap ditandai selesai, tetapi komisi tidak ditulis dan alasannya tercatat di audit log untuk ditindaklanjuti admin.

Alur payout

Penerima komisi membuka /payouts di Pusat Akun
  |
  v
Saldo per lini dihitung dari ledger (tersedia dan tertahan)
  |
  v
Simpan rekening tujuan (BCA, Mandiri, BRI, BNI)
  |
  v
Ajukan penarikan untuk satu lini (minimum sesuai lini)
(CAPTCHA bila diaktifkan)
  |
  +-> pemohon membatalkan selama status masih pending
  |
  v
Admin transfer manual, lalu tandai completed (Lunas) dan lampirkan bukti,
atau tandai rejected (Ditolak)

Kontrak untuk produk spoke

• Endpoint POST /api/commissions sudah dipensiunkan dan membalas 410 Gone secara permanen. Jangan mengirim event komisi dari spoke. Arah pencatatan komisi dari spoke ke hub sudah dihapus.
• Komisi thesis dicatat hub sendiri saat admin menyelesaikan bimbingan. Spoke thesis cukup menyediakan POST /admin/v1/bimbingan/{id}/complete yang idempoten, dan menyertakan klien_email serta tutor_core_user_id (ID tutor di hub, bukan ID di spoke) di daftar bimbingan yang sedang berjalan. Tidak ada data finansial yang dikirim spoke.
• Jika spoke suatu saat perlu jalur tulis baru ke hub, gunakan verifikasi token federasi masuk (JWT berumur pendek, scope default-deny, issuer tepercaya, anti-replay jti), bukan shared secret statis.
• Untuk menampilkan ringkasan penghasilan, spoke dapat memanggil GET /api/spoke/earnings dengan cookie SSO pengguna. Responsnya memuat saldo per lini beserta porsi tertahan dan alasannya. Platform MBG+ saat ini hanya menjelaskan model penghasilan dan menautkan ke Pusat Akun. Saldo dan penarikan tetap di /payouts.

Langkah selanjutnya