README

MLocati 的 PHP 不官方 BCC PayWay (IGFS Buy Now) 客户端库

此不官方的 PHP 库可以帮助您使用 BCC (Banca di Credito Cooperativo) PayWay 接受支付，这是一个由 IGFS (Internet Gateway Financial Systems) Buy Now 服务提供支持的服务。

它支持任何 PHP 版本，从 PHP 5.5 到最新的 PHP 版本（目前为 8.2）。

接收支付示例用法

初始化

如果您想为客户接受 123.45 欧元的支付，您首先需要初始化此过程

use MLocati\PayWay\Init\Request;
use MLocati\PayWay\Dictionary\TrType;
use MLocati\PayWay\Dictionary\Currency;
use MLocati\PayWay\Dictionary\Language;

$request = new Request();
$request
    // Set your terminal ID
    ->setTID('YourTerminalID')
    // Set an unique identifier (of your choiche) of the transaction
    ->setShopID('Order987Attempt1')
    // Set your customer's email address (a notification email will be sent to this address)
    ->setShopUserRef('customer@email.com')
    // The user have to pay, without any back office authorization
    ->setTrType(TrType::CODE_PURCHASE)
    // You can also call setAmountAsCents(12345), which accepts integer numbers instead of floating point numbers
    ->setAmountAsFloat(123.45)
    // Set the currency: for the list of available currencies, use Currency::getDictionary()
    ->setCurrencyCode(Currency::CODE_EUR)
    // Set the language to be displayed to the customer when filling-in the data: for the list of available language, use Language::getDictionary()
    ->langID(Language::CODE_ITALIAN)
    // The page where the customer will be redirected to once your customer will have paid
    ->setNotifyURL('https://your.domain/process-completed?shopID=Order987Attempt1')
    // A page to be called in case of technical issues (please remark that if the transaction failed, the customer will be still redirected to the notifyURL page)
    ->setErrorURL('https://your.domain/whoops')
    // An optional page for Server2Server calls: it will receive a POST request with the transaction details
    ->setCallbackURL('https://your.domain/process-completed')
;

接下来，您需要将初始化请求发送到您的银行网站服务器

use MLocati\PayWay\Client;
use MLocati\PayWay\Dictionary\RC;

$client = new Client(
    'https://your.bank.com/UNI_CG_SERVICES/services',
    'Your kSig digital signature'
);

$response = $client->init($request);

if ($response->getRc() !== RC::TRANSACTION_OK || $response->isError() || $response->getRedirectURL() === '') {
    throw new \Exception('Transaction failed: ' . $response->getErrorDesc());
}

此时，您将获得成功的初始化响应。您需要存储 $response->getPaymentID() 的结果以供以后使用（例如，在数据库表中）。

客户互动

现在您可以重定向您的客户到外部支付页面

header('Location: ' . $response->getRedirectURL());

在结果页面上，客户将填写带有他们的信用卡数据的表单。

验证交易结果

一旦客户完成支付（或取消支付），他们将返回到您的网站，在通知 URL 指定的页面。

在通知 URL 页面上，您然后需要检查支付交易的结果。

您可能想要使用以下类似的东西

use MLocati\PayWay\Verify\Request;
use MLocati\PayWay\Dictionary\RC;

$shopID = isset($_GET['shopID']) && is_string($_GET['shopID']) ? $_GET['shopID'] : '';
$paymentID = retrieveStoredPaymentID($shopID);
if ($paymentID === '') {
    throw new \Exception('Unexpected shopID parameter');
}
$request = new Request();
$request
    // Set your terminal ID
    ->setTID('YourTerminalID')
    // Set the unique identifier of the transaction
    ->setShopID($shopID)
    // Set the remote server-assigned payment ID
    ->setPaymentID($paymentID)
;

$response = $client->verify($request);

if ($response->getRc() !== RC::TRANSACTION_OK || $response->isError()) {
    throw new \Exception('Transaction failed: ' . $response->getErrorDesc());
}

服务器到服务器通信（回调 URL）

如果在初始化过程中您配置了回调 URL，您可以使用以下类似代码检查收到的参数

use MLocati\PayWay\Server2Server\RequestData;

$request = Server2Server\RequestData::createFromGlobals();

并且您可以检查 $request 包含的内容以验证交易结果（与上面相同的过程）。