Tutorial Integrasi Payment Gateway Midtrans Laravel 12: Panduan Lengkap & Praktis

oleh

Membangun aplikasi e-commerce atau platform SaaS di Indonesia membutuhkan sistem pembayaran yang handal, aman, dan mendukung berbagai metode pembayaran lokal seperti QRIS, transfer bank, hingga gerai retail. Salah satu solusi terbaik saat ini adalah menggunakan Midtrans. Dalam artikel ini, kita akan membahas secara mendalam tutorial integrasi payment gateway midtrans laravel 12 untuk membantu bisnis Anda melakukan otomasi transaksi dengan standar keamanan tinggi.

Laravel 12, sebagai versi terbaru dari framework PHP paling populer, menawarkan berbagai fitur modern yang membuat proses integrasi menjadi lebih efisien. Dengan menggabungkan fleksibilitas Laravel dan kelengkapan fitur Midtrans, Anda dapat menciptakan pengalaman belanja yang mulus bagi pengguna. Mari kita mulai panduan langkah demi langkah ini dari nol hingga sistem siap digunakan di lingkungan produksi.

Mengapa Memilih Midtrans dan Laravel 12?

Sebelum masuk ke teknis tutorial integrasi payment gateway midtrans laravel 12, penting untuk memahami mengapa kombinasi ini sangat direkomendasikan untuk developer profesional di Indonesia. Midtrans adalah payment gateway yang telah mengantongi izin dari Bank Indonesia dan memiliki dokumentasi yang sangat lengkap.

Berdasarkan data industri, sistem pembayaran digital di Indonesia tumbuh lebih dari 20% setiap tahunnya. Midtrans mendukung lebih dari 24 metode pembayaran, termasuk GoPay, ShopeePay, OVO, serta Virtual Account dari bank-bank besar seperti BCA, Mandiri, dan BRI. Dengan Laravel 12, Anda mendapatkan keunggulan performa PHP 8.2+ dan fitur type-safety yang lebih ketat, sehingga mengurangi potensi bug pada logika pembayaran Anda.

“Keamanan adalah prioritas utama dalam transaksi finansial. Menggunakan framework yang up-to-date seperti Laravel 12 memastikan aplikasi Anda memiliki patch keamanan terbaru untuk melindungi data sensitif pengguna.”

Persiapan Akun dan Lingkungan Pengembangan

Untuk mengikuti tutorial ini, ada beberapa persyaratan yang harus Anda penuhi:

  • PHP 8.2 atau lebih baru: Laravel 12 membutuhkan versi PHP modern.
  • Composer: Dependency manager untuk menginstal library.
  • Akun Midtrans: Daftar di Midtrans Dashboard dan pastikan Anda berada di mode Sandbox untuk keperluan testing.
  • Server Lokal: Anda bisa menggunakan Laravel Herd, XAMPP, atau Docker (Laravel Sail).

Setelah mendaftar di Midtrans, buka menu Settings > Access Keys. Anda akan membutuhkan Server Key dan Client Key. Simpan kedua kunci ini karena akan kita masukkan ke dalam file konfigurasi Laravel.

Langkah 1: Instalasi Proyek Laravel 12

Buka terminal atau command prompt Anda, lalu jalankan perintah berikut untuk membuat proyek baru:

composer create-project laravel/laravel midtrans-app

Masuk ke direktori proyek:

cd midtrans-app

Setelah itu, kita perlu menginstal SDK resmi dari Midtrans untuk PHP. Jalankan perintah berikut:

composer require midtrans/midtrans-php

Library ini mempermudah kita dalam melakukan request ke API Midtrans tanpa perlu menulis fungsi cURL secara manual, yang merupakan bagian krusial dari tutorial integrasi payment gateway midtrans laravel 12 ini.

Langkah 2: Konfigurasi SDK Midtrans

Buka file .env di root direktori proyek Anda dan tambahkan konfigurasi berikut di bagian paling bawah:

MIDTRANS_SERVER_KEY=SB-Mid-server-xxxxxxxxxxxx
MIDTRANS_CLIENT_KEY=SB-Mid-client-xxxxxxxxxxxx
MIDTRANS_IS_PRODUCTION=false
MIDTRANS_IS_SANITIZED=true
MIDTRANS_IS_3DS=true

Pastikan Anda mengganti nilai MIDTRANS_SERVER_KEY dan MIDTRANS_CLIENT_KEY dengan kunci yang Anda dapatkan dari dashboard Midtrans Sandbox. Selanjutnya, buatlah sebuah file konfigurasi baru di config/midtrans.php untuk memudahkan pemanggilan nilai-nilai tersebut:

<?php

return [
    'server_key' => env('MIDTRANS_SERVER_KEY'),
    'client_key' => env('MIDTRANS_CLIENT_KEY'),
    'is_production' => env('MIDTRANS_IS_PRODUCTION', false),
    'is_sanitized' => env('MIDTRANS_IS_SANITIZED', true),
    'is_3ds' => env('MIDTRANS_IS_3DS', true),
];

Langkah 3: Menyiapkan Database dan Model Transaksi

Kita memerlukan tabel untuk menyimpan data pesanan dan status pembayarannya. Buatlah model dan migrasi baru dengan perintah:

php artisan make:model Order -m

Buka file migrasi yang baru saja dibuat di database/migrations/xxxx_create_orders_table.php dan modifikasi strukturnya sebagai berikut:

