README

Borica EMV 3DS 是一个 PHP 库，提供了一种更简单的方式来集成新发布的 Borica 协议，称为 EMV 3DS。

该库支持新的 MAC_GENERAL 签名算法，并将在 2023 年 8 月 1 日之后的变化后工作。

0. 要求

待定

• PHP 7.1 或更高版本
• 正确配置的 default_charset php.ini 指令

1. 安装

1.1. 使用 Composer

建议通过运行以下命令通过 composer 进行安装

composer require extreme-bg/borica-emv-3ds "1.*"

或者您可以直接在您的 composer.json 文件的 require 部分手动添加以下内容

"extreme-bg/borica-emv-3ds": "1.*"

2. 使用方法

2.1. 初始化

使用您的私钥和证书创建和配置 Borica。私钥需要您自己生成（有关更多详细信息，请参阅 密码学 部分）。证书（公钥）由 Borica 提供。

$borica = new Borica();
$borica->setPrivateKey('/var/www/certificates/borica.pem') // Absolute file path
    ->setPrivateKeyPassword('<Private Key Password>')
    ->setCertificate('/var/www/certificates/borica.cer') // Absolute file path
    ->setSandboxMode(true)
    ->setSigningAlgorithm(SigningAlgorithm::MAC_GENERAL);

2.2. 创建并发送销售请求 (TRTYPE=1)

目前它只与保加利亚列弗（BGN）一起工作。Borica 正在努力支持欧元（EUR）。

要创建销售请求（电子商务中最常用的一种），请创建和配置 SaleRequest。两者 <МИД> 和 <ТИД> 都是从 Borica 获得的。请检查库源代码以了解所有属性。

请勿忘记使用清洗后的数据而不是原始的 $_POST 数据。

require_once __DIR__ . '/vendor/autoload.php';

use BogdanKovachev\Borica\Borica;
use BogdanKovachev\Borica\SigningAlgorithm;
use BogdanKovachev\Borica\TransactionType;
use BogdanKovachev\Borica\Request\SaleRequest;

$request = new SaleRequest();
$request->setTransactionType(TransactionType::SALE)
    ->setAddendum('AD,TD')
    ->setAmount(100.0)
    ->setCountry('bg')
    ->setCurrency('BGN')
    ->setDescription('Order via 1337.bg')
    ->setEmail('extreme@1337.bg')
    ->setMerchant('<МИД>')
    ->setMerchantName('1337.bg')
    ->setMerchantTimezone('+02')
    ->setMerchantUrl('https://1337.bg')
    ->setNonce(strtoupper(bin2hex(openssl_random_pseudo_bytes(16))))
    ->setOrder(9001)
    ->setOrderIdentifier($request->getOrder() . ' Website')
    ->setTerminal('<ТИД>')
    ->setTimestamp(time())
    ->sign($borica);

您可以使用以下方式选择性地验证所有属性是否正确

if (!$request->validate()) {
    // List all errors
    var_dump($request->getErrors());
}

创建请求后，您需要生成一个 HTML 表单并将用户重定向到 Borica 支付页面。下面是示例实现

<div>
    <p>
        Ще бъдете прехвърлени към страницата за онлайн плащания на БОРИКА през защитена (SSL) връзка.
    </p>

    <p>
        За нареденото от вас плащане, няма да ви бъдат удържани банкови такси.
    </p>
</div>

<div style="display: none;">
    <?= $request->renderForm($borica) ?>
</div>

<script type="text/javascript">
    window.onload = function () {
        window.setTimeout(function () {
            document.getElementById('boricaForm').submit();
        }, 3000);
    };
</script>

2.3. 处理响应

用户在 Borica 支付页面付款后，将被重定向到在 APGW 数据库中为终端定义的 backUrl（请与银行确认该 URL 是否正确设置为终端）。请注意，这并不保证，因为用户可以关闭浏览器或禁用用于重定向的 JavaScript。在这种情况下，请参阅 2.4. 创建状态检查请求。

require_once __DIR__ . '/vendor/autoload.php';

use BogdanKovachev\Borica\Borica;
use BogdanKovachev\Borica\SigningAlgorithm;
use BogdanKovachev\Borica\TransactionType;
use BogdanKovachev\Borica\Response\Response;

