README

为Laravel提供的简单且完整的YooKassa（以前称为Yandex Checkout）集成

待办事项

• 测试覆盖率

目录

1. 需求
2. 安装
3. 使用
4. 模型
5. 命令
6. 事件
7. 配置

需求

• PHP 7.3 或更高版本
• Laravel 6 或更高版本

安装

您可以通过composer安装此包

composer require orkhanahmadov/yandex-checkout

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

php artisan vendor:publish --provider="Orkhanahmadov\YandexCheckout\YandexCheckoutServiceProvider" --tag=migrations

使用

首先，在.env文件中设置Yandex Checkout商店ID和密钥。您可以从YooMoney商户页面获取这些信息。

YANDEX_CHECKOUT_SHOP_ID=
YANDEX_CHECKOUT_SECRET_KEY=

要使用Yandex Checkout服务，您需要Orkhanahmadov\YandexCheckout\YandexCheckoutService的实例。您可以使用Laravel的服务容器来实例化此类，例如通过注入到您的控制器中

use Orkhanahmadov\YandexCheckout\YandexCheckoutService;

class MyController
{
    public function index(YandexCheckoutService $yandexCheckout)
    {
        //
    }
}

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

use Orkhanahmadov\YandexCheckout\YandexCheckoutService;

class MyClass
{
    public function doSomething()
    {
        $yandexCheckout = app(YandexCheckoutService::class);
        //
    }
}

可用方法

createPayment()

根据传递的凭据创建新的支付，并接受两个参数

• Model - 与支付关联的Eloquent模型
• Payment request - 包含金额、货币等信息的数据的支付请求

$product = Product::first();
$yandexCheckout = app(YandexCheckoutService::class);
$paymentRequest = CreatePaymentRequest::builder()->build([
    'amount' => [
        'value' => 49.99,
        'currency' => 'RUB',
    ],
    'confirmation' => [
        'type' => 'redirect',
        'return_url' => 'https://example.com',
    ],
    'capture' => true,
    'description' => 'Payment for product: ' . $product->id,
]);
$yandexCheckout->createPayment($product, $paymentRequest);

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

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

paymentInfo()

获取先前创建的支付信息。接受单个参数

• Payment - 这是Yandex Checkout的支付ID，作为字符串，或者先前创建的Orkhanahmadov\YandexCheckout\Models\YandexCheckout模型实例。

$product = Product::first();
$yandexCheckout = app(YandexCheckoutService::class);
$payment = $yandexCheckout->createPayment($product, ...);

$paymentInfo = $yandexCheckout->paymentInfo($payment);
// or
$paymentInfo = $yandexCheckout->paymentInfo('1234-ABCD-5678');

方法返回具有Yandex Checkout响应的更新后的Orkhanahmadov\YandexCheckout\Models\YandexCheckout模型实例。

模型

此包附带Orkhanahmadov\YandexCheckout\Models\YandexCheckout Eloquent模型。模型为每个支付存储以下信息

• payment_id - 字符串，由Yandex Checkout提供的唯一支付密钥
• status - 字符串，支付状态代码
• response - 数组，序列化的结账对象

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

访问器

• succeeded - 如果支付标记为“成功”，则返回true，否则返回false
• paid - 如果结账已支付，则返回true，否则返回false
• confirmation_url - 返回“确认URL”，应使用该URL开始支付
• cancellation_reason - 返回支付取消/失败原因。当支付成功或尚未开始时返回null

作用域

• succeeded() - 仅过滤“成功”支付
• pending() - 仅过滤“挂起”支付。挂起支付是指状态不是“成功”或“已取消”的支付。

关系

您可以使任何现有的Eloquent模型“可支付”，并将Yandex Checkouts附加到它。在您的现有模型中使用Orkhanahmadov\YandexCheckout\Traits\HandlesYandexCheckout特性来建立直接模型关系。

use Illuminate\Database\Eloquent\Model;
use Orkhanahmadov\YandexCheckout\Traits\HandlesYandexCheckout;

