Integrasi PAYWISE dengan Laravel dan PHP dalam 15 menit

Panduan ini menghubungkan toko Laravel ke PAYWISE dengan PHP SDK resmi: membuat pembayaran QRIS, mengarahkan pelanggan ke halaman pembayaran, lalu menandai pesanan lunas saat webhook bertanda tangan datang. PHP biasa (tanpa framework) caranya sama; perbedaannya ada di bagian akhir.

Yang Anda butuhkan: PHP 7.4 atau lebih baru dengan curl dan json, akun PAYWISE, API key sandbox (pw_test_…, di menu Kunci API), dan website dengan halaman pembayaran yang sudah dinyalakan (di menu Website & Webhook).

1. Instal SDK (2 menit)

Unduh PHP SDK dari halaman developer lalu ekstrak ke proyek Anda, misalnya menjadi packages/paywise-php. Lalu beri tahu Composer lokasinya, di composer.json:

"repositories": [
    { "type": "path", "url": "packages/paywise-php" }
]

lalu instal:

composer require "paywise/paywise-php:*@dev"

SDK ini tidak punya dependensi tambahan.

2. Atur key Anda (2 menit)

Di .env:

PAYWISE_KEY=pw_test_xxxxxxxxxxxxxxxx
PAYWISE_WEBHOOK_SECRET=webhook-secret-anda

Webhook secret ada di halaman Website & Webhook. Di config/services.php:

'paywise' => [
    'key' => env('PAYWISE_KEY'),
    'webhook_secret' => env('PAYWISE_WEBHOOK_SECRET'),
],

Tambahkan kolom untuk menyimpan referensi PAYWISE setiap pesanan:

$table->string('paywise_reference')->nullable()->index();

3. Buat pembayaran (4 menit)

use Paywise\Client;
use Paywise\PaywiseException;

class PaymentController extends Controller
{
    public function pay(Order $order)
    {
        $paywise = new Client(config('services.paywise.key'));

        try {
            $payment = $paywise->createTransaction([
                'merchant_reference' => 'ORDER-' . $order->id, // sekaligus idempotency key
                'amount'             => $order->total,         // QRIS: rupiah bulat
                'payment_method'     => 'QRIS',
                'customer_id'        => (string) $order->user_id,
            ]);
        } catch (PaywiseException $e) {
            report($e);

            return back()->with('error', 'Pembayaran belum bisa dibuat. Silakan coba lagi.');
        }

        $order->update(['paywise_reference' => $payment['reference']]);

        return redirect()->away($payment['checkout_url']);
    }
}

Kalau request timeout, aman untuk mencoba lagi dengan merchant_reference yang sama: PAYWISE mengembalikan pembayaran yang lama, bukan membuat yang kedua. $e->isRetryable() memberi tahu kapan mencoba ulang itu masuk akal.

4. Tangani webhook (5 menit)

use Illuminate\Http\Request;
use Paywise\Webhook;

public function webhook(Request $request)
{
    try {
        $event = Webhook::parse(
            $request->getContent(),                          // body MENTAH
            (string) $request->header('X-PAYWISE-Signature'),
            config('services.paywise.webhook_secret')
        );
    } catch (PaywiseException $e) {
        return response('Invalid signature', 400);
    }

    $reference = $event['data']['reference'];

    if ($event['event'] === 'payment.paid') {
        // Hanya pesanan yang belum lunas yang berubah, jadi pengiriman ulang tidak berpengaruh.
        Order::where('paywise_reference', $reference)->where('status', 'unpaid')
            ->update(['status' => 'paid', 'paid_at' => now()]);
    } elseif (in_array($event['event'], ['payment.expired', 'payment.failed'], true)) {
        Order::where('paywise_reference', $reference)->where('status', 'unpaid')
            ->update(['status' => 'payment_failed']);
    }

    return response('OK');
}

Route, di routes/web.php:

Route::post('/orders/{order}/pay', [PaymentController::class, 'pay'])->name('orders.pay');
Route::post('/webhooks/paywise', [PaymentController::class, 'webhook']);

Webhook datang dari PAYWISE, bukan dari browser, jadi tidak membawa token CSRF. Kecualikan di bootstrap/app.php (Laravel 11 ke atas):

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: ['webhooks/paywise']);
})

Di Laravel 10, tambahkan 'webhooks/paywise' ke $except di app/Http/Middleware/VerifyCsrfToken.php.

Terakhir, isi https://toko-anda.com/webhooks/paywise sebagai URL webhook di halaman Website & Webhook, pilih event-nya, lalu tekan Kirim tes.

5. Uji di sandbox (2 menit)

Buat pesanan di toko Anda. Di halaman pembayaran, pilih Berhasil dibayar di bagian Simulasikan hasilnya: webhook Anda menerima payment.paid dan pesanan menjadi lunas. Coba juga Gagal dan Kedaluwarsa. Setiap pengiriman, beserta jawaban server Anda, tercatat di halaman Website & Webhook.

Kalau semuanya berjalan, ganti key sandbox dengan key live (pw_live_…) lalu lakukan satu pembayaran kecil sungguhan.

PHP biasa

Tanpa Composer, panggil SDK secara langsung:

require __DIR__ . '/paywise-php/autoload.php';

Pemanggilannya sama. Di skrip webhook, baca body mentah dengan file_get_contents('php://input') dan tanda tangannya dengan $_SERVER['HTTP_X_PAYWISE_SIGNATURE'].

Langkah berikutnya

• Untuk USDT, kirim 'payment_method' => 'USDT' dan 'network' => 'BEP20'.
• Baca kenapa webhook, bukan redirect, yang menentukan dan 10 kesalahan integrasi yang sering terjadi.
• Referensi lengkapnya ada di dokumentasi API.