Source code aplikasi, template web, dan ebook. Unduh dari akun setelah bayar. Lihat produk

Blog / REST API, Integrasi & Automation / Panduan Integrasi Payment Gate...
REST API, Integrasi & Automation

Panduan Integrasi Payment Gateway di Laravel: Alur Pembayaran, Callback, dan Verifikasi Status

AD

Admin HijrahKreativa

Penulis

19 Oct 2026
17 min read
21 views

Alur pembayaran iuran yang benar dari awal sampai akhir dengan contoh Midtrans Snap: model pembayaran dengan mesin status, pembuatan transaksi di server, halaman bayar, notifikasi HTTP yang diverifikasi tanda tangannya, konfirmasi lewat API status, penanganan duplikat dan urutan, rekonsiliasi terjadwal, serta pengujian di sandbox.

Overview

Warga ingin membayar iuran bulanan lewat QRIS, virtual account, atau e-wallet langsung dari aplikasi. Integrasi payment gateway tampak sederhana, tetapi kesalahannya langsung berdampak ke uang:

Kesalahan Akibat
Menganggap redirect "pembayaran selesai" sebagai bukti bayar Warga bisa membuka URL itu tanpa membayar dan iuran tercatat lunas
Jumlah tagihan dikirim dari browser Tagihan Rp 50.000 bisa diubah menjadi Rp 500
Notifikasi tidak diverifikasi Siapa pun bisa mengirim "settlement" palsu
Notifikasi duplikat diproses ulang Saldo kas tercatat dua kali
Status pending yang datang terlambat menimpa settlement Pembayaran yang sudah lunas kembali "menunggu"
Tidak ada rekonsiliasi Notifikasi yang hilang membuat pembayaran sah tidak pernah tercatat
Server key ada di JavaScript Siapa pun bisa membuat transaksi dan membaca status atas nama Anda

Hasil akhir:

[Warga]          [Laravel]                         [Midtrans]
   │  Bayar iuran   │                                  │
   │──────────────► │ buat Pembayaran (status: dibuat) │
   │                │ POST /snap/v1/transactions ─────►│
   │                │ ◄──────────── token, redirect_url │
   │ ◄── halaman bayar (Snap)                          │
   │ ──────────────────── membayar ──────────────────► │
   │                │ ◄──── HTTP Notification (POST) ──│
   │                │ verifikasi signature              │
   │                │ GET /v2/{order_id}/status ──────►│  (konfirmasi)
   │                │ ◄───────────────────── status ────│
   │                │ tandai berhasil → iuran lunas     │
   │ ◄── notifikasi "pembayaran diterima"               │
   │                │                                   │
   │       (scheduler) rekonsiliasi pembayaran pending  │

Prinsip yang sama berlaku untuk payment gateway lain (Xendit, DOKU, Duitku, dan sebagainya); yang berbeda hanya format API dan cara verifikasinya.

Prerequisites

Komponen Versi
PHP 8.3+ (disarankan 8.4)
Laravel 13.x
Akun payment gateway Midtrans (sandbox untuk pengembangan)
Queue Redis, worker berjalan
HTTPS Wajib, URL notifikasi harus dapat dijangkau dari internet
Testing Pest 4

Pola penerimaan webhook mengikuti artikel Webhook Laravel: Cara Menerima, Memvalidasi, dan Memproses Event dari Sistem Eksternal.

Selalu rujuk dokumentasi resmi penyedia untuk versi API, URL production, dan daftar status terbaru. Contoh di artikel ini mengikuti dokumentasi Midtrans untuk Snap dan HTTP Notification.

Step-by-step Tutorial

Langkah 1: Konfigurasi