class Product extends Model
{
    use HandlesYandexCheckout;
}

现在Product模型与Yandex Checkouts有直接关系。通过使用HandlesYandexCheckout，您的模型也获得了访问与支付相关的关联和支付方式的能力。

createPayment()

$product = Product::first();

$paymentRequest = CreatePaymentRequest::builder()->build([
    'amount' => [
      'value' => 49.99,
      'currency' => 'RUB',
    ],
    'confirmation' => [
      'type' => 'redirect',
      'return_url' => 'https://example.com',
    ],
    'capture' => true,
    'description' => 'Payment for product: ' . $product->id,
]);
$product->createPayment($paymentRequest);

yandexCheckouts()

优雅的关系方法。返回所有相关的Yandex Checkout。

$product = Product::first();
$product->yandexCheckouts; // returns collection of related Yandex Checkouts
$product->yandexCheckouts()->where('payment_id', '123-ABC-456'); // use it as regular Eloquent relationship
$product->yandexCheckouts()->pending(); // use scopes on YandexCheckout model

命令

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

php artisan yandex-checkout:check

执行上述命令将遍历所有“待处理”的 checkout 并更新其模型。

命令还接受支付 ID 作为参数，以检查单个 checkout 结果。

php artisan yandex-checkout:check 1234-ABCD-5678

您可以设置 Cron 作业计划，以便频繁检查所有“待处理”的 checkout。

protected function schedule(Schedule $schedule)
{
    $schedule->command('yandex-checkout:check')->everyMinute();
}

事件

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

可用事件类

• Orkhanahmadov\YandexCheckout\Events\CheckoutCreated - 在创建新的 checkout 时触发
• Orkhanahmadov\YandexCheckout\Events\CheckoutSucceeded - 在支付状态更改为“成功”时触发
• Orkhanahmadov\YandexCheckout\Events\CheckoutCanceled - 在支付状态更改为“已取消”时触发
• Orkhanahmadov\YandexCheckout\Events\CheckoutChecked - 在检查支付信息时触发

每个事件都接收 Orkhanahmadov\YandexCheckout\Models\YandexCheckout Eloquent 模型的实例作为公共 $yandexCheckout 属性。

您可以为特定支付事件设置事件监听器。

protected $listen = [
    'Orkhanahmadov\YandexCheckout\Events\CheckoutSucceeded' => [
        'App\Listeners\DispatchOrder',
        'App\Listeners\SendInvoice',
    ],
];

配置

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

php artisan vendor:publish --provider="Orkhanahmadov\YandexCheckout\YandexCheckoutServiceProvider" --tag=config

配置文件包含以下设置

• shop_id - 定义 Yandex Checkout 的“商店 ID”，默认为 .env 变量
• secret_key - 定义 Yandex Checkout 的“密钥”，默认为 .env 变量
• table_name - 定义 Yandex Checkout 支付数据库表的名称。默认：“yandex_checkouts”
• events - 与支付事件相关的设置
  • created - “Checkout created”事件类。默认使用 Orkhanahmadov\YandexCheckout\Events\CheckoutCreated 类
  • succeeded - “Checkout succeeded”事件类。默认使用 Orkhanahmadov\YandexCheckout\Events\CheckoutSucceeded 类
  • canceled - “Checkout canceled”事件类。默认使用 Orkhanahmadov\YandexCheckout\Events\CheckoutCanceled 类
  • checked - “Checkout checked”事件类。默认使用 Orkhanahmadov\YandexCheckout\Events\CheckoutChecked 类

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

将特定支付事件设置为 null 将禁用该事件。

测试

composer test

变更日志

请参阅CHANGELOG 了解最近更改的更多信息。

贡献

请参阅CONTRIBUTING 了解详细信息。

安全

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

致谢

• Orkhan Ahmadov
• LinksDerIsar
• 所有贡献者

许可证

MIT 许可证（MIT）。请参阅许可证文件 了解更多信息。