README

用PHP编写的简单统一的面向对象库，用于斯洛伐克银行和金融机构提供的电子商务服务。

CardPay，可选添加ComfortPay服务 -- Tatra banka, a.s.
TatraPay -- Tatra banka, a.s.
ePlatby VÚB -- VÚB, a.s.
VÚB eCard -- VÚB, a.s.
SporoPay -- Slovenská sporiteľna, a.s.
iTerminal -- Poštová banka, a.s.
GP webpay -- Global Payments Europe, s.r.o.
TrustCard -- TrustPay, a.s.
PayPal -- PayPal (Europe) S.à r.l. et Cie, S.C.A.
BenefitPlus -- Benefit Management s.r.o.

库的当前版本为v0.23.0，需要PHP 5.4或PHP 7+才能运行。尽管还有一些需要改进的地方，但它已经在生产中使用而没有任何问题。

Chaching库是开源软件，采用MIT许可。

设置和安装

安装库的推荐方法是使用composer，并将其作为依赖项添加到项目的composer.json文件中。

{
  "require": {
    "backbone/chaching": "0.23.1"
  }
}

之后，运行以下命令进行安装

$ composer install

用法

库遵循PSR-0命名约定，安装后可在其自己的命名空间\Chaching下使用。基本设置包括以下内容

use Chaching\Chaching;

$driver        = Chaching::CARDPAY;
$authorization = [ 'merchant_id', 'password' ];
$options       = [];

$chaching = new Chaching($driver, $authorization, $options);

如介绍中已提到的，目前支持八种不同的支付方式，每种方式都有自己的驱动常量：Chaching::CARDPAY、Chaching::TATRAPAY、Chaching::TRUSTPAY、Chaching::EPLATBY、Chaching::ECARD、Chaching::PAYPAL、Chaching::GPWEBPAY、Chaching::ITERMINAL、Chaching::ITERMINAL2和Chaching::BENEFITPLUS。

在Chaching::GPWEBPAY的情况下，使用关联数组代替密码，认证信息如下

$authorization = [
  'merchant_id', [
    'key'         => '...../gpwebpay.crt',
    'passphrase'  => 'passphrase',
    'certificate' => '...../gpwebpay.key'
  ]
];

需要根据GP webpay的文档创建公钥和私钥。

在Chaching::ITERMINAL或Chaching::ITERMINAL2的情况下，也使用关联数组

$authorization = [
  NULL, [
    'keystore'  => '...../iterminal.pem',
    'password'  => 'password'
  ]
];

前面提到的空$options数组目前可能包含以下键

ecdsa_keys_file - Tatra银行ECDSA密钥的绝对文件路径（仅在CardPay和TatraPay中使用HMAC消息签名时使用）
沙盒 - 在与银行或金融机构通信时，您希望使用沙盒URL还是生产URL？默认值为 FALSE。由于沙盒的限制，它仅适用于 Chaching::TRUSTPAY、Chaching::ECARD、Chaching::PAYPAL、Chaching::GPWEBPAY、Chaching::ITERMINAL、Chaching::ITERMINAL2 和 Chaching::BENEFITPLUS（如果此处未列出，即使处于沙盒模式，也将使用生产URL）。

之后，我们需要为外部服务创建一个包含有关付款特定信息的请求。

$payment = $chaching->request([
	'currency'        => \Chaching\Currencies::EUR,

	'variable_symbol' => 70000000,
	'amount'          => 9.99,
	'description'     => 'My wonderful product',
	'constant_symbol' => '0308',
	'return_email'    => '...',
	'callback'        => 'http://...'
]);

通过在下一个代码块中运行 process 方法，我们返回（当 $auto_redirect 设置为 FALSE）用户将进行付款的重定向URL。

（请注意，对于 Chaching::ITERMINAL 或 Chaching::ITERMINAL2，$auto_redirect 将永远不会起作用，因为提供的交易标识符在之后是严格必需的。只有在成功创建交易之后，您才能使用重定向URL。有关更多信息，请参阅银行的文档。）

try
{
	$redirect_url = $payment->process($auto_redirect = FALSE);
}
catch (\Chaching\Exceptions\InvalidOptionsException $e)
{
	// Missing or incorrect value of some configuration option.
}
catch (\Chaching\Exceptions\InvalidRequestException $e)
{
	// General error with authentication or the request itself.
}

