Pakasir Payment Gateway

https://github.com/fadhila36/pakasir-sdk
Admin
A lightweight Laravel SDK for integrating Pakasir digital payment gateway with support for QRIS,...
Tokens:55,897
Snippets:356
Trust Score:7.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Validation and string conversion examples

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/enums.md

Example usage of tryFrom, validateAmount, and from for string conversion and validation.

```php
use Fadhila36\Pakasir\Enums\PaymentMethod;

// Konversi string kode ke enum (peka huruf kecil)
$method = PaymentMethod::tryFrom($request->input('payment_method'));
if ($method === null) {
    return response()->json(['message' => 'Metode pembayaran tidak valid'], 400);
}

// Validasi nominal manual (melempar InvalidArgumentException)
try {
    $method->validateAmount($amount);
} catch (\InvalidArgumentException $e) {
    return back()->withErrors(['amount' => $e->getMessage()]);
}

// Paksa dari value tertentu (lempar ValueError bila tidak ada)
$byValue = PaymentMethod::from('permata_va'); // PaymentMethod::PERMATA_VA
```

--------------------------------

### Fee calculation examples

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/enums.md

Example usage of calculateFee for various payment methods, showing expected outputs.

```php
use Fadhila36\Pakasir\Enums\PaymentMethod;

// QRIS: <= 105.000 → 0.7% + 310 ; > 105.000 → 1%
echo PaymentMethod::QRIS->calculateFee(10000);   // 380
echo PaymentMethod::QRIS->calculateFee(200000);  // 2000

// PayPal: 1% dengan minimum 3.000
echo PaymentMethod::PAYPAL->calculateFee(100000);  // 3000
echo PaymentMethod::PAYPAL->calculateFee(500000);  // 5000

// VA bank: flat 3.500
echo PaymentMethod::BNI_VA->calculateFee(100000);  // 3500
echo PaymentMethod::BRI_VA->calculateFee(50000);   // 3500

// VA lain: flat 2.000
echo PaymentMethod::SAMPOERNA_VA->calculateFee(100000); // 2000
```

--------------------------------

### Example .env configuration

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/configuration.md

Example environment variables for configuring the Pakasir SDK. Set PAKASIR_PROJECT, PAKASIR_API_KEY, PAKASIR_BASE_URL, PAKASIR_TIMEOUT, PAKASIR_RETRY_ATTEMPTS, PAKASIR_RETRY_DELAY, and PAKASIR_LOGGING_ENABLED in your .env file.

```env
PAKASIR_PROJECT=slug-proyek-anda
PAKASIR_API_KEY=api-key-rahasia-anda
PAKASIR_BASE_URL=https://app.pakasir.com/api
PAKASIR_TIMEOUT=30
PAKASIR_RETRY_ATTEMPTS=3
PAKASIR_RETRY_DELAY=100
PAKASIR_LOGGING_ENABLED=true
```

--------------------------------

### Facade usage example

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/laravel-integration.md

Shows how to use the Pakasir facade to create a payment with PERMATA_VA, catching ApiException for error handling.

```php
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Enums\PaymentMethod;
use Fadhila36\Pakasir\Exceptions\ApiException;

try {
    $transaction = Pakasir::createPayment(
        PaymentMethod::PERMATA_VA,
        'INV-FACADE-1',
        250000
    );
} catch (ApiException $e) {
    // e->getStatusCode() / e->getResponseBody()
}
```

--------------------------------

### Usage example with Pakasir detailPayment

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/data-objects.md

Example of fetching transaction details, checking if completed, updating an order, and caching the snapshot array. Uses cache() helper to store data for one hour.

```php
use Fadhila36\Pakasir\Facades\Pakasir;

$detail = Pakasir::detailPayment('INV-100', 50000);

if ($detail->isCompleted()) {
    // Berhasil — proses pesanan
    $order = Order::where('order_id', $detail->orderId)->first();
    $order->update(['paid_at' => $detail->completedAt]);
} else {
    // Masih pending / expired / canceled / failed / unknown
    $order->update(['last_status' => $detail->status->value]);
}

// Simpan snapshot ke cache sebagai array
cache()->put('pakasir:' . $detail->orderId, $detail->toArray(), now()->addHour());
```

--------------------------------

### Manual Instantiation of Pakasir Client

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/configuration.md

Example of manually creating a Pakasir client instance with custom options. Use this when not using the service provider, passing project, API key, base URL, and optional timeout, retry attempts, retry delay, and logging enabled. The example shows extending timeout for slow networks and enabling logging for debugging.

```php
use Fadhila36\Pakasir\Pakasir;

$client = new Pakasir(
    project: env('PAKASIR_PROJECT'),
    apiKey: env('PAKASIR_API_KEY'),
    baseUrl: env('PAKASIR_BASE_URL', 'https://app.pakasir.com/api'),
    timeout: 60,          // perpanjang untuk jaringan lambat
    retryAttempts: 5,
    retryDelay: 200,
    loggingEnabled: true  // aktifkan log untuk debugging
);
```

