README

BKM Express 是土耳其的一个简单快捷的支付系统，它允许在线支付而无需提供完整的信用卡信息，因此这个库为你提供了一个简单的 API。

## 注意：目前正在进行此项目。文档尚未完成。

安装

您可以通过 Composer 简单地安装此库。

首先，将此行添加到您的 composer.json

{
    "require": {
        "travijuu/bkm-express": "1.0.3"
    }
}

然后运行 composer update 命令。

BKM Express 的支付步骤

进行支付交易有四个步骤。

初始化支付 - 准备您的数据（银行、分期付款、支付选项等），发送给 BKM Express，从 BKM Express 获取结果，并在验证后向 BKM 发送 POST 请求。
请求商户信息 - BKM 根据客户的信用卡选择向您发出 SOAP 请求以获取您的虚拟 POS 信息。
成功/取消 URL - 当 BKM Express 获取您的虚拟 POS 信息时，它会代替您向定义的银行发出支付交易请求。根据交易结果，它将向成功或取消 URL 发出另一个请求。
确认 URL - 除了成功/失败 URL 请求外，BKM Express 还会向您的确认 URL 发出另一个请求。此请求与成功/失败请求相同，因此它是额外的请求，以确保防止在成功/失败请求失败时数据丢失。

基本用法

让我们从第一步开始。

初始化支付

use Travijuu\BkmExpress\BkmExpress;
use Travijuu\BkmExpress\Common\Bank;
use Travijuu\BkmExpress\Common\Bin;
use Travijuu\BkmExpress\Common\Installment;

$mid              = '7b928290-b6d2-469e-ac10-29eb36b8c1f6'; // BKM Merchant ID
$successUrl       = 'https://example.com/bkm/success';
$cancelUrl        = 'https://example.com/bkm/error';
$privateKeyPath   = '/path/to/mykey.pem';
$publicKeyPath    = '/path/to/mykey.pub';
$bkmPublicKeyPath = '/path/to/bkm.pub';
// Infrastructure of the bank you choose as a default payment gateway. 
// ['Posnet', 'NestPay', 'Gvp'] one of them should be chosen.
$defaultBank      = 'NestPay';

$bkm = new BkmExpress($mid, $successUrl, $cancelUrl, $privateKeyPath, $publicKeyPath, $bkmPublicKeyPath, $defaultBank);

$wsdl    = '/path/to/BkmExpressPaymentService.wsdl';
$sAmount = 100.50; // Sale Amount
$cAmount = 4.50; // Cargo Amount
$banks   = [];

$bank        = new Bank('0062', 'Garanti Bank', 'Garanti Bank via BKM Express');
$bin         = new Bin('554960');
$installment = new Installment($cAmount, $sAmount, 1, 'Garanti Bank without installment', true);
$bin->addInstallment($installment);
$installment = new Installment($cAmount, $sAmount, 3, 'Garanti Bank with 3 installments', true);
$bin->addInstallment($installment);

$bank->addBin($bin);
$banks[] = $bank;

$response = $bkm->initPayment($wsdl, $sAmount, $cAmount, $banks);

然后，通过将页面重定向到 BKM Express，使用 3 个参数通过 POST 请求到 $response->getUrl()

[
    't'  => $response->getToken(),
    's'  => $response->getSignature(),
    'ts' => $response->getTimestamp()
]

另一种 POST 请求的方式。（但并不推荐）

<form name="bankexpresspayForm" id="bankexpresspayForm" action="<?php echo $response->getUrl(); ?>" method="POST">
    <input type="hidden" name="t"  value="<?php echo $response->getToken(); ?>">
    <input type="hidden" name="ts" value="<?php echo $response->getSignature(); ?>">
    <input type="hidden" name="s"  value="<?php echo $response->getTimestamp(); ?>">
    <!-- To support javascript unaware/disabled browsers -->
    <noscript>
        <center>
            Eğer yönlenme olmazsa lütfen tıklayınız.<br>

        </center>
    </noscript>
</form>

<script type="text/javascript">
    setTimeout(function(){
        $('#bankexpresspayForm').submit(); 
    },500);
</script>

完成此步骤后，您应该被重定向到 BKM Express 网站。

一旦客户登录到系统，可用的信用卡将被列出。因此，客户可以看到在初始化支付请求中发送的所有分期付款选项。

在信用卡选择后，将从客户处请求一个 SMS 密码。

