README

Shaparak 组件是 Laravel 5+ 的在线支付组件，完全兼容 BankTest 模拟器。Shaparak 将所有伊朗/Shetab 支付网关集成到一个组件中。

什么是 Banktest？

BankTest 是所有伊朗在线支付网关的沙箱服务
بانک تست 是一个用于开发测试目的的伊朗在线支付网关模拟器服务

支持此项目

请通过给它 ⭐ 并为其开发做出贡献来支持此包。

目前支持的 PSP

Mellat Bank Gateway - درگاه بانک ملت (به پرداخت ملت) لاراول
Saman Bank Gateway - درگاه بانک سامان (پرداخت الکترونیک سامان) لاراول
Saderat Bank Gateway - درگاه بانک صادرات (پرداخت الکترونیک سپهر) لاراول
Pasargad Bank Gateway - درگاه بانک پاسارگاد (پرداخت الکترونیک پاسارگاد) لاراول
Parsian Bank Gateway - درگاه بانک پارسیان (تجارت الکترونیک پارسیان) لاراول
Melli Bank Gateway - درگاه بانک ملی (سداد) لاراول
...

要求

Shaparak 需要 PHP 7.1+

安装

通过 php composer 安装

composer require php-monsters/shaparak

将包服务提供者添加到您的应用服务提供者中

PhpMonsters\Shaparak\ShaparakServiceProvider::class,

将包别名添加到您的应用别名中

'Shaparak' => PhpMonsters\Shaparak\Facades\Shaparak::class,

发布包资源和配置

php artisan vendor:publish --provider="PhpMonsters\Shaparak\ShaparakServiceProvider"

配置

如果您正确完成安装步骤，您可以在项目配置文件中找到 Shaparak 配置文件 shaparak.php。

要使用沙箱环境，您应该在您的 .env 文件中设置 SHAPARAK_MODE=development，否则设置 SHAPARAK_MODE=production

如果您选择开发模式，Shaparak 将使用 banktest.ir 作为其支付网关。

用法

将所需字段添加到模型迁移中

$table->string('token', 40)->nullable(); // It keeps token that we get from the IPG
$table->jsonb('gateway_callback_params')->nullable(); // It keeps the IPG callback parameters (just for tracking and debugging)

$table->boolean('verified')->default(false); // Transaction verified or not
$table->boolean('after_verified')->default(false); // Transaction settled or not
$table->boolean('reversed')->default(false); // Transaction revered/refunded or not
$table->boolean('accomplished')->default(false); // Transaction accomplished or not

准备所需模型

您的交易、发票或订单模型必须实现 Shaparak 交易接口。

<?php

namespace App\Models;

use App\Traits\JsonbField;
use App\Traits\ShaparakIntegration;
use Illuminate\Database\Eloquent\Model;
use PhpMonsters\Shaparak\Contracts\Transaction as ShaparakTransaction;

class Transaction extends Model implements TransactionTransaction
{

Shaparak 集成特质

您可以使用以下特质来集成您的模型与 Shaparak 并实现 Shaparak 的交易合同。

示例集成特质（这只是示例）:

trait ShaparakIntegration
{
    /**
     * return callback url for payment process
     */
    public function getCallbackUrl(): string
    {
        return makeHttpsUrl(route(
            'ipg.transaction_callback',
            [
                'token' => $this->token,
            ]
        ));
    }

    /**
     * set gateway token that fetched from ipg provider gateway
     */
    public function setGatewayToken(string $token, bool $save = true): bool
    {
        $this->token = $token;
        $this->status = (TransactionStatusEnum::GoneToGate)->value;

        if ($save) {
            return $this->save();
        }

        return true;
    }

    public function getGatewayToken(): string
    {
        return $this->token;
    }

    /**
     * check if you transaction is ready for requesting payment token
     */
    public function isReadyForTokenRequest(): bool
    {
        return intval($this->status) <= (TransactionStatusEnum::Callback)->value;
    }

    /**
     * check if transaction is ready for requesting verify transaction
     */
    public function isReadyForVerify(): bool
    {
        return intval($this->status) <= (TransactionStatusEnum::Verified)->value;
    }

    /**
     * check if transaction is ready for requesting inquiry transaction (if supported by gateway)
     */
    public function isReadyForInquiry(): bool
    {
        return intval($this->status) >= (TransactionStatusEnum::GoneToGate)->value;
    }

    /**
     * check if transaction is ready for requesting settle/... transaction (if needed by gateway)
     */
    public function isReadyForSettle(): bool
    {
        return intval($this->status) == (TransactionStatusEnum::Verified)->value;
    }