--------------------------------

### AuditWebhook listener example

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/events.md

Example listener that logs the received webhook payload to a 'webhook' channel, including order ID, amount, status, and payment method.

```php
// app/Listeners/AuditWebhook.php
use Fadhila36\Pakasir\Events\WebhookReceived;

public function handle(WebhookReceived $event): void
{
    $payload = $event->payload;

    Logger::channel('webhook')->info('Webhook Pakasir diterima', [
        'order_id' => $payload->orderId,
        'amount'   => $payload->amount,
        'status'   => $payload->status->value,
        'method'   => $payload->paymentMethod->value,
    ]);
}
```

--------------------------------

### Basic getPaymentData usage example

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Shows how to call getPaymentData with a QRIS payment method, order ID 'INV-1001', and amount 50000. The example outputs the payment URL, fee (660 for amounts <= 105000), and total payment (50660).

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

$data = Pakasir::getPaymentData(PaymentMethod::QRIS, 'INV-1001', 50000);

echo $data->paymentUrl;   // https://app.pakasir.com/pay/slug-proyek/50000?order_id=INV-1001&qris_only=1
echo $data->fee;          // 660 (0.7% + 310 untuk nominal <= 105.000)
echo $data->totalPayment; // 50660
```

--------------------------------

### Publish Pakasir Config File

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/docs/INTEGRATION.md

Publish the SDK configuration file so it can be edited. Run this after installation.

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

--------------------------------

### Install local package with composer require

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/docs/DEVELOPMENT.md

Install the package from the local source in development mode. With symlink:true, saved changes in the package folder are immediately reflected in the host application.

```bash
composer require fadhila36/pakasir-sdk @dev

```

--------------------------------

### Basic Usage

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/notifications.md

Shows how to create a payment transaction and send a PaymentLinkNotification to a notifiable user, including an example with a queue delay.

```APIDOC
## Basic Usage

### Description
Demonstrates creating a payment transaction and sending a PaymentLinkNotification to a user.

### Example
php
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Enums\PaymentMethod;
use Fadhila36\Pakasir\Notifications\PaymentLinkNotification;

// 1. Buat transaksi
$transaction = Pakasir::createPayment(
    PaymentMethod::QRIS,
    'INV-NOTIF-1',
    50000,
    'https://toko.com/checkout/success'
);

// 2. Kirim notifikasi ke user (model apa pun yang implements Notifiable)
$user->notify(new PaymentLinkNotification($transaction));

// Atau dengan queue delay
$user->notify((new PaymentLinkNotification($transaction))->delay(now()->addMinutes(5)));

```

--------------------------------

### PaymentCompleted listener example

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/events.md

Example listener that handles the PaymentCompleted event. It retrieves the order, checks a paid flag to process only once, updates the order status, and queues a receipt email.

```php
// app/Listeners/DeliverProduct.php
use Fadhila36\Pakasir\Events\PaymentCompleted;
use App\Models\Order;

public function handle(PaymentCompleted $event): void
{
    $detail = $event->response;

    $order = Order::with('items')->where('order_id', $detail->orderId)->firstOrFail();

    // Proses hanya sekali — cek flag
    if ($order->status === 'paid') {
        return;
    }

    $order->update([
        'status'       => 'paid',
        'completed_at' => $detail->completedAt,
    ]);

    // Kirim email resi / buka akses produk
    Mail::to($order->customer)->queue(new ReceiptMail($order));
}
```

--------------------------------

### Usage example for getPaymentUrl() and modern alternative

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Shows how to call getPaymentUrl() with PaymentMethod::QRIS and the modern alternative using getPaymentData() to access the paymentUrl property.

```php
use Fadhila36\Pakasir\Facades\Pakasir;

$url = Pakasir::getPaymentUrl(PaymentMethod::QRIS, 'INV-77', 50000);
// Alternatif modern:
$url = Pakasir::getPaymentData(PaymentMethod::QRIS, 'INV-77', 50000)->paymentUrl;
```

--------------------------------

### Install Pakasir SDK with Composer

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/docs/INTEGRATION.md

Install the Pakasir SDK into your Laravel project using Composer. Requires PHP 8.3+ and Laravel 11/12/13.

```bash
composer require fadhila36/pakasir-sdk
```

--------------------------------

### TransactionCanceled listener example

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/events.md

Example listener that handles the TransactionCanceled event. It updates the order status to canceled, records the stock release time, and echoes a confirmation message.

```php
// app/Listeners/ReleaseStock.php
use Fadhila36\Pakasir\Events\TransactionCanceled;

public function handle(TransactionCanceled $event): void
{
    $detail = $event->response;

    Order::where('order_id', $detail->orderId)->update([
        'status' => 'canceled',
        'stock_released_at' => now(),
    ]);

    echo "Transaksi {$detail->orderId} dibatalkan, stok dikembalikan.";
}
```

--------------------------------

### Event listener example for detailPayment()

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Shows how to register an event listener for the PaymentCompleted event in EventServiceProvider.php and handle the event to update the order status to 'paid' when the payment is completed.

```php
// app/Providers/EventServiceProvider.php
use Fadhila36\Pakasir\Events\PaymentCompleted;

