README

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

0. 要求

TBD

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

1. 安装

1.1. 使用 Composer

建议通过运行 composer 进行安装

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

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

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

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);

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

目前它仅适用于保加利亚列弗（BGN）。Borica 正在开发对欧元（EUR）的支持。

要创建销售请求（电子商务中最常用的一种），请创建和配置 SaleRequest。两者 <МИД> 和 <ТИД> 均来自 Borica。请检查库的源代码以获取所有属性的详细信息。

不要忘记使用清洗过的数据而不是原始的 $_POST 数据。

$request = new SaleRequest();
$request->setTransactionType(TransactionType::SALE)
    ->setAmount(100.0)
    ->setCurrency('BGN')
    ->setOrder(9001)
    ->setDescription('Order via 1337.bg')
    ->setMerchantName('1337.bg')
    ->setMerchantUrl('https://1337.bg')
    ->setMerchant('<МИД>')
    ->setTerminal('<ТИД>')
    ->setEmail('extreme@1337.bg')
    ->setCountry('bg')
    ->setMerchantTimezone('+02')
    ->setTimestamp(time())
    ->setNonce(strtoupper(bin2hex(openssl_random_pseudo_bytes(16))))
    ->setOrderIdentifier($request->getOrder() . ' Website')
    ->setAddendum('AD,TD')
    ->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. 创建状态检查请求。

$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);

$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。《蒂德》从 Borica 获取。

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

2.5. 创建撤销请求 (TRTYPE=24)

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

<RRN> 和 <INT_REF> 在 SaleRequest 的响应中返回，每个交易都是唯一的。两者 <МИД> 和 <蒂德> 均来自 Borica。请检查库的源代码以获取所有属性的详细信息。

$request = new ReversalRequest();
$request->setTransactionType(TransactionType::REVERSAL)
    ->setAmount(100.0)
    ->setCurrency('BGN')
    ->setOrder(9001)
    ->setMerchant('<МИД>')
    ->setTerminal('<ТИД>')
    ->setTimestamp(time())
    ->setNonce(strtoupper(bin2hex(openssl_random_pseudo_bytes(16))))
    ->setRetrievalReferenceNumber('<RRN>')
    ->setInternalReference('<INT_REF>')
    ->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。使用您的 蒂德 和 当前日期（例如 V0000000_20201105.csr）。

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

4. 贡献

TBD

5. 许可证

Borica EMV 3DS 根据 MIT 许可证授权。