Simple and unified object-oriented library written in PHP for e-commerce services offered by Slovak banks and financial institutions.
-
CardPay with optional addition for ComfortPay service -- 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.
The current version of the library is v0.15.0 and requires PHP 5.4 or PHP 7 to work. Even though there are things to make better, it is already being used in production without any sort of problems.
Chaching library is open-sourced software licensed under the MIT license.
The recommended way to install the library is to use composer and add it as a dependency to your project's composer.json file.
{
"require": {
"backbone/chaching": "0.15.0"
}
}
After that, run the following command to perform the installation:
$ composer install
The library follows the PSR-0 convention of naming classes and after installing is available under its own namespace \Chaching. Basic setup includes the following:
use Chaching\Chaching;
$driver = Chaching::CARDPAY;
$authorization = [ 'merchant_id', 'password' ];
$options = [];
$chaching = new Chaching($driver, $authorization, $options);
As already mentioned in the introduction, currently there are eight different payment methods that are supported with each having it's own driver constant: Chaching::CARDPAY, Chaching::TATRAPAY, Chaching::TRUSTPAY, Chaching::EPLATBY, Chaching::ECARD, Chaching::PAYPAL, Chaching::GPWEBPAY and Chaching::ITERMINAL.
In case of Chaching::GPWEBPAY use an associated array instead of password, so authentication information would look like this:
$authorization = [
'merchant_id', [
'key' => '...../gpwebpay.crt',
'passphrase' => 'passphrase',
'certificate' => '...../gpwebpay.key'
]
];
Public and private key needs to be created according to GP webpay's documentation.
And in case of Chaching::ITERMINAL use an associated array as well:
$authorization = [
NULL, [
'keystore' => '...../iterminal.pem',
'password' => 'password'
]
];
Afterwards, we need to create a request for the external service with specific information about the payment.
$payment = $chaching->request([
'currency' => \Chaching\Currencies::EUR,
'variable_symbol' => 70000000,
'amount' => 9.99,
'description' => 'My wonderful product',
'constant_symbol' => '0308',
'return_email' => '...',
'callback' => 'http://...'
]);
By running the process method in the next code block, we are getting back (when $auto_redirect is set to FALSE) the URL to redirect the user to, where the user will make the payment.
(Note that with Chaching::ITERMINAL the $auto_redirect will not ever work as the transaction identifier that is provided for you is strictly needed for thereafter. Only after you succesfully create the transaction you can use the redirection URL. For more information read bank's documetation.)
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.
}
Remember the callback key in the request options? It is an absolute URL that the banking service will redirect to upon completion of the payment. Chaching also has methods to help with handling the response, checking it's validity, etc. However, if you are running with Chaching::ITERMINAL's driver, you do not need to provide a callback as it is set in the merchant's centre provided by the bank.
try
{
$payment = $chaching->response($_REQUEST);
if ($payment->status === \Chaching\Statuses::SUCCESS)
{
// Wohoo, we've got the money!
}
elseif ($payment->status === \Chaching\Statuses::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 is a special case with response handling as they use notification mechanism similar to PayPal's IPN to let you know the status of the payment. In that case, in similar fashion to handling responses we use the notification method.
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.
}
When using Poštová banka's iTerminal servie, there is an option of refunding part or full payment that has been successfuly completed before.
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.
}
- Check for open issues or open a new issue for a feature request or a bug.
- Fork the repository and make your changes to the master branch (or branch off of it).
- Send a pull request
To release v1.0 code of the library needs to have a more thorough tutorial to explain it's usage as well as complete tests.
Added support for Poštová banka's iTerminal serice for accepting payments as well as refunding them.
Adds default saving of PayPal's transaction identifier to transaction_id on notification object.
Fixes inability to verify CardPay's signatures when set to receive RC attribute.
Adds ability to read card expiration date when using VÚB eCard and bank's transaction numbers with eCard and CardPay services.
Fixes problem with older CardPay's encryption Aes256 and Des methods, when the response from bank does not conatin TID (external transaction idenfitifer).
Fixes signature verification in TatraPay's transactions that include constant symbol.
Added support for HMAC encoding required from all new clients to Tatra banka's CardPay and TatraPay services along with ECDSA message signing (for the signing to work correctly, openssl PHP extension is required).
Fixes minor issue for handling empty "merchant data" field with GP webpay payment method.
Added support for GP webpay. The difference is that it does not use a shared_key, but set of private / public keys generated according to their documentation, so an associated array with certificate, key and passphrase keys needs to be provided as the second argument to the constructor of Chaching object.
Send automatically optional encoding attribute to VÚB eCard service to fix for default turkish encoding on payment gateway.
Added support for PayPal through "Buy now" payment buttons along with Instant Payment Notification checking.
If client requests email notification after a payment when using ComfortPay, always request also the longer notification with CID (card identifier). Just as well, if REM (return email) attribute is present with a valid value TEM will be set automatically.
Fixes support for Tatra banka's ComfortPay registration.
Added support for AES256 message hashing for Tatra banka's TatraPay and CardPay service. Missing mcrypt support in PHP throws MissingDependencyException.
Added support for VÚB eCard service (VÚB, a.s.).
Minor changes concerning input of the bank response.
Adds support for ComfortPay transactions using CardPay driver.
Shorten the name accroding to the specification when using CardPay driver.
Small fixes for incorrect initialization of ePlatby payment service and their specific symbol policy that depends on the contract with the bank.
Small fixes for currency compatibility problems with TatraPay service.
Added initial support for SporoPay – online service (Slovenská sporiteľňa, a.s.).
Fail silently when passing arguments that are not supported by particular payment method without throwing InvalidOptionsException.
Further documentation and some minor fixes.
Added support for TrustCard service (TrustPay) according to Merchant Integration Manual v2.0.
Fixes in this release:
- Fixed diacritics handling of CardPay services.
- TatraPay does not require
NAMEandSSfield when creating a payment request anymore - Code documentation rewritten to English.
First version of the Chaching library with support for CardPay and TatraPay services (Tatra banka, a.s.) and ePlatby VÚB (VÚB, a.s.).
© 2016 BACKBONE, s.r.o.