README

通过OpenPayu SDK集成PayU。

安装

composer require x-one/payu-bundle

Symfony Flex应该会自动将新条目添加到config/bundles.php文件中。

配置

使用config/packages/x_one_payu.yaml文件配置此包。

x_one_payu:
  api:
    environment: ...           # Środowisko - "sandbox" lub "secure"
    merchant_pos_id: ...       # Id punktu płatności (pos_id)
    signature_key: ...         # Drugi klucz (MD5)
    oauth_client_id: ...       # Protokół OAuth - client_id
    oauth_client_secret: ...   # Protokół OAuth - client_secret
    oauth_grant_type: ...      # Grant type - "client_credentials" (domyślnie) lub "trusted_merchant"
    oauth_email: ...           # Wymagane, jeżeli grant type ustawiony na "trusted_merchant"
    oauth_ext_customer_id: ... # Wymagane, jeżeli grant type ustawiony na "trusted_merchant"
    continue_route: ...        # Symfonowy route do przekierowania po płatności
    notify_route: ...          # Symfonowy route do odbioru powiadomienia o zmianie statusu

上述配置值（除了路由）来自PayU面板中“我的商店”>进入具体商店>“支付点”>特定支付点的详细信息中的商店支付点配置。

路由

此包提供了一个处理来自PayU通知的route。要将它们导入，请向config/routes.yaml添加条目

x_one_payu:
  resource: '@XOnePayuBundle/config/routes.php'
  prefix: /payments/payu

导入的route可以在包配置中使用

x_one_payu:
  api:
    notify_route: x_one_payu_notify

实体

此包需要添加实体

• PayuOrder 扩展 XOne\Bundle\PayuBundle\Entity\Order
• PayuRefund 扩展 XOne\Bundle\PayuBundle\Entity\Refund

实体示例

<?php

declare(strict_types=1);

namespace App\Entity\Payment;

use App\Repository\Payment\PayuOrderRepository;
use Doctrine\ORM\Mapping as ORM;
use XOne\Bundle\PayuBundle\Entity\Order;

#[ORM\Entity(repositoryClass: PayuOrderRepository::class)]
#[ORM\Table(name: 'payu_order')]
class PayuOrder extends Order
{
}

创建后，请将其添加到配置中

# config/packages/x_one_payu.yaml
x_one_payu:
  entities:
    order: App\Entity\Payment\PayuOrder
    refund: App\Entity\Payment\PayuRefund

创建订单

要创建PayU中的订单，请创建订单实体并将其传递给客户端HTTP

/**
 * @var XOne\Bundle\PayuBundle\Http\ClientInterface $payuClient
 * @var XOne\Bundle\PayuBundle\Factory\OrderFactoryInterface $payuOrderFactory
 * @var XOne\Bundle\PayuBundle\Model\OrderInterface $payuOrder
 */

$payuOrder = $payuOrderFactory->create(
    description: 'Zamówienie w sklepie',
    currencyCode: 'PLN',
    totalAmount: 149_99, // 149.99zł
);

$payuClient->createOrder($payuOrder);

在传递的订单对象中会填充

• PayU订单标识符；
• 将客户重定向到支付页面的链接；

订单描述

PayU订单由4种不同的描述组成

更新订单状态

PayU通过向先前配置的notify_route发送POST请求来通知系统订单更新。内置的控制器XOne\Bundle\PayuBundle\Controller\NotifyController将启动处理通知的过程

use Symfony\Component\HttpFoundation\Response;
use XOne\Bundle\PayuBundle\Http\ClientInterface;

class NotifyController
{
    public function __construct(
        private ClientInterface $client,
    ) {
    }

    public function __invoke(): Response
    {
        $this->client->consumeNotification();

        return new Response();
    }
}

包派发XOne\Bundle\PayuBundle\Event\NotificationEvent事件，在该事件中我们可以访问

• 订单对象；
• 来自PayU的响应；

因此，我们可以连接自己的逻辑来处理这些通知。基本包通过监听器XOne\Bundle\PayuBundle\EventListener\UpdateOrderStatusFromNotification监听此事件，该监听器更新订单状态。

创建退款

要创建PayU中的退款，请创建退款实体并将其传递给客户端HTTP

/**
 * @var XOne\Bundle\PayuBundle\Http\ClientInterface $payuClient
 * @var XOne\Bundle\PayuBundle\Factory\RefundFactoryInterface $payuRefundFactory
 * @var XOne\Bundle\PayuBundle\Model\OrderInterface $payuOrder
 */

$payuRefund = $payuRefundFactory->create($payuOrder);

$payuClient->createRefund($payuRefund);

在传递的订单对象中会填充

• PayU退款标识符；

获取特定订单的退款

要获取特定订单的退款，请向客户端HTTP传递订单对象

/**
 * @var XOne\Bundle\PayuBundle\Http\ClientInterface $payuClient
 * @var XOne\Bundle\PayuBundle\Model\OrderInterface $payuOrder
 */

$payuClient->getOrderRefunds($payuOrder);

在响应中，我们将收到一个XOne\Bundle\PayuBundle\Model\RefundResponse数组，我们可以将其转换/同步到与订单XOne\Bundle\PayuBundle\Model\OrderInterface关联的退款实体XOne\Bundle\PayuBundle\Model\RefundInterface。

包开发

注意：以下所有步骤在发布新版本之前都可以通过单个命令运行

composer run-script pre-commit-checks

测试

确保测试没有错误

vendor/bin/simple-phpunit

质量控制

确保代码格式正确（使用php-cs-fixer），以及PHPStan没有错误

vendor/bin/php-cs-fixer fix
vendor/bin/phpstan analyze

版本控制

为了通过Composer更新包，在将更改合并到主分支后，需要创建格式为vX.Y.Z的标签，例如。

git tag -a v1.1.0 -m "Version v1.1.0"
git push --tags