protected $listen = [
    PaymentCompleted::class => [OrderPaidListener::class],
];

// Pendengar menangkap TransactionDetailResponse yang sudah dikonfirmasi selesai:
public function handle(PaymentCompleted $event): void
{
    $detail = $event->response; // TransactionDetailResponse
    Order::where('order_id', $detail->orderId)->update(['status' => 'paid']);
}
```

--------------------------------

### Usage example for TransactionCreated event

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/events.md

Shows how to register a listener for TransactionCreated in EventServiceProvider and handle it in a listener to send a payment link notification.

```php
// app/Providers/EventServiceProvider.php
use Fadhila36\Pakasir\Events\TransactionCreated;

protected $listen = [
    TransactionCreated::class => [NotifyCustomer::class],
];

// app/Listeners/NotifyCustomer.php
use Fadhila36\Pakasir\Events\TransactionCreated;

public function handle(TransactionCreated $event): void
{
    $transaction = $event->response; // TransactionCreateResponse

    // Contoh: kirim link pembayaran ke pelanggan via notifikasi bawaan SDK
    Order::where('order_id', $transaction->orderId)
        ->first()?->notify(new PaymentLinkNotification($transaction));
}
```

--------------------------------

### WebhookPayload usage example in Laravel event listener

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/data-objects.md

Example of handling a WebhookReceived event in Laravel 11+ with auto-discovery. Uses the WebhookPayload from the event to create an ActivityLog entry.

```php
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Events\WebhookReceived;

// Di laravel 11+: auto-discovery event
// app/Listeners/PakasirWebhookAudit.php
public function handle(WebhookReceived $event): void
{
    $payload = $event->payload; // WebhookPayload

    ActivityLog::create([
        'order_id' => $payload->orderId,
        'project'  => $payload->project,
        'amount'   => $payload->amount,
        'method'   => $payload->paymentMethod->value,
        'status'   => $payload->status->value,
        'data'     => $payload->toArray(),
    ]);
}
```

--------------------------------

### Basic usage of PaymentLinkNotification

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/notifications.md

Basic usage example: creates a payment transaction using Pakasir::createPayment with QRIS method, then sends a PaymentLinkNotification to a user. Also shows how to delay the notification using the delay() method.

```php
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Enums\PaymentMethod;
use Fadhila36\Pakasir\Notifications\PaymentLinkNotification;

// 1. Buat transaksi
$transaction = Pakasir::createPayment(
    PaymentMethod::QRIS,
    'INV-NOTIF-1',
    50000,
    'https://toko.com/checkout/success'
);

// 2. Kirim notifikasi ke user (model apa pun yang implements Notifiable)
$user->notify(new PaymentLinkNotification($transaction));

// Atau dengan queue delay
$user->notify((new PaymentLinkNotification($transaction))->delay(now()->addMinutes(5)));
```

--------------------------------

### getPaymentData with error handling and redirect

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Example using the facade with a BNI VA payment method, order ID 'INV-1002', amount 250000, and a redirect URL. Includes try-catch for InvalidArgumentException when order ID is too short, method is invalid, or amount is below minimum.

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

try {
    $data = Pakasir::getPaymentData('bni_va', 'INV-1002', 250000, 'https://toko.com/order/INV-1002');

    // amount 250000 > 105000, fee QRIS = 1% (tapi ini VA BNI: fee tetap 3500)
    echo $data->totalPayment; // 253500
} catch (\InvalidArgumentException $e) {
    // order ID terlalu pendek, metode tidak valid, atau nominal di bawah minimum
    report($e);
}
```

--------------------------------

### Handling paymentNumber from server for VA

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/data-objects.md

Demonstrates handling a Virtual Account payment where the server returns a payment number. The example checks if paymentNumber is not null before displaying the VA number to the buyer.

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

// Untuk VA, server mengembalikan nomor virtual account pada kunci 'payment' (lihat endpoints.md)
$va = Pakasir::createPayment(PaymentMethod::BNI_VA, 'INV-VA-9', 250000);

if ($va->paymentNumber !== null) {
    // Tampilkan nomor VA ke pembeli
    echo "Bayar ke rekening VA: {$va->paymentNumber}";
}
```

--------------------------------

### GET {baseUrl}/transactiondetail

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/endpoints.md

Mengambil detail/status transaksi. Dipanggil oleh Pakasir::detailPayment(), juga internal dari cancelPayment(), simulationPayment(), dan verifyWebhook().

```APIDOC
## GET {baseUrl}/transactiondetail

### Description
Mengambil detail/status transaksi. Dipanggil oleh `Pakasir::detailPayment()` (source: `src/Pakasir.php:292-307`), juga internal dari `cancelPayment()`, `simulationPayment()`, dan `verifyWebhook()`.

