---
name: midtrans-laravel
description: |
  Panduan lengkap integrasi Midtrans Payment Gateway (Snap) ke project Laravel. Gunakan skill ini setiap kali user menyebut Midtrans, payment gateway, integrasi pembayaran, Snap token, webhook Midtrans, subscription checkout, atau ingin menambahkan fitur pembayaran di Laravel — bahkan jika user hanya bertanya "bagaimana cara terima pembayaran di Laravel" atau "setup payment gateway Indonesia". Skill ini mencakup instalasi, konfigurasi, migrasi database, model, controller checkout, controller webhook, routes, frontend (web & mobile), pengujian di sandbox, checklist production, dan penyesuaian untuk berbagai jenis aplikasi (SaaS, e-commerce, donasi).
---

# Skill: Integrasi Midtrans Payment Gateway (Laravel)

Skill ini memandu implementasi **Midtrans Snap** untuk sistem pembayaran di Laravel — cocok untuk subscription, e-commerce, atau donasi.

## Alur Kerja

```
Client → POST /api/subscription/checkout → Snap token dibuat → DB disimpan
Client membayar di Snap UI
Midtrans → POST /api/midtrans/webhook → verifikasi signature → aktifkan subscription
```

---

## Langkah Implementasi

Ikuti urutan di bawah. Untuk detail kode lengkap setiap langkah, baca file referensi sesuai petunjuk.

### 1. Instalasi Package

```bash
composer require midtrans/midtrans-php
```

### 2. Konfigurasi

Buat `.env` dan `config/midtrans.php`, lalu boot di `AppServiceProvider`.
→ Lihat: `references/01-config.md`

### 3. Database Migration

Dua opsi:
- **Opsi A**: Tambah kolom ke tabel `user_subscriptions` yang sudah ada
- **Opsi B**: Buat tabel `payment_orders` terpisah (**direkomendasikan** untuk audit trail)

→ Lihat: `references/02-migration-and-model.md`

### 4. Model PaymentOrder

→ Lihat: `references/02-migration-and-model.md`

### 5. Controller Checkout (buat Snap token)

→ Lihat: `references/03-checkout-controller.md`

### 6. Controller Webhook (terima notifikasi Midtrans)

Penting: verifikasi signature wajib dilakukan sebelum proses apapun.
→ Lihat: `references/04-webhook-controller.md`

### 7. Routes

```php
// Webhook harus publik (Midtrans tidak pakai token auth)
Route::post('/midtrans/webhook', [MidtransWebhookController::class, 'handle']);

Route::middleware('auth:sanctum')->group(function () {
    Route::post('/subscription/checkout', [PaymentController::class, 'checkout']);
    Route::get('/subscription/order/{orderId}', [PaymentController::class, 'orderStatus']); // opsional
});
```

Kecualikan webhook dari CSRF:
```php
$middleware->validateCsrfTokens(except: ['api/midtrans/webhook']);
```

### 8. Frontend

→ Lihat: `references/05-frontend-and-testing.md`

---

## Checklist Sebelum Production

- [ ] `MIDTRANS_IS_PRODUCTION=true` + ganti ke server/client key production
- [ ] Daftarkan URL webhook production di Midtrans Dashboard → Settings → Configuration
- [ ] Pastikan HTTPS aktif (wajib di production)
- [ ] Tambahkan **idempotency check** di webhook (jangan proses ulang order yang sudah `settlement`)
- [ ] Simpan `midtrans_payload` untuk audit trail
- [ ] Tambahkan logging/alerting saat signature verification gagal

### Idempotency (penting!)

```php
if ($order->status === 'settlement') {
    return response('Already processed', 200);
}
```

---

## Penyesuaian per Jenis Aplikasi

| Jenis Aplikasi | Yang Perlu Diubah |
|---|---|
| SaaS subscription | Sesuaikan `activateSubscription()` dengan model subscription project |
| E-commerce | Tambahkan `item_details` produk + `shipping_address` |
| Donasi | Isi `item_details` dengan nama campaign |
| Multi-currency | Tambahkan `currency` di `transaction_details` |
| Custom expiry bayar | Tambahkan `expiry` di params Snap |

---

## Referensi

- [Midtrans Snap Docs](https://docs.midtrans.com/reference/snap-api)
- [Midtrans PHP SDK](https://github.com/midtrans/midtrans-php)
- [Sandbox Dashboard](https://dashboard.sandbox.midtrans.com)
- [Production Dashboard](https://dashboard.midtrans.com)