Getting Started

Minimal Setup

Installation

composer require alsharie/jawali-payment

Publish the config file:

php artisan vendor:publish --provider="Alsharie\JawaliPayment\JawaliPaymentServiceProvider" --tag="config"

Configuration Edit .env with your Jawali API credentials:

JAWALI_API_KEY=your_api_key_here
JAWALI_API_SECRET=your_api_secret_here
JAWALI_ENVIRONMENT=sandbox # or 'live'

First Use Case: Create a Payment Intent

use Alsharie\JawaliPayment\Facades\JawaliPayment;

$intent = JawaliPayment::createPaymentIntent([
    'amount' => 100.00, // in SAR
    'currency' => 'SAR',
    'description' => 'Order #12345',
    'metadata' => ['order_id' => '12345'],
]);

return redirect()->to($intent->payment_url);

Key Files to Review

Config: config/jawali-payment.php (API endpoints, default settings).
Facade: app/Facades/JawaliPayment.php (if extended).
Service Provider: vendor/alsharie/jawali-payment/src/JawaliPaymentServiceProvider.php (for custom bindings).

Implementation Patterns

Common Workflows

1. Payment Processing

Create Intent:

$intent = JawaliPayment::createPaymentIntent($request->all());

Handle Webhook (e.g., in routes/web.php):

Route::post('/jawali-webhook', [PaymentWebhookController::class, 'handle']);

// PaymentWebhookController.php
public function handle(Request $request) {
    $event = JawaliPayment::verifyWebhook($request->all());
    // Process event (e.g., update order status)
}

2. Subscription Management

Create Subscription:

$subscription = JawaliPayment::createSubscription([
    'customer_id' => $customer->jawali_id,
    'items' => [['price_id' => 'price_123']],
]);

Cancel Subscription:

JawaliPayment::cancelSubscription($subscription->id);

3. Refunds and Disputes

Refund a Payment:

JawaliPayment::createRefund($payment->id, ['amount' => 50.00]);

Dispute Handling:

$dispute = JawaliPayment::createDispute($charge->id, ['amount' => 100.00, 'reason' => 'fraudulent']);

4. Customer Management

Create/Update Customer:

$customer = JawaliPayment::createCustomer([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'phone' => '+966551234567',
]);

Attach to Order:

$order->customer()->attach($customer->id);

Integration Tips

Laravel Ecosystem

Use Events: Listen to Jawali webhooks and trigger Laravel events:
```
event(new PaymentSucceeded($intent->id, $intent->amount));
```

Queue Webhook Processing:

Queue::push(new ProcessJawaliWebhook($event));

Service Layer Pattern:

// app/Services/PaymentService.php
public function processPayment(Order $order) {
    $intent = JawaliPayment::createPaymentIntent($order->toJawaliArray());
    return $intent;
}

Testing

Use the sandbox environment for testing:
```
JAWALI_ENVIRONMENT=sandbox
```

Mock the facade in tests:

JawaliPayment::shouldReceive('createPaymentIntent')->andReturn($mockIntent);

Logging

Enable debug logging in config/jawali-payment.php:

'debug' => env('JAWALI_DEBUG', false),

View logs in storage/logs/laravel.log.

Gotchas and Tips

Pitfalls

Webhook Verification
- Always verify webhook signatures to avoid spoofing:
```
$event = JawaliPayment::verifyWebhook($request->all(), $request->get('signature'));
```
- Use JAWALI_WEBHOOK_SECRET in .env for local testing.
Currency and Amount
- Jawali expects amounts in halalas (smallest unit, e.g., 100.00 SAR = 10000 halalas).
- Fix: Multiply by 100 when passing amounts:
```
'amount' => $order->total * 100,
```

Idempotency Keys

Use idempotency keys for retries to avoid duplicate charges:

JawaliPayment::createPaymentIntent($data, ['idempotency_key' => uniqid()]);

Rate Limits

Jawali enforces rate limits. Cache responses for non-idempotent operations:

$customer = Cache::remember("jawali_customer_{$user->id}", now()->addHours(1), function() use ($user) {
    return JawaliPayment::createCustomer($user->toJawaliArray());
});

Error Handling

Jawali returns HTTP errors (e.g., 402 for insufficient funds). Handle gracefully:

try {
    $intent = JawaliPayment::createPaymentIntent($data);
} catch (\Alsharie\JawaliPayment\Exceptions\JawaliException $e) {
    return back()->withError($e->getMessage());
}

Debugging Tips

Enable Debug Mode Set JAWALI_DEBUG=true in .env to log raw API responses.
Test with Sandbox Use Jawali’s sandbox tester to simulate payments.

Check Headers Ensure Authorization and Content-Type headers are set:

$response = Http::withHeaders([
    'Authorization' => 'Bearer ' . config('jawali.api_key'),
    'Content-Type' => 'application/json',
])->post('https://api.jawali.com/v1/payment_intents', $data);

Common Errors
- invalid_request_error: Validate required fields (e.g., currency, amount).
- authentication_error: Verify JAWALI_API_KEY and JAWALI_API_SECRET.
- resource_missing: Ensure the customer/subscription exists before acting on it.

Extension Points

Custom Facade Extend the facade to add domain-specific methods:

// app/Facades/ExtendedJawaliPayment.php
class ExtendedJawaliPayment extends JawaliPayment {
    public function createOrderPayment(Order $order) {
        return parent::createPaymentIntent($order->toJawaliArray());
    }
}

Middleware for API Calls Add middleware to log or transform requests:

// app/Http/Middleware/JawaliRequestMiddleware.php
public function handle($request, Closure $next) {
    if ($request->routeIs('jawali.*')) {
        // Modify request data
    }
    return $next($request);
}

Custom Webhook Handlers Route webhooks to specific handlers:

// routes/web.php
Route::post('/jawali-webhook', function (Request $request) {
    $event = JawaliPayment::verifyWebhook($request->all());
    app()->call([\App\Handlers\WebhookHandlers::class, $event->type], ['event' => $event]);
});

Local Overrides Override API endpoints in config:

'endpoints' => [
    'api' => env('JAWALI_API_URL', 'https://api.jawali.com'),
    'webhook' => env('JAWALI_WEBHOOK_URL', 'https://your-app.com/jawali-webhook'),
],

Testing Helpers Add test helpers to app/Helpers/JawaliTestHelper.php:

function mockJawaliResponse($status, $data = []) {
    JawaliPayment::shouldReceive('createPaymentIntent')
        ->andReturn((object) ['id' => 'pi_12

Jawali Payment Laravel Package