// config/services.php
'midtrans' => [
    'server_key'    => env('MIDTRANS_SERVER_KEY'),
    'client_key'    => env('MIDTRANS_CLIENT_KEY'),
    'is_production' => (bool) env('MIDTRANS_IS_PRODUCTION', false),
    'snap_url'      => env('MIDTRANS_IS_PRODUCTION', false)
        ? 'https://app.midtrans.com/snap/v1/transactions'
        : 'https://app.sandbox.midtrans.com/snap/v1/transactions',
    'api_url'       => env('MIDTRANS_IS_PRODUCTION', false)
        ? 'https://api.midtrans.com'
        : 'https://api.sandbox.midtrans.com',
    'snap_js'       => env('MIDTRANS_IS_PRODUCTION', false)
        ? 'https://app.midtrans.com/snap/snap.js'
        : 'https://app.sandbox.midtrans.com/snap/snap.js',
    'kedaluwarsa_menit' => 60 * 24,
],
# .env (sandbox)
MIDTRANS_SERVER_KEY=SB-Mid-server-xxxxxxxx
MIDTRANS_CLIENT_KEY=SB-Mid-client-xxxxxxxx
MIDTRANS_IS_PRODUCTION=false
  • Server key hanya di server. Jangan pernah dikirim ke browser atau aplikasi mobile.
  • Client key boleh di frontend; fungsinya hanya membuka halaman pembayaran Snap.
  • Gunakan kunci sandbox di lokal dan staging, kunci production hanya di production.

Langkah 2: Model Pembayaran dengan Mesin Status

Pisahkan iuran (tagihan) dari pembayaran (percobaan membayar). Satu iuran bisa memiliki beberapa percobaan: yang pertama kedaluwarsa, yang kedua berhasil.

Schema::create('pembayaran', function (Blueprint $table) {
    $table->id();
    $table->uuid('uuid')->unique();
    $table->string('referensi', 50)->unique();         // order_id ke Midtrans
    $table->foreignId('iuran_id')->constrained('iuran');
    $table->foreignId('user_id')->constrained();
    $table->unsignedBigInteger('jumlah');              // rupiah, dihitung server
    $table->string('status', 20)->default('dibuat');   // dibuat | menunggu | berhasil | gagal | kedaluwarsa | dibatalkan | dikembalikan
    $table->string('metode', 30)->nullable();          // qris, bank_transfer, gopay, ...
    $table->string('snap_token', 100)->nullable();
    $table->string('gateway_transaction_id', 100)->nullable()->unique();
    $table->timestamp('kedaluwarsa_pada')->nullable();
    $table->timestamp('dibayar_pada')->nullable();
    $table->json('respons_terakhir')->nullable();      // status terakhir dari gateway
    $table->timestamps();

    $table->index(['status', 'created_at']);
});
// app/Enums/StatusPembayaran.php
namespace App\Enums;

enum StatusPembayaran: string
{
    case Dibuat = 'dibuat';
    case Menunggu = 'menunggu';
    case Berhasil = 'berhasil';
    case Gagal = 'gagal';
    case Kedaluwarsa = 'kedaluwarsa';
    case Dibatalkan = 'dibatalkan';
    case Dikembalikan = 'dikembalikan';

    public function final(): bool
    {
        return in_array($this, [self::Berhasil, self::Gagal, self::Kedaluwarsa, self::Dibatalkan, self::Dikembalikan], true);
    }

    /** Transisi yang diizinkan: status hanya bergerak maju */
    public function bolehMenjadi(self $baru): bool
    {
        return match ($this) {
            self::Dibuat   => $baru !== self::Dibuat,
            self::Menunggu => ! in_array($baru, [self::Dibuat, self::Menunggu], true),
            self::Berhasil => $baru === self::Dikembalikan,
            default        => false,
        };
    }
}

Mesin status ini adalah pertahanan utama terhadap notifikasi yang datang tidak berurutan: pending yang terlambat tidak bisa mengembalikan pembayaran berhasil menjadi menunggu.

Langkah 3: Membuat Transaksi di Server

// app/Integrations/Midtrans/MidtransClient.php
namespace App\Integrations\Midtrans;

