README

比雷埃夫斯银行支付中心组件

安装

步骤 1：下载组件

打开命令行，进入您的项目目录并执行以下命令以下载此组件的最新稳定版本

$ composer require thanpa/paycenter-bundle "1.1"

此命令要求您已全局安装 Composer，如 Composer 文档中的安装章节中所述。

步骤 2：启用组件

然后，将组件添加到项目中 app/AppKernel.php 文件中注册的组件列表中，以启用组件

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...

            new Thanpa\PaycenterBundle\ThanpaPaycenterBundle(),
        );

        // ...
    }

    // ...
}

步骤 3：配置

将以下内容添加到您的 app/config/parameters.yml.dist，无需更改其值
将以下内容添加到您的 app/config/parameters.yml，用银行提供的值替换占位符

    thanpa_paycenter.acquirerId: placeholder-value-change-me
    thanpa_paycenter.merchantId: placeholder-value-change-me
    thanpa_paycenter.posId: placeholder-value-change-me
    thanpa_paycenter.username: placeholder-value-change-me
    thanpa_paycenter.password: placeholder-value-change-me
    thanpa_paycenter.param_back_link: "" # its contents used as a query string in the URL returned to the user when the "Cancel" button is pressed.

将以下代码添加到您的 app/config/routing.yml

# app/config/routing.yml
redirectToBank:
    path:      /order/redirectToBank
    defaults:  { _controller: ThanpaPaycenterBundle:RedirectionPay:redirectToBank }

步骤 4：更新数据库

此组件支持 Doctrine，请运行以下命令

# bin/console for Symfony3
$ app/console doctrine:schema:update --force

如果您正在使用 DoctrineMigrationsBundle，请运行

# bin/console for Symfony3
$ app/console doctrine:migrations:diff
$ app/console doctrine:migrations:migrate

参数

thanpa_paycenter.acquirerId：您的 Acquirer Id（由银行提供）
thanpa_paycenter.merchantId：您的 Merchant Id（由银行提供）
thanpa_paycenter.posId：您的 Pos Id（由银行提供）
thanpa_paycenter.username：您的 API 用户名（由银行提供）
thanpa_paycenter.password：您的 API 密码（由银行提供）
thanpa_paycenter.param_back_link：如果不需要参数，请使用 ""，或添加您的参数：p1=v1&p2=v2。请确保不要以 ? 作为第一个字符。

支付成功/失败页面

请注意，您需要通知银行您的支付成功/失败 URL。请告知他们希望 API 响应被 POST 回到您的网站。

在您的应用程序中创建一个新的控制器，命名为 PaymentController.php。
您需要实现 PaymentResponseInterface 中定义的方法。

您的代码应如下所示

支付成功页面

    public function successAction()
    {
        $service = $this->get('thanpa_paycenter.payment_response');
        $paymentResponse = $service->extract($request);
        
        // your logic here: set order as 'paid', notify customer etc
        
        $this->addFlash('success', $service->getDisplayMessage($paymentResponse));
        // redirect where you need to redirect
    }

支付失败页面

    public function failAction()
    {
        $service = $this->get('thanpa_paycenter.payment_response');
        $paymentResponse = $service->extract($request);

        // your logic here: set order as 'payment failed', email customer etc
        
        $this->addFlash('error', $service->getDisplayMessage($paymentResponse));
        // redirect where you need to redirect
    }

返回链接页面

    public function backlinkAction()
    {
        $service = $this->get('thanpa_paycenter.payment_response');
        $paymentResponse = $service->extract($request);

        // your logic here: actually probably nothing
                
        $this->addFlash('warning', $this->get('translator')->trans('You clicked cancel!'));
        // redirect where you need to redirect
    }

Thanpa\PaycenterBundle\Entity\PaymentResponse 类提供了您可以使用的方法来获取响应信息。

注意

银行要求您将响应持久化到您的系统中以供将来参考（保存在 thanpa_payment_response 表中）
对于成功调用，支付响应服务的 extract 方法还将计算哈希，以确保这是银行的有效响应。

请将以下内容添加到您的 app/config/routing.yml（调整路径和控制器路径以匹配您的应用程序）

payment_success:
    path:      /order/payment/success
    defaults:  { _controller: AppBundle:PaymentController:success }
    methods:   [POST]

payment_fail:
    path:      /order/payment/fail
    defaults:  { _controller: AppBundle:PaymentController:fail }
    methods:   [POST]
    
payment_backlink:
    path:      /order/payment/backlink
    defaults:  { _controller: AppBundle:PaymentController:backlink }
    methods:   [POST]

如何使用此组件

在您的应用程序中，当创建新订单时，您应使用作为订单参考的唯一标识符（通常是一个 5 个字符的字符串）。如果没有订单参考，您也可以使用订单 ID。

步骤 1：将订单对象保存到数据库中

当您的订单创建时，它应保存为“支付待处理”。

步骤 2：从银行的 API 获取新票据

此时应调用票据机制。

// ...

// get ticket issuer service
$issuer = $this->get('thanpa_paycenter.ticket_issuer');
$issuer->setMerchantReference($orderReference); // your unique order identifier

$ticket = $issuer->getTicket();

如果对银行 API 的请求成功，您现在应该在 $ticket 中有一个新的票据，并将其保存在您的数据库中。

步骤 3：将用户重定向到安全的支付环境

在您的控制器中，将用户重定向到 redirectToBank 路由（如之前定义的）

        return $this->redirect(
            $this->generateUrl(
                'redirectToBank', 
                [
                    'languageCode' => 'el-GR',
                    'merchantReference' => $orderReference, // or your unique order/payment identifier 
                ]
            )
        );

此页面将显示一个包含隐藏字段的表单，并自动提交（需要用户启用JavaScript）。表单提交后，用户将被重定向到银行的加密环境以完成支付。

步骤 4：支付成功、失败或取消后，用户将被重定向到您的网站。

如果用户未完成支付并点击“取消”，则将被重定向到您提供给银行的指定URL（此设置在包中不可配置）。
如果支付成功完成，用户将被重定向到您的 payment_success 路由。
如果支付失败，用户将被重定向到您的 payment_fail 路由。
如果用户点击“取消”，则用户将被重定向到您的 payment_backlink 路由。

注意：我强烈建议您阅读银行的API手册，以全面了解其工作原理。

如何运行测试

您需要在系统上安装phpunit。

$ phpunit --testsuite PaycenterBundle

您可以根据需要修改 phpunit.xml.dist 文件。默认情况下，代码覆盖率日志将生成在 build/ 目录下。

thanpa / paycenter-bundle

维护者

详细信息