### Method
GET

### Endpoint
`{baseUrl}/transactiondetail`

### Parameters
#### Query Parameters
- **project** (string) - Required - Slug proyek SDK.
- **amount** (int) - Required - Nominal `(int) $amount`.
- **order_id** (string) - Required - ID transaksi.
- **api_key** (string) - Required - API key rahasia.

### Response
#### Success Response (2xx)
- **project** (string) - Slug proyek, fallback project SDK.
- **order_id** (string) - ID transaksi, fallback argumen `$orderId`.
- **amount** (int) - Nominal, fallback argumen `$amount`.
- **fee** (int) - Fee, fallback `null` bila absen.
- **total_payment** (int) - Total tagihan, fallback `null` bila absen.
- **payment_method** (string) - Kode metode, fallback `PaymentMethod::ALL` bila tak dikenal.
- **status** (string) - `pending` | `completed` | `expired` | `canceled` | `failed` | `unknown`, fallback `TransactionStatus::PENDING`.
- **payment_url** (string) - URL pembayaran, fallback `null`.
- **payment_number** (string) - Kode QRIS / nomor VA, fallback `null`.
- **completed_at** (string) - Waktu selesai, fallback `null`.
- **expired_at** (string) - Batas waktu, fallback `null`.

#### Response Example
```json
{
  "project": "slug-proyek",
  "order_id": "INV-1001",
  "amount": 50000,
  "fee": 2500,
  "total_payment": 52500,
  "payment_method": "qris",
  "status": "completed",
  "payment_url": "https://app.pakasir.com/pay/123",
  "payment_number": "1234567890",
  "completed_at": "2025-01-01T00:00:00Z",
  "expired_at": "2025-01-02T00:00:00Z"
}
```

### Error Handling
- **2xx**: Sukses.
- **Selain itu**: `ApiException` berpesan `'Pakasir Check Error: {body}'`.
```

--------------------------------

### Basic usage of QRISHelper::isValid()

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/support.md

Example of using isValid() with a scanned QRIS payload. If valid, the code proceeds with payment processing.

```php
use Fadhila36\Pakasir\Support\QRISHelper;

$scanned = '00020101021226610016ID.CO.SHOPEE.WWW01189360091800216005230208216005230303UME51440014ID.CO.QRIS.WWW0215ID10243228429300303UME5204792953033605409100003.005802ID5907Pakasir6012KAB. KEBUMEN61055439262230519SP25RZRATEQI2HQ65Q46304A079';

if (QRISHelper::isValid($scanned)) {
    // lanjut proses pembayaran QRIS
}
```

--------------------------------

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

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Mengambil status terkini sebuah transaksi langsung dari server Pakasir via HTTP GET. Mengirim GET {baseUrl}/transactiondetail dengan query ['project', 'amount', 'order_id', 'api_key']. Jika gagal, melempar ApiException. Mengembalikan TransactionDetailResponse DTO.

```APIDOC
## [GET] /transactiondetail

### Description
Mengambil status terkini sebuah transaksi langsung dari server Pakasir via HTTP GET.

### Method
GET

### Endpoint
{baseUrl}/transactiondetail

### Parameters
#### Query Parameters
- **project** (string) - Required - Proyek (dari konfigurasi SDK).
- **amount** (int) - Required - Nominal tagihan; di-cast ke `int`.
- **order_id** (string) - Required - ID transaksi (dibersihkan via `sanitizeUrlSafe()`).
- **api_key** (string) - Required - Kunci API.

### Request Example
```
GET /transactiondetail?project=...&amount=50000&order_id=INV-1001&api_key=...
```

### Response
#### Success Response (200)
- **project** (string) - Proyek.
- **orderId** (string) - ID transaksi.
- **amount** (int) - Nominal tagihan.
- **fee** (?int) - Biaya (jika ada).
- **totalPayment** (?int) - Total pembayaran (jika ada).
- **paymentMethod** (PaymentMethod) - Metode pembayaran.
- **status** (TransactionStatus) - Status transaksi.
- **paymentUrl** (string) - URL pembayaran.
- **paymentNumber** (string) - Nomor pembayaran.
- **completedAt** (string) - Waktu selesai.
- **expiredAt** (string) - Waktu kedaluwarsa.

#### Response Example
```json
{
  "project": "project-name",
  "orderId": "INV-1001",
  "amount": 50000,
  "fee": 2500,
  "totalPayment": 52500,
  "paymentMethod": "bank_transfer",
  "status": "pending",
  "paymentUrl": "https://...",
  "paymentNumber": "1234567890",
  "completedAt": null,
  "expiredAt": "2024-12-31 23:59:59"
}
```

### Error Handling
- **ApiException** - HTTP request gagal. Pesan: `'Pakasir Check Error: {body}'`.
```

--------------------------------

### Resolve Pakasir from container

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/laravel-integration.md

Shows how to resolve the Pakasir client from the Laravel container, either via constructor injection (recommended for unit tests) or manually using app(). The example then calls getPaymentData with sample arguments.

```php
use Fadhila36\Pakasir\Contracts\PakasirInterface;

