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。 <ТИД>从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许可证的许可。