Getting Started

Minimal Setup

Installation

composer require spiderwebtr/payment-kit
php artisan vendor:publish --tag=payment-kit
php artisan migrate

Verify the payment-kit table exists in your database.

First Use Case: Creating a Payment

use Spiderwebtr\PaymentKit\Facades\PaymentKit;

$payment = PaymentKit::create([
    'amount' => 1000, // in cents
    'currency' => 'TRY',
    'description' => 'Product Purchase',
    'payment_method' => 'sipay', // or 'param', 'iyzico', etc.
    'callback_url' => route('payment.callback'),
    'success_url' => route('payment.success'),
    'fail_url' => route('payment.fail'),
]);

// Redirect to payment gateway
return redirect()->to($payment->getRedirectUrl());

Testing Locally
- Access the dashboard at /payment-kit (if APP_ENV=local).
- Use the test cards provided in the dashboard to simulate payments.

Implementation Patterns

Core Workflows

1. Payment Creation & Processing

Dynamic Provider Selection Use the payment_method parameter to switch between providers (e.g., sipay, iyzico). Example:
```
$payment = PaymentKit::create([
    'payment_method' => request('provider') ?? 'sipay',
    // ...
]);
```
3D Secure Flow For 3D Secure payments, the package handles the redirect and callback automatically. Ensure your callback_url is publicly accessible.
```
$payment = PaymentKit::create([
    'is_3d_secure' => true,
    // ...
]);
```

2. Webhook/Callback Handling

Define a route for payment callbacks (e.g., payment.callback).

Use the PaymentKit::handleCallback() method to process incoming webhooks:

public function handleCallback(Request $request)
{
    $result = PaymentKit::handleCallback($request);
    return response()->json($result);
}

Validate the callback signature using the PAYMENT_KIT_WEBHOOK_SECRET in your .env.

3. Dashboard Integration

Livewire Dashboard: The package includes a built-in dashboard at /payment-kit. Customize it by extending the PaymentKitController or overriding views in resources/views/vendor/payment-kit.
Data Export: Use the PaymentKit::getPayments() method to fetch payments for reporting:
```
$payments = PaymentKit::getPayments()->latest()->take(100)->get();
```

4. Testing Payments

Use the test mode for all providers by setting PAYMENT_KIT_TEST_MODE=true.
Test cards are provider-specific (e.g., 4242 4242 4242 4242 for Sipay, 4111 1111 1111 1111 for Iyzico).
Simulate 3D Secure flows via the dashboard’s test tools.

Integration Tips

Laravel Ecosystem

Livewire: The dashboard is built with Livewire. Extend it by creating a custom Livewire component that interacts with PaymentKit:

use Spiderwebtr\PaymentKit\Facades\PaymentKit;

public function mount()
{
    $this->payments = PaymentKit::getPayments()->latest()->paginate(10);
}

Horizon/Pulse: Monitor payment jobs by publishing the PaymentKitServiceProvider and configuring Horizon to listen for PaymentProcessed events.

Custom Providers

Extend the package by creating a custom provider. Override the Spiderwebtr\PaymentKit\Contracts\PaymentGateway contract:

namespace App\Providers;

use Spiderwebtr\PaymentKit\Contracts\PaymentGateway;

class CustomGateway implements PaymentGateway
{
    public function createPayment(array $data): array
    {
        // Custom logic for your payment provider
    }

    // Implement other required methods
}

Frontend Integration

Use the PaymentKit::getPaymentForm() method to generate a payment form dynamically:
```
$form = PaymentKit::getPaymentForm($paymentId);
echo $form->render();
```
For SPAs or JavaScript-heavy apps, use the getRedirectUrl() method to handle redirects via JavaScript:
```
window.location.href = "{{ $payment->getRedirectUrl() }}";
```

Gotchas and Tips

Pitfalls

Callback URL Mismatch
- Ensure your callback_url matches the URL used in the payment creation. Mismatches will cause webhook failures.
- Fix: Use absolute URLs (e.g., https://yourdomain.com/payment/callback) and verify the domain in config/payment-kit.php.
Test Mode vs. Live Mode
- Forgetting to toggle PAYMENT_KIT_TEST_MODE can lead to real transactions being processed.
- Fix: Always set PAYMENT_KIT_TEST_MODE=true in .env during development.
3D Secure Redirects
- If the 3D Secure flow fails silently, check:
  - The success_url and fail_url are accessible.
  - The callback_url is correctly configured to handle 3D Secure redirects.
- Fix: Test 3D Secure flows in the dashboard first.
Livewire Dashboard Conflicts
- If the dashboard doesn’t load, ensure:
  - Livewire 3.5+ is installed.
  - No JavaScript errors are blocking Livewire’s hydration.
- Fix: Clear your cache (php artisan view:clear) and check browser console logs.
Payment Gateway Timeouts
- Some providers (e.g., TurkPOS) have strict timeout requirements.
- Fix: Increase the PAYMENT_KIT_TIMEOUT in .env (default: 30 seconds).

Debugging

Enable Logging Add this to config/payment-kit.php to log all payment requests/responses:
```
'log_enabled' => env('PAYMENT_KIT_LOG_ENABLED', true),
```
Logs are stored in storage/logs/payment-kit.log.

Webhook Debugging Use Laravel’s tape package to inspect incoming webhook payloads:

composer require spatie/laravel-tape
php artisan tape:play storage/logs/laravel.log --grep="payment_callback"

SQL Queries Enable Laravel’s query logging to debug payment record issues:

DB::enableQueryLog();
$payment = PaymentKit::create([...]);
dd(DB::getQueryLog());

Configuration Quirks

Gateway-Specific Settings Each provider may require additional configuration. Check the config/payment-kit.php file for provider-specific keys (e.g., iyzico_api_key, sipay_store_id). Example:
```
'gateways' => [
    'iyzico' => [
        'api_key' => env('IYZICO_API_KEY'),
        'secret_key' => env('IYZICO_SECRET_KEY'),
    ],
],
```
Currency and Amount Validation The package validates that amount is in cents (e.g., 1000 for 10.00 TRY). Ensure your input matches this format. Fix: Use bcdiv() or number_format() to convert amounts:
```
$amount = (int) round(10.00 * 100); // 1000
```
Locale-Specific Issues
- Turkish locale (tr) may cause issues with number formatting (e.g., 1.000,00 vs. 1000.00).
- Fix: Set the locale explicitly in your payment creation:
```
$payment = PaymentKit::create([
    'amount' => 1000,
    'currency' => 'TRY',
    'locale' => 'en_US', // Force English locale
]);
```

Extension Points

Custom Payment Statuses Extend the payment_status column by adding a status_details JSON column to the payment-kit table:
```
Schema::table('payment-kit', function (Blueprint $table) {
    $table->json('status_details')->nullable();
});
```
Update the Payment model to handle this field.
Event Listeners Listen for payment events (e.g., PaymentCreated, PaymentProcessed) to trigger custom logic:
```
use Spiderwebtr\PaymentKit\Events\PaymentProcess
```

Payment Kit Laravel Package