use Illuminate\Support\Facades\Http;

final class MidtransClient
{
    public function __construct(#[\SensitiveParameter] private readonly string $serverKey) {}

    private function http()
    {
        return Http::withBasicAuth($this->serverKey, '')        // server key sebagai username, password kosong
            ->acceptJson()
            ->asJson()
            ->timeout(15)
            ->connectTimeout(5);
    }

    public function buatSnap(array $payload): array
    {
        return $this->http()
            ->post(config('services.midtrans.snap_url'), $payload)
            ->throw()
            ->json();                                             // ['token' => ..., 'redirect_url' => ...]
    }

    public function status(string $orderId): array
    {
        return $this->http()
            ->retry(3, 500, throw: true)
            ->get(config('services.midtrans.api_url').'/v2/'.rawurlencode($orderId).'/status')
            ->json();
    }
}
// app/Services/Pembayaran/MulaiPembayaran.php
namespace App\Services\Pembayaran;

use App\Enums\StatusPembayaran;
use App\Exceptions\BusinessRuleException;
use App\Integrations\Midtrans\MidtransClient;
use App\Models\{Iuran, Pembayaran, User};
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;

final class MulaiPembayaran
{
    public function __construct(private readonly MidtransClient $midtrans) {}

    public function handle(Iuran $iuran, User $user): Pembayaran
    {
        if ($iuran->sudahLunas()) {
            throw new BusinessRuleException('Iuran ini sudah lunas.', 'iuran_sudah_dibayar');
        }

        // Gunakan kembali pembayaran yang masih aktif agar warga tidak membuat tagihan ganda
        $aktif = $iuran->pembayaran()
            ->where('status', StatusPembayaran::Menunggu)
            ->where('kedaluwarsa_pada', '>', now()->addMinutes(5))
            ->latest()->first();

        if ($aktif) {
            return $aktif;
        }

        $pembayaran = DB::transaction(fn () => Pembayaran::create([
            'uuid'      => (string) Str::uuid(),
            'referensi' => 'IUR-'.$iuran->id.'-'.strtoupper(Str::random(8)),
            'iuran_id'  => $iuran->id,
            'user_id'   => $user->id,
            'jumlah'    => $iuran->sisaTagihan(),           // DIHITUNG SERVER, bukan dari request
            'status'    => StatusPembayaran::Dibuat,
            'kedaluwarsa_pada' => now()->addMinutes(config('services.midtrans.kedaluwarsa_menit')),
        ]));

        $snap = $this->midtrans->buatSnap([
            'transaction_details' => [
                'order_id'     => $pembayaran->referensi,
                'gross_amount' => $pembayaran->jumlah,
            ],
            'item_details' => [[
                'id'       => 'IURAN-'.$iuran->periode,
                'price'    => $pembayaran->jumlah,
                'quantity' => 1,
                'name'     => 'Iuran RW '.$iuran->periode,
            ]],
            'customer_details' => [
                'first_name' => Str::limit($user->name, 50, ''),
                'email'      => $user->email,
            ],
            'expiry' => [
                'unit'     => 'minutes',
                'duration' => config('services.midtrans.kedaluwarsa_menit'),
            ],
            'callbacks' => [
                'finish' => route('pembayaran.selesai', $pembayaran->uuid),
            ],
        ]);

        $pembayaran->update([
            'snap_token' => $snap['token'],
            'status'     => StatusPembayaran::Menunggu,
        ]);

        return $pembayaran;
    }
}

Poin penting:

