Callback vs redirect: kenapa status pembayaran harus dicek dari webhook, bukan halaman sukses

Setelah pelanggan membayar, dua hal terjadi hampir bersamaan:

1. PAYWISE mengarahkan pelanggan kembali ke website Anda (redirect, atau return URL).
2. PAYWISE mengirim webhook bertanda tangan ke server Anda (callback).

Keduanya terlihat mirip, tapi tugasnya sangat berbeda. Tertukar di antara keduanya adalah salah satu kesalahan integrasi yang paling sering, dan paling mahal.

Redirect: untuk dilihat pelanggan

Saat pembayaran paid, expired, atau failed, halaman pembayaran mengarahkan pelanggan ke return URL Anda, dengan hasilnya ditambahkan:

https://toko.contoh.com/terima-kasih?reference=PW20260921143022AB3F&merchant_reference=ORDER-1042&status=paid

URL ini bukan bukti apa pun. Siapa saja bisa mengetiknya di browser, mengganti status=failed menjadi status=paid, lalu menekan Enter. Kalau toko Anda menandai pesanan lunas saat halaman ini dibuka, siapa pun bisa mendapat barang Anda gratis.

Redirect juga bisa tidak pernah terjadi: pelanggan menutup tab, koneksinya putus, atau membayar di HP lalu tidak kembali.

Pakai redirect hanya untuk menampilkan pesan: "Terima kasih, pembayaran Anda sedang kami konfirmasi."

Webhook: untuk server Anda

Webhook adalah request POST dari PAYWISE ke server Anda, dari server ke server. Webhook ditandatangani dengan webhook secret Anda di header X-PAYWISE-Signature, sehingga server Anda bisa memastikan pesan itu benar dari PAYWISE dan tidak diubah siapa pun. Webhook tetap sampai walaupun pelanggan menutup tab, dan pengiriman yang gagal dicoba ulang otomatis.

Di webhook inilah Anda menandai pesanan lunas dan mulai memproses pesanan. Cara memeriksa tanda tangannya dijelaskan di memverifikasi tanda tangan webhook PAYWISE.

Cara keduanya bekerja sama

Penangan webhook: verifikasi, lalu perbarui pesanan satu kali.

$raw = file_get_contents('php://input');
$event = \Paywise\Webhook::parse($raw, $_SERVER['HTTP_X_PAYWISE_SIGNATURE'] ?? '', getenv('PAYWISE_WEBHOOK_SECRET'));

if ($event['event'] === 'payment.paid') {
    // Hanya mengubah pesanan yang belum lunas: pengiriman ulang tidak mengubah apa-apa.
    $db->prepare("UPDATE orders SET status = 'paid' WHERE paywise_reference = ? AND status = 'unpaid'")
       ->execute([$event['data']['reference']]);
}
http_response_code(200);

Halaman terima kasih: baca status dari database Anda sendiri, jangan dari URL.

$order = findOrderByPaywiseReference($_GET['reference'] ?? '');
if ($order && $order->status === 'paid') {
    echo 'Terima kasih! Pesanan Anda sudah terkonfirmasi.';
} else {
    echo 'Terima kasih! Pembayaran Anda sedang kami konfirmasi. Halaman ini akan diperbarui sebentar lagi.';
}

Kalau webhook belum sampai saat pelanggan tiba di halaman ini, muat ulang halaman setelah beberapa detik, atau tanyakan langsung ke PAYWISE dengan GET /api/v1/transactions/{reference}. Request itu memakai API key Anda, jadi jawabannya bisa dipercaya.

Checklist

• Proses pesanan hanya dari webhook payment.paid yang sudah diverifikasi, atau setelah GET /api/v1/transactions/{reference} menjawab paid.
• Jangan pernah percaya status di return URL.
• Buat penangan webhook yang idempoten: event yang sama bisa datang lebih dari sekali.
• Balas webhook dengan 2xx secepatnya; kerjakan proses yang lama (email, update stok) sesudahnya.
• Uji ketiga hasil di sandbox. Lihat menguji endpoint webhook.