    /**
     * check if transaction is ready to mark as  accomplished
     */
    public function isReadyForAccomplish(): bool
    {
        return (intval($this->status) >= (TransactionStatusEnum::Verified)->value) &&
            (intval($this->status) < (TransactionStatusEnum::Accomplished)->value);
    }

    public function ipgProviderSupportsRefund(): bool
    {
        return ! empty($this->providable) &&
            $this->providable->refund_support === true;
    }

    public function isReadyForReverse(): bool
    {
        return $this->status === TransactionStatusEnum::Callback->value;
    }

    public function isReadyForCancel(): bool
    {
        return $this->status === TransactionStatusEnum::Verified->value;
    }

    /**
     * check if transaction is ready for accomplishment (merchant verify)
     */
    public function isReadyForRefund(): bool
    {
        return
            $this->ipgProviderSupportsRefund() &&
            (int) $this->status !== (TransactionStatusEnum::Accomplished)->value;
    }

    /**
     * update transaction by paid card number (if provided by gateway)
     */
    public function setCardNumber(string $cardNumber, bool $save = true): bool
    {
        $this->cardNumber = $cardNumber;

        if ($save) {
            return $this->save();
        }

        return true;
    }

    /**
     * mark transaction as verified
     */
    public function setVerified(bool $save = true): bool
    {
        $this->status = (TransactionStatusEnum::Verified)->value;

        if ($save) {
            return $this->save();
        }

        return true;
    }

    /**
     * mark transaction as settled/...
     */
    public function setSettled(bool $save = true): bool
    {
        $this->status = (TransactionStatusEnum::Settled)->value;

        if ($save) {
            return $this->save();
        }

        return true;
    }

    /**
     * mark transaction as reversed
     */
    public function setRefunded(bool $save = true): bool
    {
        $this->status = (TransactionStatusEnum::Refund)->value;

        if ($save) {
            return $this->save();
        }

        return true;
    }

    /**
     * get transaction amount
     */
    public function getPayableAmount(): int
    {
        return $this->payable_amount;
    }

    /**
     * save ipg provider's gateway callback parameters into transaction
     */
    public function setCallBackParameters(array $parameters, bool $save = true): bool
    {
        $this->gateway_callback_params = $parameters;

        if ($save) {
            return $this->save();
        }

        return true;
    }

    /**
     * @return false|mixed|string
     */
    public function getCallbackParams(): mixed
    {
        return $this->gateway_callback_params;
    }
}

初始化 Shaparak 实例

// method I: init Shaparak by passing custom gateway options
$gatewayProperties = [
    'terminal_id' => 'X1A3B5CY-X1DT4Z',
    'terminal_pass' => '12345',
];
$shaparak = Shaparak::with($psp, $transaction, $gatewayProperties)
    ->setParameters($request->all());
    
// method II: init shaparak by config based gateway options
// if you don't pass the third item it will use gateway's options from `config/shaparak.php` config file
$shaparak = Shaparak::with($psp, $transaction)
    ->setParameters($request->all());

创建 Goto IPG 表单（支付表单）

创建一个表单以跳转到支付网关。此表单默认自动提交

// create your transaction as you desired
$transaction = new Transaction();
$transaction->user_id = $user->id;
// ...
$transaction->ip_address = $request->getClientIp();
$transaction->description = $request->input('description');
$transaction->save();

try {
    $form = Shaparak::with('saman', $transaction)->getForm();
} catch (\Exception $e) {
    XLog::exception($e);
    flash(trans('gate.could_not_create_goto_bank_form'))->error();
    return redirect()->back();
}

在您的 blade 中显示表单，如下所示

{!! $form !!}

应用程序的回调 URL/路由

在您的回调操作中创建 Shaparak 实例并处理交易

$shaparak = Shaparak::with('saman', $order)
    ->setParameters($request->all());
    
if ($shaparak->canContinueWithCallbackParameters($request->all()) !== true) {
    flash(trans('gate.could_not_continue_because_of_callback_params'))->error();
    // do what you need
}

$shaparak->setCallBackParameters($request->all());

$verifyResult = $shaparak->verifyTransaction($request->all());

下一步（可选步骤）

根据您的需求使用以下方法

$inquiryResult = $shaparak->inquiryTransaction($request->all());
$settleResult = $shaparak->settleTransaction($request->all());
$refundResult = $shaparak->refundTransaction($request->all());

安全

如果您发现任何安全问题，请通过电子邮件 aboozar.ghf@gmail.com 来报告，而不是使用问题跟踪器。

团队

此组件由以下人员开发和一群出色的贡献者开发。

许可证

Laravel 在线支付模块是开源软件，许可协议为 MIT 许可证

php-monsters / shaparak

维护者

详细信息