还记得请求选项中的 callback 键吗？它是一个绝对URL，银行服务在付款完成后将重定向到该URL。Chaching 还具有帮助处理响应、检查其有效性等的方法。但是，如果您正在使用 Chaching::ITERMINAL（或 Chaching::ITERMINAL2）的驱动程序，则不需要提供回调，因为它已在银行提供的商户中心中设置。

try
{
	$payment = $chaching->response($_REQUEST);

	if ($payment->status === \Chaching\TransactionStatuses::SUCCESS)
	{
		// Wohoo, we've got the money!
	}
	elseif ($payment->status === \Chaching\TransactionStatuses::TIMEOUT)
	{
		// Special type that is only returned by TatraPay service. In general
		// it's a good idea to check for it nonetheless.
	}
	else
	{
		// Failure, the user cancelled, the payment got rejected or the payment pending.
	}
}
catch (\Chaching\Exceptions\InvalidResponseException $e)
{
	// General error with authentication or the response itself.
}

TrustPay 是一个特殊情况，因为它们使用类似于 PayPal 的 IPN 的通知机制来告知您付款的状态。在这种情况下，我们使用类似处理响应的方法使用通知方法。

try
{
	$payment = $chaching->notification($_GET);

	// And now we can check the $payment->status and do what's appropriate.
}
catch (\Chaching\Exceptions\InvalidResponseException $e)
{
	// General error with authentication or the response/notification itself.
}

您还可以使用 notification 方法与 SporoPay 及其向账户发送的邮件通知一起使用。它们不会在用户从 SporoPay 的界面中重定向浏览器时同时到达，这仅仅是检查付款状态的一种冗余方式，以防事情没有按计划进行。（对于 Tatra banka 的 CardPay 和 TatraPay 服务也是如此，但在这些情况下，您只需使用 response 即可。）

当使用 Poštová banka 的 iTerminal 服务、Tatra banka 的 CardPay 服务或 Benefit Plus 服务时，有部分或全额退款已成功完成的付款的选项。Poštová banka 和 Benefit Plus 支持每笔交易只能退款一次，而对于 CardPay，您可以按照您喜欢的步骤进行退款，直到所有退款的总金额达到原始交易金额。

try
{
	$payment = $chaching->refund([
		'transaction_id' => '...',
		'amount'         => 1.00,
		'currency'       => \Chaching\Currencies::EUR
	]);

	// Check $payment->status and do what's appropriate.
}
catch (\Chaching\Exceptions\ChachingException $e)
{
	// General error with authentication, request or bank's response.
}

付款状态可以是 TransactionStatuses::REVERSED、TransactionStatuses::SUCCESS 或 TransactionStatuses::FAILURE 之一。前两者表示付款已成功退款。

支持支付机构的多种服务中最新增加的是检查 Tatra banka 的 TatraPay 服务是否可用并接受请求的功能。

use \Chaching\Chaching;
use \Chaching\ServiceStatuses;

$authorization = [ 'merchant_id', 'password' ];
$chaching = new Chaching(Chaching::TATRAPAY, $authorization);

try
{
	$status = $chaching->status();

	if ($status->status === ServiceStatuses::ONLINE)
	{
		// TatraPay is alive and well!
	}
}
catch (\Chaching\Exceptions\ChachingException $e)
{
	// General error with authentication, request or bank's response.
}

请在这里对 PayPal 表示敬意：请将即时支付通知（IPNs）的字符编码设置为 UTF-8。转到您的 PayPal 个人资料，点击侧边栏中的“我的销售工具”，滚动到页面底部并点击“PayPal 按钮语言编码”，点击“更多选项”并将编码设置为 UTF-8。这将为您节省很多痛苦。

贡献

查找开放问题或为新功能请求或错误创建新问题。
对存储库进行分支并修改主分支（或从其分支）。
发送拉取请求

TODO

为了发布库的 v1.0 正式代码，需要有一个更全面的教程来解释其用法以及完整的测试。

backbone / chaching

维护者

详细信息

README

设置和安装

用法

贡献

TODO