  • Jumlah dihitung di server dari data iuran. Browser hanya mengirim "saya ingin membayar iuran #812".
  • order_id unik per percobaan, tidak bisa ditebak, dan tetap terkait ke iuran.
  • item_details harus berjumlah sama dengan gross_amount; bila tidak, Midtrans menolak transaksi.
  • Pembayaran aktif yang masih berlaku dipakai ulang agar warga yang menekan "Bayar" dua kali tidak menerima dua tagihan.
  • Data pelanggan dikirim seperlunya; jangan kirim NIK atau data yang tidak dibutuhkan penyedia.

Langkah 4: Halaman Bayar dengan Snap

// app/Http/Controllers/PembayaranController.php
public function store(Iuran $iuran, MulaiPembayaran $mulai)
{
    Gate::authorize('bayar', $iuran);

    $pembayaran = $mulai->handle($iuran, auth()->user());

    return view('pembayaran.bayar', [
        'pembayaran' => $pembayaran,
        'clientKey'  => config('services.midtrans.client_key'),
        'snapJs'     => config('services.midtrans.snap_js'),
    ]);
}
{{-- resources/views/pembayaran/bayar.blade.php --}}
<x-layouts.app title="Bayar Iuran">
    <x-card class="mx-auto max-w-md text-center">
        <p class="text-slate-500">Iuran {{ $pembayaran->iuran->periode }}</p>
        <p class="my-2 text-3xl font-bold">Rp {{ number_format($pembayaran->jumlah, 0, ',', '.') }}</p>
        <x-button id="tombol-bayar" class="w-full">Pilih Metode Pembayaran</x-button>
        <p class="mt-3 text-xs text-slate-500">Berlaku hingga {{ $pembayaran->kedaluwarsa_pada->timezone('Asia/Jakarta')->translatedFormat('d F Y H:i') }} WIB</p>
    </x-card>

