Getting Started

Minimal Setup

Installation:

composer require melipayamak/laravel

Publish the config file:

php artisan vendor:publish --provider="Melipayamak\Laravel\MelipayamakServiceProvider"

Configuration: Update .env with your Melipayamak credentials:

MELIPAYAMAK_KEY=your_api_key
MELIPAYAMAK_SECRET=your_api_secret
MELIPAYAMAK_SANDBOX=true # Set to false for production

First Use Case: Initialize the client in a service or controller:

use Melipayamak\Laravel\Facades\Melipayamak;

$client = Melipayamak::client();

Implementation Patterns

Common Workflows

Creating a Payment:

$payment = $client->payment()->create([
    'amount' => 100.00,
    'currency' => 'TRY',
    'card' => [
        'number' => '4242424242424242',
        'exp_month' => 12,
        'exp_year' => 2025,
        'cvc' => '123'
    ],
    'customer' => [
        'name' => 'John Doe',
        'email' => 'john@example.com',
        'identity_number' => '12345678901'
    ]
]);

Retrieving a Payment:

$payment = $client->payment()->find($paymentId);

Refunding a Payment:

$refund = $client->refund()->create($paymentId, [
    'amount' => 50.00
]);

Webhook Handling:

Define a route in routes/web.php:

Route::post('/melipayamak/webhook', [PaymentController::class, 'handleWebhook']);

Process webhooks in a controller:

public function handleWebhook(Request $request) {
    $event = $request->input('event');
    $data = $request->input('data');

    // Validate and handle the event (e.g., payment success, failure)
    if ($event === 'payment.succeeded') {
        // Update your database or send notifications
    }
}

Integration with Laravel Jobs:

use Melipayamak\Laravel\Jobs\CreatePaymentJob;

// Dispatch a job for asynchronous payment processing
CreatePaymentJob::dispatch($paymentData);

Integration Tips

Use Facades for Cleaner Code: Prefer Melipayamak::client()->payment()->create() over instantiating the client directly in controllers.

Leverage Laravel’s HTTP Client: For custom API calls, use Laravel’s HTTP client with the Melipayamak base URL:

$response = Http::withHeaders([
    'Authorization' => 'Bearer ' . $client->getAccessToken(),
])->post('https://api.melipayamak.com/v1/payments', $data);

Logging: Enable logging in config/melipayamak.php to debug API responses:
```
'log' => [
    'enabled' => true,
    'channel' => 'single',
],
```

Testing: Use the sandbox mode (MELIPAYAMAK_SANDBOX=true) for testing. Example test payment card:

'card' => [
    'number' => '4242424242424242', // Test card number
    'exp_month' => 12,
    'exp_year' => 2025,
    'cvc' => '123'
]

Gotchas and Tips

Pitfalls

Deprecated Package:
- The last release was in 2019, so ensure compatibility with Laravel’s latest versions (e.g., 8/9/10). Test thoroughly, especially if using newer Laravel features like named route model binding or HTTP tests.
Missing Documentation:
- The package lacks detailed docs. Refer to Melipayamak’s official API docs for undocumented endpoints or edge cases.

Webhook Verification:

Always verify webhook signatures to avoid spoofing attacks. The package doesn’t include built-in verification, so implement it manually:

use Illuminate\Support\Facades\Http;

public function handleWebhook(Request $request) {
    $payload = $request->getContent();
    $signature = $request->header('X-Melipayamak-Signature');

    // Reconstruct the expected signature
    $expectedSignature = hash_hmac(
        'sha256',
        $payload,
        config('melipayamak.secret')
    );

    if (!hash_equals($expectedSignature, $signature)) {
        abort(403, 'Invalid signature');
    }
    // Process the webhook
}

Rate Limiting:

Melipayamak’s API may throttle requests. Implement exponential backoff in your code:

use Illuminate\Support\Facades\Http;

try {
    $response = Http::retry(3, 100)->post($url, $data);
} catch (\Illuminate\Http\Client\ConnectionException $e) {
    // Handle rate limiting or connection errors
}

Currency and Amount Validation:
- Validate amount (e.g., ensure it’s a multiple of the smallest currency unit, like 0.01 TRY) and currency (e.g., TRY, USD) before sending requests to avoid API errors.

Debugging Tips

Enable Debug Mode: Set 'debug' => true in config/melipayamak.php to log raw API requests/responses.
Check API Status: Verify the API endpoint (https://api.melipayamak.com) is reachable and not down:
```
curl -v https://api.melipayamak.com/v1/payments
```
Test with Postman: Manually test API endpoints using Postman with the same payloads to isolate issues.
Common Errors:
- Invalid API Key: Double-check MELIPAYAMAK_KEY and MELIPAYAMAK_SECRET in .env.
- Card Declined: Use test cards for sandbox mode (e.g., 4242424242424242 for success).
- Amount Too Low/High: Ensure amount is within Melipayamak’s supported limits (e.g., min/max per transaction).

Extension Points

Custom API Client: Extend the package by creating a custom client class:

namespace App\Services;

use Melipayamak\Laravel\Client;

class CustomMelipayamakClient extends Client {
    public function customEndpoint($data) {
        return $this->post('/custom-endpoint', $data);
    }
}

Add Middleware: Attach middleware to the HTTP client for logging, retries, or auth:

$client = Melipayamak::client();
$client->middleware->push(
    \Illuminate\Http\Middleware\TransformJson::class
);

Event Dispatching: Trigger Laravel events for payment status changes:
```
event(new PaymentSucceeded($payment));
```

Localization: Override error messages or responses for multilingual support:

$client->on('error', function ($response) {
    throw new \Exception(__('payment.failed', ['message' => $response->error]));
});

Laravel Laravel Package