نمونه کد PHP
کیت PHP فینوپال برای اتصال درگاه در پروژههای سمت سرور است. شکل استفاده همان نمونه کدهای رایج درگاه است: یک تنظیم، کلاینت، و متدهای paymentGateway(). مبلغها به ریال و حداقل ۱۰۰۰ ریال هستند.
نصب
پیشنیاز: PHP 8.1 یا بالاتر، افزونه curl و Composer.
تا زمان انتشار روی Packagist، بسته را از مسیر محلی وصل کنید:
composer config repositories.finopal path ../finopal-php-sdk
composer require finopal/finopal-php-sdk
پیکربندی
مرچنتکد را از پنل کاربری بردارید. برای محیط آزمایشی sandbox را true بگذارید. میزبان واقعی https://payment.finopal.ir و سندباکس https://sandbox.finopal.ir است.
use FinoPal\Sdk\FinoPal;
use FinoPal\Sdk\Options;
$options = new Options([
'merchant_id' => 'fino-xxxx-xxxx-xxxx-xxxx',
'sandbox' => false,
]);
$finopal = new FinoPal($options);
$paymentGateway = $finopal->paymentGateway();
درخواست پرداخت
order_id الزامی است. توضیحات حداکثر ۲۵۵ کاراکتر است. پس از موفقیت، کاربر را به payment_url بفرستید.
use FinoPal\Sdk\Endpoint\PaymentGateway\RequestTypes\RequestRequest;
$request = new RequestRequest();
$request->amount = 10000;
$request->description = 'سفارش ۱۲۳۴۵';
$request->callback_url = 'https://shop.example/verify.php';
$request->order_id = 'ORD-12345';
$response = $paymentGateway->request($request);
$url = $response->payment_url !== ''
? $response->payment_url
: $paymentGateway->getRedirectUrl($response->authority);
header('Location: ' . $url);
تأیید پرداخت
فقط وقتی Status=OK است (در سندباکس Status=0) متد verify را صدا بزنید. مبلغ باید دقیقاً همان مبلغ درخواست اول باشد. کد ۱۰۰ یعنی تازه تأیید شد و کد ۱۰۱ یعنی قبلاً تأیید شده بود. هر دو یعنی پرداخت موفق است.
use FinoPal\Sdk\Endpoint\PaymentGateway\RequestTypes\VerifyRequest;
$authority = isset($_GET['Authority']) ? (string) $_GET['Authority'] : '';
$status = isset($_GET['Status']) ? (string) $_GET['Status'] : '';
if ($status === 'OK' || $status === '0') {
$verifyRequest = new VerifyRequest();
$verifyRequest->authority = $authority;
$verifyRequest->amount = $amountFromOrder;
$response = $paymentGateway->verify($verifyRequest);
// $response->code برابر 100 یا 101
// $response->ref_id شماره پیگیری
}
استعلام، ریورس و کارمزد
اگر verify بهخاطر قطع شبکه نامعلوم ماند، بهجای ساخت پرداخت تازه استعلام بگیرید. وضعیتها: pending، successful، failed، cancelled، refunded و callback.
use FinoPal\Sdk\Endpoint\PaymentGateway\RequestTypes\InquiryRequest;
use FinoPal\Sdk\Endpoint\PaymentGateway\RequestTypes\ReverseRequest;
use FinoPal\Sdk\Endpoint\PaymentGateway\RequestTypes\FeeRequest;
$inquiry = new InquiryRequest();
$inquiry->authority = $authority;
$status = $paymentGateway->inquiry($inquiry);
$reverse = new ReverseRequest();
$reverse->authority = $authority;
$paymentGateway->reverse($reverse);
$fee = new FeeRequest();
$fee->amount = 1000000;
$feeResult = $paymentGateway->fee($fee);
// fee_type برابر Merchant یا Payer
ریورس فقط روی تراکنش تأییدشده و در بازه کوتاه پس از تأیید ممکن است.
خطا
| استثنا | معنی |
|---|---|
| ValidationException | ورودی نامعتبر؛ درخواستی ارسال نشده |
| ResponseException | گیتوی درخواست را رد کرده. کد و جزئیات روی استثنا است |
| TransportException | خطای شبکه یا پاسخ نامعتبر. نتیجه نامعلوم است؛ استعلام بگیرید |
کدهای پرکاربرد: ۹− اعتبارسنجی، ۱۱− درگاه یا تراکنش پیدا نشد، ۱۴− دامنه بازگشت با دامنه ثبتشده یکی نیست، ۵۰− مبلغ تأیید با مبلغ درخواست فرق دارد.