    @push('scripts')
        <script src="{{ $snapJs }}" data-client-key="{{ $clientKey }}"></script>
        <script nonce="{{ Vite::cspNonce() }}">
            document.getElementById('tombol-bayar').addEventListener('click', () => {
                window.snap.pay(@js($pembayaran->snap_token), {
                    onSuccess: () => window.location = @js(route('pembayaran.selesai', $pembayaran->uuid)),
                    onPending: () => window.location = @js(route('pembayaran.selesai', $pembayaran->uuid)),
                    onError:   () => alert('Pembayaran gagal diproses. Silakan coba lagi.'),
                });
            });
        </script>
    @endpush
</x-layouts.app>

Bila aplikasi memakai Content Security Policy (artikel Laravel Security Hardening), izinkan domain Midtrans di script-src, frame-src, dan connect-src sesuai dokumentasi penyedia.

Halaman "selesai" bukan bukti pembayaran. Callback onSuccess dan redirect finish hanya memberi tahu bahwa pengguna kembali ke aplikasi. Halaman ini menampilkan status dari database, yang diperbarui oleh notifikasi server-ke-server:

public function selesai(string $uuid)
{
    $pembayaran = Pembayaran::where('uuid', $uuid)->where('user_id', auth()->id())->firstOrFail();

    return view('pembayaran.selesai', compact('pembayaran'));   // tampilkan status + polling ringan bila masih menunggu
}

Langkah 5: Terima dan Verifikasi Notifikasi

Midtrans mengirim HTTP POST JSON ke Payment Notification URL yang Anda atur di dasbor. Tanda tangannya dihitung sebagai SHA512(order_id + status_code + gross_amount + ServerKey).

// app/Http/Controllers/Webhooks/MidtransNotificationController.php
namespace App\Http\Controllers\Webhooks;

use App\Http\Controllers\Controller;
use App\Jobs\ProsesNotifikasiMidtrans;
use App\Models\WebhookCall;
use Illuminate\Database\UniqueConstraintViolationException;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class MidtransNotificationController extends Controller
{
    public function __invoke(Request $request)
    {
        $n = json_decode($request->getContent(), true) ?? [];

        foreach (['order_id', 'status_code', 'gross_amount', 'signature_key', 'transaction_status'] as $field) {
            if (! isset($n[$field])) {
                return response()->json(['message' => 'Payload tidak lengkap.'], 400);
            }
        }

        // gross_amount dipakai PERSIS seperti string yang diterima (mis. "50000.00")
        $expected = hash('sha512', $n['order_id'].$n['status_code'].$n['gross_amount'].config('services.midtrans.server_key'));

        if (! hash_equals($expected, (string) $n['signature_key'])) {
            Log::channel('security')->warning('midtrans.signature_tidak_valid', ['order_id' => $n['order_id'], 'ip' => $request->ip()]);
            return response()->json(['message' => 'Tanda tangan tidak valid.'], 401);
        }

        // Idempotensi: kombinasi order + status + waktu transaksi
        $eventId = implode(':', [$n['order_id'], $n['transaction_status'], $n['transaction_time'] ?? '', $n['status_code']]);

        try {
            $call = WebhookCall::create([
                'penyedia' => 'midtrans',
                'event_id' => mb_substr($eventId, 0, 120),
                'jenis'    => $n['transaction_status'],
                'headers'  => ['user-agent' => $request->userAgent()],
                'payload'  => $request->getContent(),
            ]);
        } catch (UniqueConstraintViolationException) {
            return response()->json(['message' => 'OK']);
        }

        ProsesNotifikasiMidtrans::dispatch($call->id)->onQueue('webhooks');

        return response()->json(['message' => 'OK']);          // 2xx: Midtrans tidak mengulang
    }
}
// routes/api.php
Route::post('webhooks/midtrans', \App\Http\Controllers\Webhooks\MidtransNotificationController::class)
    ->middleware('throttle:webhooks');

Atur URL https://rw.contoh.id/api/webhooks/midtrans di dasbor Midtrans (Settings → Configuration). URL harus dapat dijangkau publik melalui HTTPS, tidak di balik login atau VPN.

Midtrans menunggu respons hingga sekitar 15 detik dan mengulang notifikasi bila respons bukan 2xx. Karena itu endpoint hanya memverifikasi, menyimpan, dan men-dispatch job.

Langkah 6: Proses dan Konfirmasi Status

Dokumentasi Midtrans menyarankan notifikasi diproses secara idempoten, dan bila urutan notifikasi meragukan, memeriksa status terkini lewat Get Status API. Job berikut selalu mengonfirmasi ke API sebelum menandai pembayaran berhasil:

// app/Jobs/ProsesNotifikasiMidtrans.php
namespace App\Jobs;

use App\Enums\StatusPembayaran as S;
use App\Integrations\Midtrans\MidtransClient;
use App\Models\{Pembayaran, WebhookCall};
use App\Services\Pembayaran\TandaiPembayaran;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\DB;

class ProsesNotifikasiMidtrans implements ShouldQueue
{
    use Queueable;

    public int $tries = 5;
    public array $backoff = [30, 120, 600];

    public function __construct(public int $webhookCallId) {}

    public function handle(MidtransClient $midtrans, TandaiPembayaran $tandai): void
    {
        $call = WebhookCall::findOrFail($this->webhookCallId);
        $orderId = $call->data()['order_id'];

        $status = $midtrans->status($orderId);                  // sumber kebenaran terkini

        DB::transaction(function () use ($status, $orderId, $tandai) {
            $pembayaran = Pembayaran::where('referensi', $orderId)->lockForUpdate()->first();

            if (! $pembayaran) {
                return;                                          // bukan order dari aplikasi ini
            }

            if ((int) round((float) $status['gross_amount']) !== $pembayaran->jumlah) {
                throw new \RuntimeException("Jumlah tidak cocok untuk {$orderId}");
            }

            $baru = self::petakan($status);

            if ($baru === null || ! $pembayaran->status->bolehMenjadi($baru)) {
                $pembayaran->update(['respons_terakhir' => $status]);
                return;                                          // tidak ada perubahan yang sah
            }

            match ($baru) {
                S::Berhasil => $tandai->berhasil($pembayaran, $status),
                default     => $pembayaran->update(['status' => $baru, 'respons_terakhir' => $status]),
            };
        });

        $call->update(['status' => 'diproses', 'diproses_pada' => now()]);
    }