// Injectable di constructor (disarankan untuk unit test)
public function __construct(protected PakasirInterface $pakasir) {}

// Atau resolve manual
$client = app(PakasirInterface::class);
$client = app('pakasir');

$data = $client->getPaymentData('qris', 'INV-50', 50000);
```

--------------------------------

### PaymentLinkNotification with error handling

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/notifications.md

Example with error handling: creates a payment using BNI_VA method, sends notification, and catches ApiException to log the error and return a user-friendly error message.

```php
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Enums\PaymentMethod;
use Fadhila36\Pakasir\Exceptions\ApiException;
use Fadhila36\Pakasir\Notifications\PaymentLinkNotification;

public function purchase(Request $request)
{
    try {
        $transaction = Pakasir::createPayment(PaymentMethod::BNI_VA, 'INV-NOTIF-2', 250000);

        $request->user()->notify(new PaymentLinkNotification($transaction));

        return back()->with('success', 'Tagihan terbit. Cek email Anda untuk tautan pembayaran.');
    } catch (ApiException $e) {
        // Gagal membuat transaksi/notifikasi — jangan sampai user bingung
        Log::error('Gagal membuat tagihan: ' . $e->getMessage());

        return back()->withErrors(['payment' => 'Gagal memproses pembayaran, coba lagi.']);
    }
}
```

--------------------------------

### PaymentController checkout with Pakasir::createPayment

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/docs/INTEGRATION.md

Example PaymentController with a checkout method that validates input, retrieves the product price from the database (never from the request), creates a pending transaction, calls Pakasir::createPayment with an enum, and returns the payment URL. Uses a database transaction with rollback on error and logs exceptions without exposing details to the user.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use App\Models\Product;     // Model Produk Anda
use App\Models\Transaction; // Model Transaksi Anda
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Enums\PaymentMethod;

class PaymentController extends Controller
{
    public function checkout(Request $request)
    {
        // 1. Validasi Input
        $request->validate([
            'product_id' => 'required|exists:products,id',
            'payment_method' => 'required|string', 
        ]);

        // Gunakan Database Transaction agar data konsisten (Rollback jika gagal)
        DB::beginTransaction();

        try {
            // 2. AMBIL HARGA DARI DATABASE (Critical Security)
            // Jangan gunakan $request->price, user bisa memanipulasinya!
            $product = Product::findOrFail($request->product_id);
            
            // Validasi Metode Pembayaran menggunakan Enum
            $methodEnum = PaymentMethod::tryFrom($request->payment_method);
            if (!$methodEnum) {
                return response()->json(['message' => 'Metode pembayaran tidak valid'], 400);
            }

            // Generate No Invoice Unik
            $orderId = 'INV-' . time() . rand(100, 999);

            // 3. Simpan Transaksi 'Pending' di Database Lokal
            $transaction = Transaction::create([
                'order_id'       => $orderId,
                'product_id'     => $product->id,
                'amount'         => $product->price, // Harga asli dari DB
                'payment_method' => $methodEnum->value,
                'status'         => 'pending',
            ]);

            // 4. Request ke Pakasir API
            // Kita pakai Enum agar type-safe & otomatis validasi amount
            $response = Pakasir::createPayment(
                $methodEnum,
                $transaction->order_id,
                $transaction->amount
            );

            DB::commit(); // Simpan permanen

            // 5. Kirim data ke Frontend (berisi URL pembayaran)
            return response()->json([
                'status'  => 'success',
                'message' => 'Silahkan lakukan pembayaran',
                'data'    => [
                    'order_id'       => $orderId,
                    'amount'         => $transaction->amount,
                    'payment_detail' => $response, // Berisi 'payment_url' & 'payment_number' (VA)
                ]
            ]);

        } catch (\Exception $e) {
            DB::rollBack(); // Batalkan semua simpanan DB jika error
            
            // Log error untuk developer, jangan tampilkan error detail ke user
            \Log::error('Pakasir Error: ' . $e->getMessage());

            return response()->json(['message' => 'Gagal memproses pembayaran'], 500);
        }
    }
}
```

--------------------------------

### Combined usage of clean() and isValid()

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/support.md

Example showing how to clean a raw QRIS payload with clean() and then validate it with isValid(). If valid, the cleaned payload is saved to the database; otherwise, a 422 error is returned.

```php
use Fadhila36\Pakasir\Support\QRISHelper;

$raw = "  0002010102122661...  ";

$cleanPayload = QRISHelper::clean($raw); // '0002010102122661...'

if (QRISHelper::isValid($cleanPayload)) {
    // Simpan versi bersih ke database
    DB::table('qris_payments')->insert(['payload' => $cleanPayload]);
} else {
    // Tolak: bukan QRIS EMVCo
    abort(422, 'QRIS tidak valid');
}
```

