amirkateb / payment-core-client

v1.0.0 2026-10-05 08:32 UTC

Requires

• php: >=7.4
• guzzlehttp/guzzle: ^7.2
• illuminate/contracts: ^8.0|^9.0|^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0|^13.0

proprietary

Published on Packagist.org on 2026-10-05 08:34 UTC

README

کلاینت رسمی PHP/Laravel برای Payment Platform مرکزی AvazTek. این SDK برای Laravel 8 تا 13 طراحی شده و تمام درخواست‌ها را با HMAC، timestamp و nonce امضا می‌کند.

نصب

composer require amirkateb/payment-core-client
php artisan vendor:publish --tag=payment-core-config

.env:

PAYMENT_CORE_URL=https://avaztek.ir
PAYMENT_CORE_KEY_ID=pay_live_xxxxxxxxxxxxxxxxxxxxxxxx
PAYMENT_CORE_SECRET=paysec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Secret را فقط در سمت سرور نگه دارید و هرگز در JavaScript، HTML یا مخزن Git قرار ندهید.

ایجاد پرداخت

use Avaztek\PaymentCore\PaymentClient;

$client = app(PaymentClient::class);
$response = $client->createTransaction([
    'order_id' => (string) $order->id,
    'amount' => 250000,
    'currency' => 'IRT',
    'description' => 'پرداخت سفارش #'.$order->id,
    'customer' => [
        'name' => $order->customer_name,
        'email' => $order->customer_email,
        'mobile' => $order->customer_mobile,
    ],
    'return_url' => route('payments.return'),
    'metadata' => ['cart_id' => $order->cart_id],
]);

return redirect()->away($response['transaction']['checkout_url']);

کاربر در Checkout مرکزی بین درگاه‌های فعال و مجاز برای همان مبلغ انتخاب می‌کند.

استعلام امن نتیجه

پارامترهای صفحه بازگشت فقط برای UX هستند. برای تصمیم مالی همیشه تراکنش را server-to-server استعلام کنید:

$result = $client->transaction(request('payment_id'));
if (($result['transaction']['status'] ?? null) === 'paid') {
    // fulfil order idempotently
}

Webhook

هدرهای webhook:

• X-Payment-Event
• X-Payment-Timestamp
• X-Payment-Signature

$raw = $request->getContent();
$valid = $client->verifyWebhook(
    $request->header('X-Payment-Timestamp'),
    $request->header('X-Payment-Event'),
    $raw,
    $request->header('X-Payment-Signature')
);
abort_unless($valid, 401);

Webhook handler باید idempotent باشد؛ event_id را ذخیره کنید و یک event را دوبار اعمال نکنید.

Laravel 8–13

Auto-discovery فعال است. در تمام نسخه‌های Laravel 8 تا 13 می‌توانید PaymentClient را dependency-inject کنید یا از Facade PaymentCore استفاده کنید.

خطاها

تمام خطاهای HTTP/تنظیمات با Avaztek\PaymentCore\Exceptions\PaymentCoreException پرتاب می‌شوند. statusCode() و responseBody() برای logging امن قابل استفاده‌اند؛ Secret را log نکنید.