在下一步中，BKM Express 将向您的应用程序发出 SOAP 请求，以获取与客户选择的卡片相关的银行 API 信息（请求商户信息）

请求商户信息

重要：您应该向 BKM Express 客户服务声明一个 webservice url。

因此，BKM Express 将向此 URL 发出 SOAP 请求，从您的服务器获取银行 API 信息。

use Travijuu\BkmExpress\Common\VirtualPos;
use Travijuu\BkmExpress\Payment\RequestMerchInfo\RequestMerchInfoWSRequest;

$wsdlServer     = '/path/to/RequestMerchInfoService_latest.wsdl';
$virtualPosList = [];

$virtualPos = new VirtualPos();
$virtualPos->setPosUrl('https://sanalposprovtest.garanti.com.tr/VPServlet')
    ->setPosUid('600218');
    ->setPosPwd('123qweASD');
    ->setMpiUrl('https://sanalposprovtest.garanti.com.tr/servlet/gt3dengine')
    ->setMpiUid('600218')
    ->setMpiPwd('123qweASD')
    ->setMd('')
    ->setXid('')
    ->setCIp('192.168.0.1')
    ->setExtra('{"terminalprovuserid":"PROVAUT", "terminalmerchantid":"7000679", "storekey":"12345678", "terminalid":"30690168"}')
    ->setIs3ds(false)
    ->setIs3dsFDec(false);

// Garanti Bank Id: 0062
$virtualPosList['0062'] = $virtualPos;

/* This callback can help you to be informed what kind of
 * payment method is selected in BKM Express website. 
 * You may insert this into database for info purposes.
 * Note: This is optional.
 */
$callback = function(RequestMerchInfoWSRequest $request) {
    $token       = $response->getToken();
    $bankId      = $response->getBankId();
    $installment = $response->getInstallment();
    ...
}

$bkm->requestMerchInfo($wsdlServer, $virtualPosList, $callback);

此请求的结果将返回给 BKM Express，并且它将使用您的银行 API 信息进行银行交易。之后，BKM Express 将根据银行交易的结果（成功 / 取消 URL）发出 POST 请求。

成功/取消 URL

BKM Express 将向成功 URL（https://example.com/bkm/success）或取消 URL（https://example.com/bkm/error）发出 POST 请求。您需要获取 POST 数据并将其传递到确认函数中

注意： https://example.com/bkm/success/{orderCode} 您可以使用您的成功 URL 如此，这样可以帮助您了解您正在尝试支付哪个订单。

// This part can be used in both success and cancel url. $confirmation->success() will return the result.
$data = $_POST;
$confirmation = $bkm->confirm($data);

if ($confirmation->isSuccess()) {
    // remember the callback which I decribed above. If you save $token, $bankId, $installment into your database, now you can use them to identify the posResponse. 
    $token       = $confirmation->getToken();
    $bankId      = '0062'; // get the bank Id from database according to token
    $posResponse = $bkm->getPosResponse($bankId, $confirmation->getPosRef());
    
    // This means that bank transcation is successfully completed so you got the money
    // now you can save the success result to your database.
    if ($posResponse->isSuccess()) {
        $authCode    = $posResponse->getAuthCode();
        $rawResponse = $posResponse->getRawResponse();
        ...
    } else {
        // Transaction failed so get the error message and code
        $errorCode    = $posResponse->getResponseCode();
        $errorMessage = $posResponse->getResponseMessage();
        ...
    }
}

确认 URL

除了 成功 URL 之外，BKM Express 还会为此 POST 请求发出到您的确认 URL，以防万一。他们认为发送到 成功 URL 的请求可能无法到达。

重要：您应该向 BKM Express 客户服务声明确认 URL。

$data = $_POST;
$confirmation = $bkm->confirm($data);

/* You can use the same methodology as above. 
 * Save $token, $bankId, $installment into your database, 
 * now you can use them to identify the posResponse. (Garanti, YKB, Akbank, etc..)
 */
$token       = $confirmation->getToken();
$bankId      = '0062'; // get the bank Id from database according to token
$posResponse = $bkm->getPosResponse($bankId, $confirmation->getPosRef());

待办事项

将添加协议。

贡献

如果您有任何建议，请随时在此GitHub上创建一个问题，或者fork此仓库，进行修改并提交一个pull请求！

travijuu / bkm-express

维护者

详细信息