--------------------------------

### Combined Example: Catch All SDK Errors in Laravel Controller

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/errors.md

Use this snippet in a Laravel controller method to handle all SDK exceptions during payment creation. It catches InvalidArgumentException for input validation, ApiException for server issues, and PakasirException as a fallback, returning appropriate JSON responses.

```php
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Exceptions\ApiException;
use Fadhila36\Pakasir\Exceptions\PakasirException;
use Fadhila36\Pakasir\Exceptions\WebhookValidationException;
use Fadhila36\Pakasir\Enums\PaymentMethod;

public function checkout()
{
    try {
        $transaction = Pakasir::createPayment(PaymentMethod::QRIS, 'INV-1001', 50000);
    } catch (InvalidArgumentException $e) {
        return response()->json(['message' => 'Input tidak valid: ' . $e->getMessage()], 422);
    } catch (ApiException $e) {
        return response()->json(['message' => 'Server Pakasir bermasalah', 'code' => $e->getStatusCode()], 502);
    } catch (PakasirException $e) {
        // Cadangan: exception SDK lain
        return response()->json(['message' => 'Terjadi kesalahan'], 500);
    }
}
```

--------------------------------

### Catch ApiException with status and response body

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/errors.md

Example of catching ApiException to access HTTP status code and raw response body. Uses Pakasir::createPayment() with PaymentMethod::QRIS, logs the error, and returns a JSON 502 response.

```php
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Enums\PaymentMethod;
use Fadhila36\Pakasir\Exceptions\ApiException;

try {
    Pakasir::createPayment(PaymentMethod::QRIS, 'INV-500', 50000);
} catch (ApiException $e) {
    $status = $e->getStatusCode();       // ?int — status HTTP
    $body   = $e->getResponseBody();     // ?string — respons mentah server

    Log::error("Pakasir API gagal ({$status})", ['body' => $body]);

    return response()->json(['message' => 'Pembayaran gagal diproses'], 502);
}
```

--------------------------------

### boot() method in PakasirServiceProvider

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/laravel-integration.md

Publishes the package configuration file to the host application. Only runs when the application is running in the console, as checked by runningInConsole().

```php
public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->publishes([
            __DIR__.'/../config/pakasir.php' => config_path('pakasir.php'),
        ], 'config');
    }
}
```

--------------------------------

### Constructor

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Menginisialisasi instance Pakasir dengan konfigurasi proyek, API key, base URL, dan opsi retry/logging.

```APIDOC
## Constructor

### Description
Menginisialisasi instance Pakasir dengan konfigurasi proyek, API key, base URL, dan opsi retry/logging.

### Method
Constructor

### Endpoint
`new Pakasir($project, $apiKey, $baseUrl, $timeout = 30, $retryAttempts = 3, $retryDelay = 100, $loggingEnabled = false)`

### Parameters
#### Constructor Parameters
- **$project** (string) - Required - Slug/ID proyek Pakasir Anda (dari dashboard Pakasir).
- **$apiKey** (string) - Required - API key rahasia proyek Pakasir.
- **$baseUrl** (string) - Required - Base URL API Pakasir. Nilai trailing slash (`/`) otomatis dihapus via `rtrim($baseUrl, '/')`.
- **$timeout** (int) - Optional - Timeout request HTTP dalam detik, diteruskan ke `Http::timeout()`. Default: `30`.
- **$retryAttempts** (int) - Optional - Jumlah percobaan ulang otomatis saat request gagal, diteruskan ke `Http::retry()`. Default: `3`.
- **$retryDelay** (int) - Optional - Jeda antar percobaan ulang dalam milidetik. Default: `100`.
- **$loggingEnabled** (bool) - Optional - Bila `true`, request dan respons API dicatat ke log Laravel. Default: `false`.

### Request Example
```php
use Fadhila36\Pakasir\Pakasir;

$client = new Pakasir(
    project: 'slug-proyek-anda',
    apiKey: 'api-key-rahasia',
    baseUrl: 'https://app.pakasir.com/api',
    timeout: 30,
    retryAttempts: 3,
    retryDelay: 100,
    loggingEnabled: true
);
```

### Response
#### Success Response
- Instance `Pakasir` yang dikonfigurasi.

#### Response Example
Tidak ada respons spesifik; konstruktor mengembalikan instance kelas.
```

--------------------------------

### Contoh isi config/pakasir.php (host)

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/configuration.md

Contoh file konfigurasi yang diedit langsung di aplikasi host. Nilai env tetap menimpa kunci di file config selama memakai env() di dalamnya; mergeConfigFrom di register() memastikan kunci paket tersedia bahkan sebelum publish.

```php
// config/pakasir.php (host)
return [
    'project'   => 'slug-proyek-staging',
    'api_key'   => 'key-staging',
    'base_url'  => 'https://staging.pakasir.com/api',
    'logging_enabled' => true,
];
```

--------------------------------