    /** Pemetaan status Midtrans → status internal */
    public static function petakan(array $s): ?S
    {
        $fraud = $s['fraud_status'] ?? 'accept';             // bila tidak ada, abaikan (dianggap accept)

        return match ($s['transaction_status']) {
            'settlement'               => S::Berhasil,
            'capture'                  => $fraud === 'accept' ? S::Berhasil : null,
            'pending', 'authorize'     => S::Menunggu,
            'deny', 'failure'          => S::Gagal,
            'expire'                   => S::Kedaluwarsa,
            'cancel'                   => S::Dibatalkan,
            'refund', 'partial_refund' => S::Dikembalikan,
            default                    => null,
        };
    }
}
// app/Services/Pembayaran/TandaiPembayaran.php
public function berhasil(Pembayaran $pembayaran, array $status): void
{
    $pembayaran->update([
        'status'       => StatusPembayaran::Berhasil,
        'metode'       => $status['payment_type'] ?? null,
        'gateway_transaction_id' => $status['transaction_id'] ?? null,
        'dibayar_pada' => isset($status['settlement_time'])
            ? Carbon::parse($status['settlement_time'], 'Asia/Jakarta')
            : now(),
        'respons_terakhir' => $status,
    ]);

    $pembayaran->iuran->catatPembayaran($pembayaran);         // update iuran + catat kas masuk

    PembayaranDiterima::dispatch($pembayaran);                // event: notifikasi warga, dasbor real-time
}

Ringkasan status Midtrans:

transaction_status Arti Status internal
settlement Dana sudah masuk Berhasil
capture + fraud_status: accept Kartu berhasil ditarik Berhasil
pending Menunggu pelanggan membayar Menunggu
deny Ditolak penyedia/deteksi fraud Gagal
expire Lewat batas waktu bayar Kedaluwarsa
cancel Dibatalkan Dibatalkan
failure Kesalahan tak terduga Gagal
refund / partial_refund Dikembalikan Dikembalikan

Karena semua efek samping (iuran lunas, kas masuk, notifikasi) terjadi di dalam TandaiPembayaran::berhasil() yang hanya dipanggil satu kali per pembayaran (dijaga mesin status dan kunci baris), notifikasi duplikat tidak bisa mencatat kas dua kali.

Langkah 7: Rekonsiliasi Terjadwal

Notifikasi bisa gagal sampai (server down saat itu, salah konfigurasi URL). Rekonsiliasi memeriksa pembayaran yang masih menunggu langsung ke API status.

// app/Console/Commands/RekonsiliasiPembayaran.php
protected $signature = 'pembayaran:rekonsiliasi';

public function handle(MidtransClient $midtrans): int
{
    Pembayaran::query()
        ->where('status', StatusPembayaran::Menunggu)
        ->where('created_at', '<', now()->subMinutes(10))      // beri waktu notifikasi datang dulu
        ->where('created_at', '>', now()->subDays(3))
        ->lazyById(100)
        ->each(function (Pembayaran $p) {
            $call = WebhookCall::create([
                'penyedia' => 'midtrans',
                'event_id' => 'rekonsiliasi:'.$p->referensi.':'.now()->format('YmdHi'),
                'jenis'    => 'rekonsiliasi',
                'headers'  => [],
                'payload'  => json_encode(['order_id' => $p->referensi]),
            ]);

            ProsesNotifikasiMidtrans::dispatch($call->id)->onQueue('webhooks');
        });

    // Pembayaran "dibuat" yang gagal mendapatkan token lebih dari 1 jam: tandai gagal
    Pembayaran::where('status', StatusPembayaran::Dibuat)->where('created_at', '<', now()->subHour())
        ->update(['status' => StatusPembayaran::Gagal]);

    return self::SUCCESS;
}
// routes/console.php
Schedule::command('pembayaran:rekonsiliasi')->everyFifteenMinutes()->onOneServer()->withoutOverlapping();

Job yang sama (ProsesNotifikasiMidtrans) dipakai untuk notifikasi dan rekonsiliasi, sehingga hanya ada satu jalur logika yang mengubah status pembayaran.

Lengkapi dengan rekonsiliasi keuangan harian: cocokkan total pembayaran berhasil di aplikasi dengan laporan settlement dari dasbor penyedia.

Langkah 8: Test

// tests/Feature/Pembayaran/MidtransTest.php
use Illuminate\Support\Facades\Http;

beforeEach(function () {
    config(['services.midtrans.server_key' => 'SB-Mid-server-uji']);
    Http::preventStrayRequests();
});

function notifikasi(array $data): array
{
    $data['signature_key'] = hash('sha512', $data['order_id'].$data['status_code'].$data['gross_amount'].'SB-Mid-server-uji');
    return $data;
}

it('membuat transaksi dengan jumlah dari server', function () {
    Http::fake(['app.sandbox.midtrans.com/*' => Http::response(['token' => 'tok-1', 'redirect_url' => 'https://...'], 201)]);
    [$warga, $iuran] = wargaDenganIuranBelumBayar(pokok: 50000);

    $this->actingAs($warga)->post("/iuran/{$iuran->id}/bayar", ['jumlah' => 500])   // jumlah dari klien diabaikan
        ->assertOk();

    Http::assertSent(fn ($r) => $r['transaction_details']['gross_amount'] === 50000
        && $r->hasHeader('Authorization', 'Basic '.base64_encode('SB-Mid-server-uji:')));
});

it('menolak notifikasi dengan tanda tangan salah', function () {
    $this->postJson('/api/webhooks/midtrans', [
        'order_id' => 'IUR-1-X', 'status_code' => '200', 'gross_amount' => '50000.00',
        'transaction_status' => 'settlement', 'signature_key' => 'palsu',
    ])->assertUnauthorized();
});

it('menandai berhasil setelah dikonfirmasi API status', function () {
    $p = Pembayaran::factory()->menunggu()->create(['referensi' => 'IUR-1-ABC', 'jumlah' => 50000]);
    Http::fake(['api.sandbox.midtrans.com/v2/IUR-1-ABC/status' => Http::response([
        'order_id' => 'IUR-1-ABC', 'transaction_status' => 'settlement', 'gross_amount' => '50000.00',
        'payment_type' => 'qris', 'transaction_id' => 'trx-1', 'settlement_time' => '2026-10-19 10:00:00',
    ])]);

    $this->postJson('/api/webhooks/midtrans', notifikasi([
        'order_id' => 'IUR-1-ABC', 'status_code' => '200', 'gross_amount' => '50000.00',
        'transaction_status' => 'settlement', 'transaction_time' => '2026-10-19 09:58:00',
    ]))->assertOk();

    expect($p->fresh()->status)->toBe(StatusPembayaran::Berhasil)
        ->and($p->iuran->fresh()->sudahLunas())->toBeTrue();
});

it('notifikasi pending yang terlambat tidak menurunkan status', function () {
    $p = Pembayaran::factory()->create(['referensi' => 'IUR-2-ABC', 'jumlah' => 50000, 'status' => 'berhasil']);
    Http::fake(['api.sandbox.midtrans.com/*' => Http::response([
        'order_id' => 'IUR-2-ABC', 'transaction_status' => 'pending', 'gross_amount' => '50000.00',
    ])]);

    $this->postJson('/api/webhooks/midtrans', notifikasi([
        'order_id' => 'IUR-2-ABC', 'status_code' => '201', 'gross_amount' => '50000.00', 'transaction_status' => 'pending',
    ]))->assertOk();

    expect($p->fresh()->status)->toBe(StatusPembayaran::Berhasil);
});

it('kas hanya tercatat sekali walau notifikasi settlement datang dua kali', function () {
    Pembayaran::factory()->menunggu()->create(['referensi' => 'IUR-3-ABC', 'jumlah' => 50000]);
    Http::fake(['api.sandbox.midtrans.com/*' => Http::response([
        'order_id' => 'IUR-3-ABC', 'transaction_status' => 'settlement', 'gross_amount' => '50000.00',
    ])]);

    $notif = notifikasi([
        'order_id' => 'IUR-3-ABC', 'status_code' => '200', 'gross_amount' => '50000.00',
        'transaction_status' => 'settlement', 'transaction_time' => '2026-10-19 09:58:00',
    ]);

    $this->postJson('/api/webhooks/midtrans', $notif)->assertOk();
    $this->postJson('/api/webhooks/midtrans', $notif)->assertOk();          // duplikat: diterima, tidak diproses ulang

    expect(TransaksiKas::where('sumber', 'iuran')->count())->toBe(1);
});

Uji di sandbox sebelum go-live: gunakan simulator pembayaran yang disediakan Midtrans untuk setiap metode yang Anda aktifkan (QRIS, VA, e-wallet), uji pembayaran sukses, kedaluwarsa, dan pembatalan, lalu pastikan notifikasi sampai ke staging melalui HTTPS.

Troubleshooting

Error / Gejala Penyebab Solusi
401 dari Snap API Server key salah atau tertukar sandbox/production Periksa kunci dan MIDTRANS_IS_PRODUCTION
400 saat membuat transaksi order_id dipakai ulang, atau total item_details ≠ gross_amount Referensi unik per percobaan; samakan jumlah
Tanda tangan notifikasi selalu salah gross_amount diubah ke integer sebelum di-hash, atau server key berbeda Pakai string gross_amount apa adanya
Notifikasi tidak pernah datang URL salah, bukan HTTPS publik, atau di balik autentikasi Atur URL di dasbor; uji dengan fitur kirim notifikasi uji
Iuran tercatat lunas tanpa pembayaran Mengandalkan redirect finish / onSuccess Status hanya diubah dari notifikasi + API status
Pembayaran "berhasil" kembali "menunggu" Status ditimpa tanpa aturan transisi Mesin status bolehMenjadi()
Pembayaran sah tetap "menunggu" Notifikasi hilang Rekonsiliasi terjadwal ke API status
Snap tidak muncul CSP memblokir skrip/frame Midtrans Izinkan domain penyedia di CSP

Best Practices

Keamanan

