README

完整的Goldenpay集成Laravel包。

目录

1. 要求
2. 安装
3. 使用
4. 控制器
5. 模型
6. 命令
7. 事件
8. 配置

要求

安装

您可以通过composer安装此包

composer require orkhanahmadov/laravel-goldenpay

运行此命令以发布所需的迁移文件

php artisan vendor:publish --provider="Orkhanahmadov\LaravelGoldenpay\LaravelGoldenpayServiceProvider" --tag=migrations

使用

首先，在.env文件中设置您的Goldenpay商户名称和认证密钥。您可以从Goldenpay仪表板获取这些信息。

GOLDENPAY_AUTH_KEY=your-auth-key
GOLDENPAY_MERCHANT_NAME=your-merchant-name

要使用Goldenpay服务，您需要Orkhanahmadov\LaravelGoldenpay\Goldenpay的实例。您可以使用Laravel的服务容器实例化此类，例如通过将其注入到您的控制器中

use Orkhanahmadov\LaravelGoldenpay\Goldenpay;

class MyController
{
    public function index(Goldenpay $goldenpay)
    {
        //
    }
}

或者您可以使用Laravel的服务解析器来创建类的实例

use Orkhanahmadov\LaravelGoldenpay\Goldenpay;

class MyClass
{
    public function doSomething()
    {
        $goldenpay = app(Goldenpay::class);
        //
    }
}

可用方法

payment()

基于传递的凭据准备支付，并接受4个参数

