محاسبه کارمزد تراکنش (Fee Calculation)

متد feeCalculation به شما امکان می‌دهد تا قبل از ایجاد درخواست پرداخت، میزان کارمزد یک تراکنش را محاسبه و دریافت کنید. این متد زمانی مفید است که بخواهید کارمزد تراکنش را پیش از شروع فرآیند پرداخت به کاربر نمایش دهید یا در محاسبات خود لحاظ کنید.

پارامترهای ارسالی به متد FeeCalculation

در جدول زیر پارامترهای ارسالی به متد feeCalculation و توضیحات مربوط به آن‌ها آورده شده است:

نام پارامتر	نوع	الزامی	توضیحات
merchant_id	String	بله	کد Merchant شما که توسط زرین‌پال اختصاص داده شده است.
amount	Integer	بله	مبلغ تراکنش به ریال که باید بیشتر از 1000 ریال باشد.
currency	String	خیر	نوع ارز تراکنش (پیش‌فرض: IRR). مقادیر مجاز: IRR, IRT

مقادیر بازگشتی از متد FeeCalculation

در جدول زیر پارامترهای بازگشتی از متد feeCalculation توضیح داده شده است:

نام پارامتر	نوع	توضیحات
code	Integer	کد وضعیت درخواست: کد 100 برای درخواست موفق.
message	String	پیام وضعیت درخواست، مانند موفقیت‌آمیز بودن محاسبه کارمزد.
amount	Integer	مبلغ اصلی تراکنش به ریال.
fee	Integer	میزان کارمزد محاسبه شده به ریال.
fee_type	String	نوع پرداخت کننده کارمزد: Merchant (پذیرنده) یا Payer (پرداخت کننده).
suggested_amount	str	مبلغ پیشنهادی برای تسویه حساب

نمونه کد

در ادامه نمونه کدی ارائه شده است که کارمزد یک تراکنش را محاسبه می‌کند:

<?php
require_once __DIR__ . '/../vendor/autoload.php';
use ZarinPal\Sdk\Options;
use ZarinPal\Sdk\ZarinPal;
use ZarinPal\Sdk\HttpClient\Exception\ResponseException;
use ZarinPal\Sdk\Endpoint\PaymentGateway\RequestTypes\FeeCalculationRequest;
$options = new Options([
    'merchant_id' => '67887a6d-e2f8-4de2-86b1-8db27bc171b5',
]);
$zarinpal = new ZarinPal($options);
$paymentGateway = $zarinpal->paymentGateway();
$feeCalculationRequest = new FeeCalculationRequest();
$feeCalculationRequest->merchant_id = '67887a6d-e2f8-4de2-86b1-8db27bc171b5';
$feeCalculationRequest->amount = 100000; // 100,000 ریال
$feeCalculationRequest->currency = 'IRR'; // اختیاری
try {
    $response = $paymentGateway->feeCalculation($feeCalculationRequest);
    echo "Fee Calculation Result: \n";
    echo "Code: " . $response->code . "\n";
    echo "Message: " . $response->message . "\n";
    echo "Amount: " . $response->amount . " ریال\n";
    echo "Fee: " . $response->fee . " ریال\n";
    echo "Fee Type: " . $response->fee_type . "\n";
} catch (ResponseException $e) {
    echo 'Fee Calculation Validation Error: ' . $e->getErrorDetails();
} catch (\Exception $e) {
    echo 'Fee Calculation Error: ' . $e->getMessage();
}

نکات مهم

• مبلغ تراکنش باید حداقل 10000 ریال باشد
• کارمزد محاسبه شده بر اساس تنظیمات ترمینال شما و نوع تراکنش متفاوت خواهد بود
• نوع پرداخت کننده کارمزد (fee_type) می‌تواند Merchant (پذیرنده می‌پردازد) یا Payer (مشتری می‌پردازد) باشد
• این متد صرفاً برای محاسبه کارمزد است و هیچ تراکنشی ایجاد نمی‌کند