README

Sebuah SDK Laravel modern, modular, dan type-safe untuk mengintegrasikan layanan gerbang pembayaran (payment gateway) Pakasir ke aplikasi Anda.

SDK ini mendukung QRIS, Virtual Account multi-bank (BNI, BRI, CIMB, Permata, dll), serta PayPal dengan kalkulasi biaya (fee) otomatis, timeout/retry otomatis, logging, Laravel Events, dan sistem verifikasi Webhook terproteksi.

⚡ Fitur Unggulan

• Laravel 13+ & PHP 8.3+ Ready dengan standard strict typing (declare(strict_types=1)).
• Data Transfer Objects (DTO): Semua respons API dipetakan secara type-safe ke objek DTO untuk autocompletion penuh di IDE Anda.
• Webhook Spoofing Protection: Metode verifyWebhook() secara otomatis memverifikasi payload dan melakukan double-check query langsung ke server Pakasir.
• Enterprise Connection Handling: Konfigurasi timeout, retry attempts, dan delay secara otomatis pada koneksi API.
• Laravel Events Support: Trigger event seperti TransactionCreated, PaymentCompleted, TransactionCanceled, dan WebhookReceived secara instan.
• Out-of-the-box Notifications: Kirim tagihan tautan pembayaran menggunakan Laravel Notification dengan template siap pakai.

📦 Instalasi

Pastikan server Anda menggunakan PHP 8.3+ dan aplikasi Anda berbasis Laravel 11.0 s/d 13.0+.

Jalankan perintah Composer berikut untuk menginstal:

composer require fadhila36/pakasir-sdk

🛠️ Konfigurasi

1. Publikasikan file konfigurasi package ke aplikasi host Anda:

php artisan vendor:publish --provider="Fadhila36\Pakasir\PakasirServiceProvider" --tag="config"

1. Atur kredensial proyek Pakasir Anda di file .env:

PAKASIR_PROJECT=slug-proyek-anda
PAKASIR_API_KEY=api-key-rahasia-anda
PAKASIR_TIMEOUT=30
PAKASIR_RETRY_ATTEMPTS=3
PAKASIR_LOGGING_ENABLED=true

🚀 Penggunaan Cepat

1. Membuat Transaksi Pembayaran

Gunakan PaymentMethod Enum untuk kenyamanan autocompletion dan validasi otomatis:

use Fadhila36\Pakasir\Enums\PaymentMethod;
use Fadhila36\Pakasir\Facades\Pakasir;

// Membuat transaksi QRIS secara instan
$transaction = Pakasir::createPayment(
    paymentMethod: PaymentMethod::QRIS, 
    orderId: 'INV-' . time(), 
    amount: 50000, 
    redirectUrl: 'https://websitekamu.com/invoice/complete' // Opsional
);

// Respon berupa DTO yang type-safe & IDE Friendly
echo $transaction->paymentUrl;     // Tautan ke pembayaran
echo $transaction->paymentNumber;  // Kode QRIS atau nomor VA
echo $transaction->totalPayment;   // Nominal + Fee

2. Memproses & Memverifikasi Webhook Secara Aman

Untuk menghindari eksploitasi webhook palsu, gunakan fitur verifyWebhook() yang akan memvalidasi data dan memverifikasi langsung ke server resmi Pakasir:

use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Exceptions\WebhookValidationException;

public function handleWebhook(Request $request)
{
    try {
        // Ambil nominal tagihan asli dari database Anda
        $expectedAmount = $order->amount; 

        // Verifikasi & Double-Check ke server Pakasir secara otomatis
        $webhookData = Pakasir::verifyWebhook($request->all(), $expectedAmount);

        // Jika lolos verifikasi, ubah status transaksi di DB Anda
        $order->update([
            'status' => $webhookData->status->value, // e.g., 'completed'
            'completed_at' => $webhookData->completedAt,
        ]);

        return response()->json(['status' => 'ok']);
    } catch (WebhookValidationException $e) {
        // Log & tolak jika webhook mencurigakan atau tidak valid
        return response()->json(['message' => $e->getMessage()], 400);
    }
}

💰 Pilihan Metode Pembayaran (PaymentMethod)

SDK menyediakan Enum lengkap dengan kalkulasi biaya (fee) dan validasi nominal minimum terintegrasi:

📖 API Reference

1. createPayment()

Membuat transaksi baru secara realtime di server Pakasir.

Pakasir::createPayment(
    string|PaymentMethod $paymentMethod,
    string $orderId,
    int|float $amount,
    ?string $redirectUrl = null
): TransactionCreateResponse;

2. detailPayment()

Mengambil status detail transaksi terkini dari server Pakasir.

Pakasir::detailPayment(string $orderId, int|float $amount): TransactionDetailResponse;

3. cancelPayment()

Membatalkan tagihan transaksi yang sedang aktif/pending.

Pakasir::cancelPayment(string $orderId, int|float $amount): TransactionDetailResponse;

4. simulationPayment()

Melakukan simulasi pembayaran sukses (khusus mode Sandbox/testing).

Pakasir::simulationPayment(string $orderId, int|float $amount): TransactionDetailResponse;

5. verifyWebhook()

Memparse dan memvalidasi keabsahan data webhook masukan.

Pakasir::verifyWebhook(array $payload, int|float $expectedAmount): WebhookPayload;

📜 Lisensi

Didistribusikan di bawah lisensi MIT License. Lihat dokumen LICENSE untuk informasi lebih lanjut.