• Amount - 支付金额，仅接受整数。例如，如果您想创建10.25的支付，则将其作为1025传递。
• Card type - 需要Orkhanahmadov\Goldenpay\Enums\CardType的实例。《CardType::VISA()` 用于VISA，《CardType::MASTERCARD()` 用于MasterCard
• Description - 支付描述
• Language (可选) - 设置支付页面界面语言。需要Orkhanahmadov\Goldenpay\Enums\Language的实例。《Language::EN()` 用于英语，《Language::RU()` 用于俄语，《Language::AZ()` 用于阿塞拜疆语。如果没有传递，则服务将使用Laravel的活动区域设置。

$goldenpay = app(Goldenpay::class);
$goldenpay->payment(1000, CardType::MASTERCARD(), 'my payment');

方法返回创建的Orkhanahmadov\LaravelGoldenpay\Models\Payment模型实例。

您可以使用$payment_url属性来获取唯一的支付URL，并将用户重定向到该URL以开始支付。

$payment = $goldenpay->payment(1000, CardType::MASTERCARD(), 'my payment');

$payment->payment_url; // redirect user to this URL to start payment

result()

根据之前支付的关键字检查支付结果。接受单个参数

• Payment - 这是Goldenpay的支付关键字作为字符串，或之前创建的Orkhanahmadov\LaravelGoldenpay\Models\Payment模型实例。

$goldenpay = app(Goldenpay::class);
$paymentModel = $goldenpay->payment(1000, CardType::MASTERCARD(), 'my payment');

$result = $goldenpay->result($paymentModel);
// or
$result = $goldenpay->result('1234-ABCD-5678');

方法返回带有Goldenpay响应的更新后的Orkhanahmadov\LaravelGoldenpay\Models\Payment模型实例。

控制器

Goldenpay要求拥有成功和失败支付的端点。对于这些端点中的每一个，Goldenpay都会发送带有附加的payment_key查询字符串的GET请求。要获取支付结果，您需要创建一个路由来接受这些请求，并使用接收到的payment_key获取支付结果。

包附带一个控制器，可帮助简化此过程。要开始，首先为成功或失败的支付创建一个GET路由，并将完整的URL添加到Goldenpay仪表板中的相应字段。

Route::get('payments/successful', 'App\Http\Controllers\Payment\SuccessfulPaymentController@index');

为您的新路由创建一个控制器类，并扩展Orkhanahmadov\LaravelGoldenpay\Http\Controllers\GoldenpayController。

use Orkhanahmadov\LaravelGoldenpay\Http\Controllers\GoldenpayController;

class SuccessfulPaymentController extends GoldenpayController
{
    public function index()
    {
        // return a view or JSON, totally up to you
    }
}

通过扩展Orkhanahmadov\LaravelGoldenpay\Http\Controllers\GoldenpayController，您的控制器将自动根据payment_key查询字符串检查支付结果。

在您的控制器中，您可以通过访问$payment属性来访问Goldenpay的支付结果。

public function index()
{
    $this->payment->status; // will return payment status 
    $this->payment->successful; // will return true if payment was successful or false if unsuccessful
}

您可以使用相同的端点来处理成功和失败的支付，并基于$this->payment->successful状态显示用户想要的内容，或者您创建单独的端点和控制器，并在两个控制器中扩展Orkhanahmadov\LaravelGoldenpay\Http\Controllers\GoldenpayController。

模型

包附带Orkhanahmadov\LaravelGoldenpay\Models\Payment Eloquent模型。模型为每次支付存储以下信息

• payment_key - 字符串，Goldenpay提供的唯一支付关键字
• amount - 整数，支付金额
• card_type - 枚举，"m" 表示万事达卡，"v" 表示维萨卡
• language - 枚举，"en" 表示英语，"ru" 表示俄语，"lv" 表示阿塞拜疆语
• description - 字符串，支付描述
• status - 整数，支付状态代码
• message - 字符串，支付状态消息
• reference_number - 字符串，支付参考号
• card_number - 字符串，加密，用于支付的卡号
• payment_date - 日期时间，支付日期
• checks - 整数，支付检查次数

除了常见的Eloquent功能外，此模型还具有特定的访问器、作用域和关系能力，您可以使用这些能力。

访问器

• successful - 如果支付标记为成功则返回 true，否则返回 false
• payment_url - 返回支付页面URL。如果支付标记为成功则返回 null
• formatted_amount - 返回十进制形式的 "amount"
• card_number_decrypted - 返回解密后的 "card_number" 值。如果卡号加密已关闭则返回 null

作用域

• whereSuccessful() - 只过滤 "successful" 支付
• wherePending() - 只过滤 "pending" 支付。待支付是指未成功且在30分钟内创建或支付检查次数少于3次的支付。

关系

您可以将任何现有的Eloquent模型转换为 "payable" 并将其与Goldenpay支付相关联。在现有模型中使用 Orkhanahmadov\LaravelGoldenpay\Traits\Payable 特性来建立直接模型关系。使用特性需要您的模型中定义 amount() 和 description() 方法。

• amount() - 必须返回整数形式的支付金额
• description() - 必须返回支付实例的描述

use Illuminate\Database\Eloquent\Model;
use Orkhanahmadov\LaravelGoldenpay\Traits\Payable;

class Product extends Model
{
    use Payable;

    protected $fillable = [
        'name',
        'color',
        'size',
        'price',
    ];

    protected $casts = [
        'price' => 'float', // lets image that you store price as float, like "15.70" in "products" table
    ];

    protected function amount(): int
    {
        // this method needs to return integer value of price
        return $this->price * 100;
    }

    protected function description(): string
    {
        // this method needs to return description for payment instance
        // try to use both unique and easy to read identifier
        return $this->id . ' - ' . $this->name . ' - ' . $this->color;
    }
}

现在 Product 模型与Goldenpay支付具有直接关系。通过使用 Payable，您的模型也获得了访问与支付相关的关联和支付方式的权限。

createPayment()

$product = Product::find(1);

$product->createPayment(CardType::VISA()); // uses product amount() and description() to create new payment instance

您也可以为特定支付重写 amount 和 description()

$product->createPayment(CardType::VISA(), 2599, 'my custom description');

方法接受以下参数

• 卡类型 - Orkhanahmadov\Goldenpay\Enums\CardType 的实例
• 金额 (可选) - 当使用时将覆盖模型中的 amount() 方法值
• 描述 (可选) - 当使用时将覆盖模型中的 description() 方法值
• 语言 (可选) - 当跳过时将使用Laravel的locale。实例为 Orkhanahmadov\Goldenpay\Enums\Language。

方法返回创建的 Orkhanahmadov\LaravelGoldenpay\Models\Payment 实例。

payments()

Eloquent关系方法。返回与模型相关联的所有支付。

$product = Product::find(1);
$product->payments; // returns collection of related Payment models
$product->payments()->where('amount', '>=', 10000); // use it as regular Eloquent relationship

successfulPayments()

Eloquent关系方法。返回与模型相关联的所有成功支付。

$product = Product::find(1);
$product->successfulPayments; // returns collection of related Payment models
$product->successfulPayments()->where('amount', '>=', 10000); // use it as regular Eloquent relationship

命令

该包附带用于检查支付结果的 artisan 命令。

php artisan goldenpay:result

执行上述命令将遍历所有 "pending" 支付并更新它们的结果。

命令也接受支付键作为参数以检查单个支付结果。

php artisan goldenpay:result 1234-ABCD-5678

Goldenpay需要手动检查支付以确定其最终状态。例如，用户可能访问支付页面然后关闭浏览器窗口而不输入任何内容。这些支付情况需要手动检查以确定其状态。您可以使用Laravel的 任务调度 在Cron作业上运行 goldenpay:result 命令。

protected function schedule(Schedule $schedule)
{
    $schedule->command('goldenpay:result')->everyFiveMinutes();
}

因为Goldenpay表示每个支付会话仅在15分钟内是活动的，所以建议频率为每5或10分钟一次。

事件

该包附带Laravel事件，这些事件在特定条件下被触发。

可用事件类

• Orkhanahmadov\LaravelGoldenpay\Events\PaymentCreatedEvent - 当创建新支付时触发
• Orkhanahmadov\LaravelGoldenpay\Events\PaymentCheckedEvent - 当支付结果检查时触发
• Orkhanahmadov\LaravelGoldenpay\Events\PaymentSuccessfulEvent - 当支付成功最终化时触发

每个事件都会接收到Orkhanahmadov\LaravelGoldenpay\Models\Payment Eloquent模型的实例，作为公开的$payment属性。

您可以设置事件监听器，当特定支付事件触发时执行。

protected $listen = [
    'Orkhanahmadov\LaravelGoldenpay\Events\PaymentSuccessfulEvent' => [
        'App\Listeners\SendPaymentInvoice',
        'App\Listeners\SendProductLicense',
    ],
];

配置

运行此命令以发布包配置文件

php artisan vendor:publish --provider="Orkhanahmadov\LaravelGoldenpay\LaravelGoldenpayServiceProvider" --tag=config

配置文件包含以下设置

• auth_key - 定义Goldenpay的"auth key"，默认为.env变量
• merchant_name - 定义Goldenpay的"商户名称"，默认为.env变量
• table_name - 定义Goldenpay支付数据库表的名称。默认："goldenpay_payments"
• encrypt_card_numbers - 定义在创建支付或获取支付结果时是否需要自动加密"card_number"字段。默认为true，如果您想禁用自动加密，请将其更改为false。建议保持为true以提供额外的安全层。警告！如果您在支付表中已有记录，更改此值将破坏加密/解密。旧值将不会自动加密/解密，您需要手动操作。
• payment_events - 支付事件相关设置
  • enabled - 定义是否启用支付事件。设置为false以禁用所有支付事件
  • checked - "支付检查"事件类。默认使用Orkhanahmadov\LaravelGoldenpay\Events\PaymentCreatedEvent类
  • created - "支付创建"事件类。默认使用Orkhanahmadov\LaravelGoldenpay\Events\PaymentCheckedEvent类
  • successful - "支付成功"事件类。默认使用Orkhanahmadov\LaravelGoldenpay\Events\PaymentSuccessfulEvent类

如果您想为特定支付事件使用自己的事件类，可以替换类命名空间为您的类命名空间。每个支付事件都会接收到Orkhanahmadov\LaravelGoldenpay\Models\Payment Eloquent模型的实例。因此，请确保将支付模型作为依赖项添加到您的事件类构造函数签名中，或者您可以扩展已将支付模型作为依赖项的Orkhanahmadov\LaravelGoldenpay\Events\PaymentEvent类。

将特定支付事件设置为null将禁用该事件而不会中断其他事件。

测试

composer test

贡献

请参阅CONTRIBUTING以获取详细信息。

安全

如果您发现任何安全相关的问题，请通过ahmadov90@gmail.com发送电子邮件，而不是使用问题跟踪器。

致谢

• Orkhan Ahmadov
• 所有贡献者

支持我

如果您喜欢我的工作，如果我的开源贡献帮助了您或您的公司，请考虑通过Github Sponsors支持我。

许可

MIT许可（MIT）。请参阅许可文件以获取更多信息。