  • Server key hanya di server; client key saja yang boleh di frontend.
  • Jumlah tagihan selalu dihitung server.
  • Verifikasi tanda tangan notifikasi, lalu konfirmasi status lewat API sebelum menandai berhasil.
  • Validasi silang jumlah dan order_id dengan data internal.
  • Catat setiap perubahan status pembayaran ke activity log.

Performa

  • Endpoint notifikasi membalas cepat; pemrosesan di queue khusus.
  • Rekonsiliasi dibatasi rentang waktu dan dijalankan di satu server.
  • Pakai ulang pembayaran aktif agar tidak membuat transaksi berulang.

Maintainability

  • Pisahkan tagihan (iuran) dan percobaan pembayaran.
  • Satu jalur logika perubahan status untuk notifikasi dan rekonsiliasi.
  • Mesin status eksplisit dengan transisi yang diizinkan.
  • Semua efek samping keberhasilan di satu service, dipicu satu kali.
  • Simpan payload notifikasi mentah untuk audit dan investigasi selisih.

Related Articles

Last Tested

Komponen Versi
Laravel 13.x
PHP 8.4
Midtrans Snap API v1, Core API v2 (sandbox)
Redis 7.x
Pest 4.x
Tanggal 19 Oktober 2026

Bagikan artikel:

Artikel lainnya