Getting Started

Minimal Setup

Installation

composer require fadhila36/pakasir-sdk

Publish the config file:

php artisan vendor:publish --provider="Fadhila36\PakasirSdk\PakasirServiceProvider" --tag="pakasir-sdk-config"

Configure .env Add Pakasir credentials:

PAKASIR_SECRET_KEY=your_secret_key_here
PAKASIR_BASE_URL=https://api.pakasir.com

First Use Case: Create a Payment

use Fadhila36\PakasirSdk\Pakasir;
use Fadhila36\PakasirSdk\Requests\CreatePaymentRequest;

$payment = Pakasir::createPayment(
    new CreatePaymentRequest(
        id: 'order_123',
        amount: 100000,
        currency: 'IDR',
        description: 'Premium Subscription',
        customer: [
            'name' => 'John Doe',
            'email' => 'john@example.com',
        ],
        payment_method: 'QRIS', // or 'VA_BNI', 'VA_BRI', etc.
    )
);

Verify Webhook Add a route to handle Pakasir webhooks:
```
Route::post('/pakasir/webhook', [PakasirWebhookController::class, 'handle']);
```
Ensure PAKASIR_WEBHOOK_SECRET is set in .env for verification.

Implementation Patterns

Core Workflows

1. Payment Creation & Flow

Frontend: Generate a payment link/QR code or redirect to Pakasir’s payment page.

$payment = Pakasir::createPayment($request);
return redirect()->to($payment->getPaymentUrl());

Backend: Store the payment_id in your database for tracking.
```
$payment->getId(); // e.g., 'pay_abc123'
```

2. Payment Verification

Polling: Check payment status periodically.

$payment = Pakasir::getPayment($paymentId);
if ($payment->getStatus() === 'SUCCESS') {
    // Fulfill order
}

Webhook-Driven: Prefer webhooks for real-time updates. Validate the signature:

use Fadhila36\PakasirSdk\Webhook\PakasirWebhook;

$webhook = PakasirWebhook::validateAndParse(
    request()->getContent(),
    request()->header('X-Pakasir-Signature')
);

3. Refunds & Disputes

Initiate a refund:

Pakasir::createRefund(
    $paymentId,
    new CreateRefundRequest(amount: 50000, reason: 'Customer dispute')
);

4. Virtual Account (VA) Management

Generate a VA for multi-bank transfers:

$vaPayment = Pakasir::createPayment($request->withPaymentMethod('VA_BNI'));
$vaNumber = $vaPayment->getVirtualAccountNumber(); // e.g., '1234567890'

Integration Tips

Database Schema

Extend your payments table with:

Schema::create('payments', function (Blueprint $table) {
    $table->id();
    $table->string('pakasir_payment_id')->unique();
    $table->string('status'); // 'PENDING', 'SUCCESS', 'FAILED', etc.
    $table->json('metadata');
    $table->timestamps();
});

Event-Driven Architecture

Listen to Pakasir events (e.g., PaymentSucceeded):

use Fadhila36\PakasirSdk\Events\PaymentSucceeded;

event(new PaymentSucceeded($payment));

protected $listen = [
    PaymentSucceeded::class => [
        HandleSuccessfulPayment::class,
    ],
];

Testing

Use the SDK’s test mode:

PAKASIR_ENVIRONMENT=test

Mock webhooks in tests:

$this->post('/pakasir/webhook', $payload, [
    'HTTP_X_PAKASIR_SIGNATURE' => $signature,
]);

Gotchas and Tips

Pitfalls

Webhook Signature Mismatch
- Issue: Webhook requests fail validation due to incorrect PAKASIR_WEBHOOK_SECRET.
- Fix: Regenerate the secret in Pakasir’s dashboard and update .env.
```
php artisan config:clear
```
Idempotency Keys
- Issue: Duplicate payments if the same idempotency_key is reused.
- Fix: Use UUIDs or timestamps for uniqueness:
```
$request->withIdempotencyKey(Uuid::generate());
```
Currency & Amount Precision
- Issue: Rounding errors in amount (e.g., 100000.0001).
- Fix: Use integers (e.g., 100000 for IDR) and validate in the request DTO.
Timeouts & Retries
- Issue: API timeouts during peak hours.
- Fix: Configure retry logic in config/pakasir.php:
```
'retry' => [
    'max_attempts' => 3,
    'delay' => 1000, // ms
],
```

Debugging

Enable Logging Set PAKASIR_LOG_ENABLED=true in .env to log API requests/responses to storage/logs/pakasir.log.

Inspect Raw Responses Use the debug() method to dump raw API responses:

$payment = Pakasir::createPayment($request);
$payment->debug(); // Outputs raw response

Common HTTP Errors
- 401 Unauthorized: Invalid PAKASIR_SECRET_KEY.
- 403 Forbidden: IP restrictions or sandbox vs. production mismatch.
- 429 Too Many Requests: Exceed rate limits; implement exponential backoff.

Extension Points

Custom Payment Methods Extend the PaymentMethod enum or create a decorator:

use Fadhila36\PakasirSdk\Enums\PaymentMethod;

class CustomPaymentMethod extends PaymentMethod
{
    public const CUSTOM_BANK = 'VA_CUSTOM_BANK';
}

Override API Client Bind a custom HTTP client (e.g., Guzzle with middleware):

$client = new \GuzzleHttp\Client([
    'timeout' => 30,
    'headers' => ['User-Agent' => 'MyApp/1.0'],
]);

$this->app->bind(\Fadhila36\PakasirSdk\Contracts\Client::class, function () use ($client) {
    return new \Fadhila36\PakasirSdk\Clients\GuzzleClient($client);
});

Add Custom Fields Extend the CreatePaymentRequest DTO:

class ExtendedPaymentRequest extends CreatePaymentRequest
{
    public function __construct(
        public ?string $custom_field = null,
        // ... other fields
    ) {}
}

Localization Override translation strings in resources/lang/vendor/pakasir.php:

return [
    'payment_methods' => [
        'QRIS' => 'Scan QRIS',
        'VA_BNI' => 'Transfer BNI VA',
    ],
];

Configuration Quirks

Environment-Specific Settings Use config/pakasir.php to switch between sandbox/production:

'environments' => [
    'test' => [
        'base_url' => 'https://sandbox.pakasir.com',
    ],
    'production' => [
        'base_url' => 'https://api.pakasir.com',
    ],
],

Fee Calculation Fees are auto-calculated, but override in the request:

$request->withFee(
    amount: 1000, // Fixed fee
    percentage: 0.01, // 1% dynamic fee
);

Webhook Retries Configure failed webhook retries:

'webhook' => [
    'retry_after_minutes' => 5,
    'max_retries

Pakasir Sdk Laravel Package