نمونه کد PHP

کیت PHP فینوپال برای اتصال درگاه در پروژه‌های سمت سرور است. شکل استفاده همان نمونه کدهای رایج درگاه است: یک تنظیم، کلاینت، و متدهای paymentGateway(). مبلغ‌ها به ریال و حداقل ۱۰۰۰ ریال هستند.

زبان
PHP 8.1+
بسته
finopal/finopal-php-sdk
حمل‌ونقل
cURL

نصب

پیش‌نیاز: 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خطای شبکه یا پاسخ نامعتبر. نتیجه نامعلوم است؛ استعلام بگیرید

کدهای پرکاربرد: ۹− اعتبارسنجی، ۱۱− درگاه یا تراکنش پیدا نشد، ۱۴− دامنه بازگشت با دامنه ثبت‌شده یکی نیست، ۵۰− مبلغ تأیید با مبلغ درخواست فرق دارد.