### POST {baseUrl}/paymentsimulation

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/endpoints.md

Menjalankan simulasi pembayaran sukses (mode sandbox/testing). Dipanggil oleh Pakasir::simulationPayment().

```APIDOC
## POST {baseUrl}/paymentsimulation

### Description
Menjalankan simulasi pembayaran sukses (mode sandbox/testing). Dipanggil oleh `Pakasir::simulationPayment()` (source: `src/Pakasir.php:197-207`).

### Method
POST

### Endpoint
`{baseUrl}/paymentsimulation`

### Parameters
#### Request Body
- **project** (string) - Required - Slug proyek SDK.
- **order_id** (string) - Required - ID transaksi.
- **amount** (int) - Required - Nominal tagihan.
- **api_key** (string) - Required - API key rahasia.

### Request Example
```json
{
  "project": "slug-proyek",
  "order_id": "INV-1001",
  "amount": 50000,
  "api_key": "rahasia"
}
```

### Response
#### Success Response (2xx)
- Konten tidak diparsing; SDK lalu memanggil `transactiondetail` dan mengembalikan hasilnya (status menjadi `completed` bila simulasi berhasil).

### Error Handling
- **2xx**: Sukses.
- **Selain itu**: `ApiException` berpesan `'Pakasir Simulation Error: {body}'`.
```

--------------------------------

### Pakasir::getPaymentUrl

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/laravel-integration.md

Gets the payment URL for the given payment method and order details. Returns a string.

```APIDOC
## Pakasir::getPaymentUrl

### Description
Gets the payment URL for the given payment method and order details.

### Method
Static method

### Signature
`getPaymentUrl(string|PaymentMethod $paymentMethod, string $orderId, int|float $amount, ?string $redirectUrl = null): string`

### Parameters
- **$paymentMethod** (string|PaymentMethod) - Required - The payment method to use.
- **$orderId** (string) - Required - The unique order identifier.
- **$amount** (int|float) - Required - The transaction amount.
- **$redirectUrl** (?string) - Optional - The URL to redirect to after payment.

### Return Value
`string`
```

--------------------------------

### Recommended directory structure for local development

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/docs/DEVELOPMENT.md

Recommended directory layout for local development, placing the package repository and the Laravel host application under a common parent directory.

```text
/Workplace/
├── pakasir-sdk/       (Repositori Package ini)
└── laravel-playground/ (Aplikasi Laravel untuk testing)

```

--------------------------------

### Contoh Instansiasi Pakasir

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Contoh pembuatan instance Pakasir secara manual dengan parameter yang ditentukan. Dalam aplikasi Laravel, instansiasi manual tidak diperlukan karena instance di-bind sebagai singleton oleh PakasirServiceProvider dan diakses melalui Facade.

```php
use Fadhila36\Pakasir\Pakasir;

$client = new Pakasir(
    project: 'slug-proyek-anda',
    apiKey: 'api-key-rahasia',
    baseUrl: 'https://app.pakasir.com/api',
    timeout: 30,
    retryAttempts: 3,
    retryDelay: 100,
    loggingEnabled: true
);
```

--------------------------------

### Catch PakasirException with try-catch

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/errors.md

Example of catching PakasirException to handle both ApiException and WebhookValidationException in one block. Uses Pakasir::detailPayment() as the operation that may throw.

```php
use Fadhila36\Pakasir\Exceptions\PakasirException;

try {
    Pakasir::detailPayment('INV-100', 50000);
} catch (PakasirException $e) {
    // Menangkap ApiException DAN WebhookValidationException sekaligus
    report($e);
}
```

--------------------------------

### Basic createPayment() usage with QRIS

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/pakasir.md

Shows how to create a QRIS payment transaction using the Pakasir facade and PaymentMethod enum. Outputs the payment URL, payment number, and total payment including fee.

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

$transaction = Pakasir::createPayment(
    paymentMethod: PaymentMethod::QRIS,
    orderId: 'INV-' . time(),
    amount: 50000,
    redirectUrl: 'https://toko.com/invoice/complete'
);

echo $transaction->paymentUrl;    // tautan pembayaran QRIS
echo $transaction->paymentNumber; // kode QRIS / nomor VA dari server (nullable)
echo $transaction->totalPayment;  // 50000 + fee
```

--------------------------------

### Set up webhook route in routes/api.php

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/docs/INTEGRATION.md

Define the POST endpoint that Pakasir will call to notify about payment status changes.

```php
use App\Http\Controllers\WebhookController;

Route::post('/webhooks/pakasir', [WebhookController::class, 'handle']);
```

--------------------------------

### QRISHelper::isValid()

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/support.md

Checks whether a given string is a valid QRIS payload according to the EMVCo standard by verifying it starts with '000201' after trimming whitespace.

```APIDOC
## `isValid()`

### Description
Memeriksa apakah string merupakan payload QRIS yang valid menurut standar EMVCo.

### Method
`public static function isValid(string $payload): bool`