$borica = new Borica();
$borica->setPrivateKey('/var/www/certificates/borica.pem') // Absolute file path
    ->setPrivateKeyPassword('<Private Key Password>')
    ->setCertificate('/var/www/certificates/borica.cer') // Absolute file path
    ->setSandboxMode(true)
    ->setSigningAlgorithm(SigningAlgorithm::MAC_GENERAL);

$response = Response::withPost($_POST)->verify($borica);

if (!$response->signatureIsVerified) {
    ...
}

if ($response->isSuccessful()) {
    echo '<h1>Плащането е успешно</h1>';

    ...
} else {
    echo '<h1>Възникна грешка при плащане</h1>';
    echo '<p>Отговор на сървъра: ' . $response->responseCode . ' - ' . $response->responseCodeDescription() . '</p>';
}

2.4. 创建状态检查请求 (TRTYPE=90)

如果您想检查已发送请求的状态，请创建和配置 StatusCheckRequest。《TIД》是从 Borica 获得的。

require_once __DIR__ . '/vendor/autoload.php';

use BogdanKovachev\Borica\Borica;
use BogdanKovachev\Borica\Request\StatusCheckRequest;
use BogdanKovachev\Borica\Response\Response;
use BogdanKovachev\Borica\SigningAlgorithm;
use BogdanKovachev\Borica\TransactionType;

$request = new StatusCheckRequest();
$request->setTransactionType(TransactionType::STATUS_CHECK)
    ->setNonce(strtoupper(bin2hex(openssl_random_pseudo_bytes(16))))
    ->setOrder(9001)
    ->setOriginalTransactionType(TransactionType::SALE)
    ->setTerminal('<ТИД>')
    ->sign($borica);

2.5. 创建反向请求 (TRTYPE=24)

要取消成功的 SaleRequest（TRTYPE=1）或完成的延迟授权（TRTYPE=24），请创建和配置 ReversalRequest。

<RRN> 和 <INT_REF> 在 SaleRequest 的响应中返回，并且每个交易都是唯一的。两者 <МИД> 和 <ТИД> 都是从 Borica 获得的。请检查库源代码以了解所有属性。

require_once __DIR__ . '/vendor/autoload.php';

use BogdanKovachev\Borica\Borica;
use BogdanKovachev\Borica\Request\ReversalRequest;
use BogdanKovachev\Borica\Response\Response;
use BogdanKovachev\Borica\SigningAlgorithm;
use BogdanKovachev\Borica\TransactionType;

$request = new ReversalRequest();
$request->setTransactionType(TransactionType::REVERSAL)
    ->setAddendum('AD,TD')
    ->setAmount(100.0)
    ->setCurrency('BGN')
    ->setDescription('Отмяна на плащане през bulmint.com')
    ->setInternalReference('<INT_REF>')
    ->setMerchant('<МИД>')
    ->setMerchantName('Мебели Дизма')
    ->setNonce(strtoupper(bin2hex(openssl_random_pseudo_bytes(16))))
    ->setOrder(9001)
    ->setOrderIdentifier($request->getOrder() . ' Website')
    ->setRetrievalReferenceNumber('<RRN>')
    ->setTerminal('<ТИД>')
    ->setTimestamp(time())
    ->sign($borica);

3. 密码学

• 使用安全的密码生成私钥

$ openssl genrsa -out borica.key -aes256 2048

• 使用您公司的信息生成代码签名请求 (CSR)

$ openssl req -new -key borica.key -out borica.csr

	Country Name (2 letter code) []:BG
	State or Province Name (full name) []:Plovdiv
	Locality Name (eg, city) []:Plovdiv
	Organization Name (eg, company) []:1337 LTD
	Organizational Unit Name (eg, section) []:V0000000
	Common Name (eg, fully qualified host name) []:1337.bg
	Email Address []:extreme@1337.bg
	A challenge password []: <empty>

• 将 borica.csr 重命名为匹配文件模式 TID_YYYYMMDD.csr 并将其发送到 Borica。使用您的 TIД 和 当前日期（例如 V0000000_20201105.csr）。

• 作为回应，您将从 Borica 收到已签名的证书（borica.cer）和公钥（borica.pub）。

4. 贡献

待定

5. 许可证

Borica EMV 3DS 在 MIT 许可证下发布。