public function up(): void
{
    Schema::create('orders', function (Blueprint $table) {
        $table->id();
        $table->string('number');
        $table->decimal('total_price', 15, 2);
        $table->enum('payment_status', ['1', '2', '3', '4'])->comment('1=pending, 2=success, 3=failed, 4=expired');
        $table->string('snap_token')->nullable();
        $table->timestamps();
    });
}

Jalankan migrasi tersebut:

php artisan migrate

Langkah 4: Implementasi Midtrans Snap API

Snap API adalah cara termudah untuk mengintegrasikan Midtrans karena menyediakan UI pembayaran yang siap pakai. Mari kita buat sebuah controller bernama OrderController.

php artisan make:controller OrderController

Di dalam controller ini, kita akan membuat logika untuk membuat pesanan dan mendapatkan Snap Token dari Midtrans. Perhatikan penggunaan namespace dan konfigurasi SDK:

namespace AppHttpControllers;

use AppModelsOrder;
use IlluminateHttpRequest;
use MidtransConfig;
use MidtransSnap;

class OrderController extends Controller
{
    public function __construct()
    {
        Config::$serverKey = config('midtrans.server_key');
        Config::$isProduction = config('midtrans.is_production');
        Config::$isSanitized = config('midtrans.is_sanitized');
        Config::$is3ds = config('midtrans.is_3ds');
    }

    public function checkout(Request $request)
    {
        $order = Order::create([
            'number' => 'ORD-' . time(),
            'total_price' => 150000,
            'payment_status' => '1',
        ]);

        $params = [
            'transaction_details' => [
                'order_id' => $order->number,
                'gross_amount' => $order->total_price,
            ],
            'customer_details' => [
                'first_name' => 'Budi',
                'email' => '[email protected]',
            ],
        ];

        $snapToken = Snap::getSnapToken($params);
        $order->snap_token = $snapToken;
        $order->save();

        return view('checkout', compact('order'));
    }
}

Dalam tutorial integrasi payment gateway midtrans laravel 12 ini, Snap Token berfungsi sebagai kunci akses unik yang dikirimkan ke frontend untuk menampilkan popup pembayaran Midtrans.

Langkah 5: Menangani Webhook (Notification Handler)

Webhook adalah fitur yang digunakan Midtrans untuk memberi tahu server Anda bahwa status pembayaran telah berubah (misalnya dari pending menjadi success). Ini sangat penting karena pengguna mungkin menutup browser sebelum kembali ke situs Anda.

Buat method baru di OrderController untuk menangani notifikasi ini:

public function callback(Request $request)
{
    $serverKey = config('midtrans.server_key');
    $hashed = hash("sha512", $request->order_id . $request->status_code . $request->gross_amount . $serverKey);

    if ($hashed == $request->signature_key) {
        if ($request->transaction_status == 'capture' || $request->transaction_status == 'settlement') {
            $order = Order::where('number', $request->order_id)->first();
            $order->update(['payment_status' => '2']);
        }
    }
}

Penting: Jangan lupa untuk menambahkan pengecualian CSRF untuk route callback ini di file bootstrap/app.php (untuk Laravel 12) agar Midtrans bisa mengirimkan data POST ke server Anda.

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'api/callback',
    ]);
})

Langkah 6: Pengujian di Lingkungan Sandbox

Setelah semua kode terpasang, saatnya melakukan pengujian. Midtrans menyediakan Simulator Pembayaran yang bisa Anda gunakan untuk mensimulasikan berbagai skenario seperti pembayaran sukses, gagal, atau kadaluarsa.

Beberapa hal yang perlu diperiksa saat testing:

  • Apakah popup Snap muncul dengan benar?
  • Apakah status di database berubah menjadi ‘success’ setelah pembayaran dilakukan di simulator?
  • Apakah log aplikasi mencatat adanya error saat menerima webhook?

Tips Keamanan dan Best Practices

Mengintegrasikan sistem pembayaran berarti Anda bertanggung jawab atas keamanan alur data. Berikut adalah beberapa tips tambahan untuk meningkatkan kualitas integrasi Anda:

  1. Gunakan HTTPS: Selalu gunakan koneksi terenkripsi untuk semua endpoint, terutama callback webhook.
  2. Validasi Signature Key: Jangan pernah mempercayai data webhook tanpa memvalidasi signature_key seperti yang ditunjukkan pada langkah 5.
  3. Logging: Catat setiap notifikasi yang masuk dari Midtrans ke dalam file log Laravel (storage/logs/laravel.log) untuk mempermudah debugging jika terjadi perselisihan data.
  4. Idempotency: Pastikan logika callback Anda aman jika dipanggil berkali-kali untuk order ID yang sama (idempotent).

Kesimpulan

Mengikuti tutorial integrasi payment gateway midtrans laravel 12 ini memberikan fondasi yang kuat bagi aplikasi Anda untuk menerima pembayaran secara otomatis. Dengan Laravel 12, proses ini menjadi lebih terstruktur dan modern. Ingatlah untuk selalu melakukan pengujian menyeluruh di mode Sandbox sebelum beralih ke mode Production.

Integrasi yang sukses bukan hanya tentang kode yang berjalan, tetapi juga tentang memberikan rasa aman kepada pelanggan Anda. Dengan Midtrans dan Laravel, Anda sudah selangkah lebih maju dalam membangun platform digital yang profesional dan terpercaya di Indonesia.

Apakah Anda menemui kendala saat mencoba tutorial ini? Jangan ragu untuk membaca dokumentasi resmi Midtrans atau bertanya di komunitas pengembang Laravel Indonesia. Selamat mencoba!

Tinggalkan komentar