### Parameters
- `$payload` (string) - Required - String payload QRIS mentah (mis. hasil scan QRIS atau `paymentNumber` dari API).

### Return
`bool` — `true` bila string (setelah `trim()`) diawali dengan `'000201'` (Payload Format Indicator standar EMVCo); `false` jika tidak.

### Example
```php
use Fadhila36\Pakasir\Support\QRISHelper;

$scanned = '00020101021226610016ID.CO.SHOPEE.WWW01189360091800216005230208216005230303UME51440014ID.CO.QRIS.WWW0215ID10243228429300303UME5204792953033605409100003.005802ID5907Pakasir6012KAB. KEBUMEN61055439262230519SP25RZRATEQI2HQ65Q46304A079';

if (QRISHelper::isValid($scanned)) {
    // lanjut proses pembayaran QRIS
}
```
```

--------------------------------

### Using TransactionCreateResponse with createPayment()

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/data-objects.md

Shows how to create a payment with QRIS, access type-safe properties, convert to an array for JSON/logging, and restore from an array using fromArray(). The paymentNumber may be null, so use the null coalescing operator.

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

$transaction = Pakasir::createPayment(PaymentMethod::QRIS, 'INV-100', 50000);

// Akses properti type-safe
echo $transaction->totalPayment;   // int
echo $transaction->paymentUrl;     // string
echo $transaction->paymentNumber ?? 'belum tersedia';

// Konversi ke array (mis. untuk respons JSON / simpan log)
$array = $transaction->toArray();
// ['project' => ..., 'order_id' => 'INV-100', ..., 'status' => 'pending']

// Konversi dari array (mis. dari cache / DB)
$restored = \Fadhila36\Pakasir\DataObjects\TransactionCreateResponse::fromArray($array);
```

--------------------------------

### isValid() method signature

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/support.md

Public static method that checks if a string is a valid QRIS payload by verifying it starts with '000201' after trimming. Returns true if valid, false otherwise.

```php
public static function isValid(string $payload): bool
```

--------------------------------

### Menggabungkan PaymentMethod dan TransactionStatus dalam transaksi

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/enums.md

Gunakan pola ini untuk membuat transaksi dengan PaymentMethod::QRIS dan memantau statusnya melalui TransactionStatus. Contoh ini mengasumsikan Anda telah mengimpor kelas yang diperlukan dan memanggil metode Pakasir::createPayment() dan Pakasir::detailPayment(). Status yang mungkin adalah PENDING, COMPLETED, EXPIRED, CANCELED, FAILED, dan UNKNOWN.

```php
use Fadhila36\Pakasir\Facades\Pakasir;
use Fadhila36\Pakasir\Enums\PaymentMethod;
use Fadhila36\Pakasir\Enums\TransactionStatus;

// Buat transaksi, lalu pantau statusnya
$created = Pakasir::createPayment(PaymentMethod::QRIS, 'INV-PAIR-1', 50000);

$current = Pakasir::detailPayment($created->orderId, $created->amount);

assert($current->paymentMethod === PaymentMethod::QRIS);
assert(in_array($current->status, [
    TransactionStatus::PENDING,
    TransactionStatus::COMPLETED,
    TransactionStatus::EXPIRED,
    TransactionStatus::CANCELED,
    TransactionStatus::FAILED,
    TransactionStatus::UNKNOWN,
], true));
```

--------------------------------

### GET /api/transactiondetail

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/endpoints.md

Retrieves details of a specific payment transaction. Requires project and API key as query parameters. Called by the SDK's detailPayment() method and also used internally.

```APIDOC
## GET /api/transactiondetail

### Description
Retrieves details of a specific payment transaction. Requires project and API key as query parameters. Called by the SDK's detailPayment() method and also used internally.

### Method
GET

### Endpoint
/api/transactiondetail

### Parameters
#### Query Parameters
- **project** (string) - Required - The project identifier
- **api_key** (string) - Required - The API key for authentication

### Response
#### Success Response (200)
- **transaction_id** (string) - The unique identifier of the transaction
- **status** (string) - The status of the transaction

#### Response Example
{
  "transaction_id": "txn_123456",
  "status": "completed"
}

### Error Handling
- **ApiException** - Thrown with message 'Pakasir Check Error: {body}' when the API returns an error.
```

--------------------------------

### Handling invalid input with QRISHelper::isValid()

Source: https://github.com/fadhila36/pakasir-sdk/blob/main/_autodocs/api-reference/support.md

Example of using isValid() in a controller to validate a QRIS payload from a request. Returns a 422 JSON response if invalid, otherwise returns a success response.

```php
use Fadhila36\Pakasir\Support\QRISHelper;

public function confirmQrisPayment(Request $request)
{
    $payload = (string) $request->input('qris_payload');

    if (! QRISHelper::isValid($payload)) {
        return response()->json(['message' => 'Payload QRIS tidak valid'], 422);
    }

    return response()->json(['status' => 'valid']);
}
```
Tokens:
Raw