README

此扩展提供了与 Comgate 交互的基本接口。

安装

下载

安装 snugcomponents/comgate 的最佳方式是使用 Composer

$ composer require snugcomponents/comgate

注册和设置

您可以使用 neon 配置文件启用和配置此扩展

extensions:
	comgate: Snugcomponents\Comgate\SnugcomponentsComgateExtension

comgate:
	eshopIdentifier: %comgate.eshopIdentifier%
	password: %comgate.password%
	cacheTime: '2 hours' # unrequired

简单使用

首先，您需要创建一个付款并将其发送到 Comgate。然后，Comgate 会返回用于重定向或 iframe 的 URL。

class BasePresenter extends Nette\Application\UI\Presenter
{
    #[Inject] public Snugcomponents\Comgate\PaymentFactory $paymentFactory; // Required for creating payment
    #[Inject] public Snugcomponents\Comgate\Client $comgateClient;          // Required for sending payment to Comgate

    public function actionComgateCreatePayment(): void
    {
        $payment = $this->paymentFactory->create(   // For explanation of arguments see Comgate official documentation.
            price: 5000,
            curr: 'CZK',
            label: 'Měsíční licence',
            refId: date('Ym') . 'U' . $this->user->getId(),
            email: $this->user->getIdentity()->getData()['email'],
            prepareOnly: true,
            method: 'ALL',
            initRecurring: false,
            test: !Debugger::$productionMode,
            country: 'CZ',
            //account: 'afes',
            phone: $this->user->getIdentity()->getData()['phone'] ?? null,
            name: 'Měsíční licence',
            eetReport: false,
            eetData: '{}',
            preauth: false,
            lang: 'cs',
            verification: false,
            embedded: false,
            applePayPayload: null,
        );

        $redirectUrl = $this->comgateClient->createPayment($payment);   // Creating payment. It sends payment to Comgate server and returns URL.

        $this->redirectUrl($redirectUrl); // Redirect to received URL.
    }
}

然后，您需要 API 端点，当付款完成后，Comgate 会调用此端点以获取付款结果。

class BasePresenter extends Nette\Application\UI\Presenter
{
    #[Inject] public PaymentSaver $comgatePaymentSaver;     // Required for processing comgate request for our API endpoint
	
    public function actionPaymentConfirm(): void
    {
        try{
            $this->comgatePaymentSaver->confirm();  // This will do all the stuff.
        } catch (Exception $e) {
            // Please log the error and request. May be hack.
            $this->getHttpResponse()->setCode(IResponse::S400_BAD_REQUEST);
        }
        die();
    }
}

这还不是全部。您还需要实现一些接口。首先是 Snugcomponents\Comgate\Providers\PaymentResponseManipulator。

interface PaymentResponseManipulator
{
    /**
     * Is responsible for saving response from Comgate. 
     * When you implement the creating payment and Comgate returns result,
     * then the result is forced to save via this method.
     * You need to save it somewhere save. 
     */
    public function savePaymentResponse(PaymentResponse $paymentResponse): void;
    /**
     * This method is called automatically, when is triggered confirmation of payment
     * by ComgatePaymentSaver. It is needed because of integrity of data.
     * @param string $transId This is unique identifier of PaymentResponse.
     */
    public function getPaymentResponse(string $transId): PaymentResponse;
}

其次是 Snugcomponents\Comgate\Providers\ComgatePaymentConfirm。

interface ComgatePaymentConfirm
{
    /**
     * After successfully confirmed integrity of data from ComgatePaymentSaver, this method is called.
     * Inside parameter you have all the data, which comgate provides and their integrity is confirmed.
     * You can do with that data whatever you want, 
     * but we are recommended to save information about that the payment was proceeded.
     */
    public function confirm(PaymentConfirmRequestDataProvider $paymentConfirmRequestDataProvider): void;
}

周期性付款

当您需要使用周期性付款时，您需要实现另一个接口 Snugcomponents\Comgate\Providers\RecurringPaymentResponseManipulator。

interface RecurringPaymentResponseManipulator
{
    public function saveRecurringPaymentResponse(RecurringPaymentResponse $recurringPaymentResponse): void;
}

此接口旨在保存关于周期性付款的信息。以下步骤是周期性付款正常工作的必要条件：（下面将详细介绍各个步骤）

1. 用户将创建一个经典的付款，但将 $initRecurring 设置为 true。
2. 应用程序将保存此次付款的 $transId。重要的是，此值在任何情况下都不得被覆盖，除非您取消周期性付款。
3. 当您需要执行周期性付款时，应用程序或用户将创建 Snugcomponents\Comgate\RecurringPayment 类的实例。此类需要一个参数 $initRecurringId，它是前面步骤中的 $transId。
4. 应用程序必须使用 Snugcomponents\Comgate\Client::doRecurringPayment 方法将此实例发送到 Comgate 服务器。
5. 前面的步骤将自动调用 RecurringPaymentResponseManipulator::saveRecurringPaymentResponse 方法。
6. 如果您想取消周期性付款，只需删除步骤 2 中的 $transId。

步骤 1 和 2 在“简单使用”部分中有描述，步骤 5 和 6 对每个实现都不同。步骤 3 和 4 应该如下所示：

class BasePresenter extends Nette\Application\UI\Presenter
{
    #[Inject] public Snugcomponents\Comgate\RecurringPaymentFactory $recurringPaymentFactory; // Required for creating payment
    #[Inject] public Snugcomponents\Comgate\Client $comgateClient;          // Required for sending payment to Comgate

    public function actionComgateDoRecurringPayment(string $initRecurringId): void
    {
        $payment = $this->recurringPaymentFactory->create(   // This is step 3. For explanation of arguments see Comgate official documentation.
            price: 5000,
            curr: 'CZK',
            label: 'Měsíční licence',
            refId: date('Ym') . 'U' . $this->user->getId(),
            email: $this->user->getIdentity()->getData()['email'],
            prepareOnly: true,
            initRecurringId: $initRecurringId, // This variable can be loaded from database etc...
            test: !Debugger::$productionMode,
            country: 'CZ',
            //account: 'afes',
            phone: $this->user->getIdentity()->getData()['phone'] ?? null,
            name: 'Měsíční licence',
            eetReport: false,
            eetData: '{}',
        );

        $this->comgateClient->doRecurringPayment($payment);   // This is step 4. Do recurring payment. It sends payment to Comgate server and forces saving of response.
    }
}

在周期性付款中，没有重定向，因此没有确认端点。付款在后台完成，所以付款结果立即由 Comgate 的响应转发，并通过步骤 5 强制保存。

这就结束了。祝您使用愉快。

结论

此扩展需要 PHP8.1 和 Nette3.1，并归 SnugDesign 所有 © 2021