Download the PHP package backbone/cheddar without Composer
On this page you can find all versions of the php package backbone/cheddar. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package cheddar
Cheddar Bindings for PHP
A PHP wrapper for Cheddar's application interface. Cheddar is a payment gateway for processing and executing transactions within a neat and universal API.
At the moment, the following payment methods and services are supported by Cheddar and this library:
- 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.
To see what is new or changed in the current version, check out the changelog.
Requirements
Cheddar requires PHP version 5.4.0 or greater (including PHP 7) with json
, hash
and cURL
extensions installed.
If you use Composer, these dependencies should be handled automatically. If you install manually, you'll want to make sure that these extensions are available.
Setup and installation
Composer
The recommended way to install the library is to use Composer and add it as a dependency to your project's composer.json
file.
Then to use the bindings, use Composer's autoload:
Manual installation
If you do not wish to use Composer, you can download the latest release. Then, to use the library, include the init.php
file.
Usage
First off, you need to require the library and provide authentication information by providing your user handle and shared secret you got.
If you need to access an environment other than production or are running custom instance of Cheddar service, you can set the endpoint manually.
And if you just want to use the sandbox version of default Cheddar instance, run the following command.
Please note that only VÚB eCard, iTerminal, GP webpay and PayPal currently allow for using their test environments so in case of other providers production URLs will be used! When using sandbox with supported bank or financial institution never use real world credit cards / accounts for testing payment methods implementation (they will not work). Always use virtual testing cards / accounts provided for this purpose by the payment institution.
Creating a transaction
It is quite simple to instantiate a payment.
Here’s a quick piece of example code to get you started which will call the Cheddar service and retrieve UUID – universal identifier of the transaction and set the transaction status to none
(see next section for more on transaction statuses). User's IP is automatically added to the data array before it is sent to the service.
First argument is a service provider, which can currently be one of the following:
Service name | Description |
---|---|
Cheddar::SERVICE_SPOROPAY |
SporoPay, Slovenská sporiteľňa |
Cheddar::SERVICE_TATRAPAY |
TatraPay, Tatra banka |
Cheddar::SERVICE_CARDPAY |
Cardpay, Tatra banka |
Cheddar::SERVICE_EPLATBY |
ePlatby, VÚB |
Cheddar::SERVICE_ECARD |
eCard, VÚB |
Cheddar::SERVICE_PAYPAL |
PayPal Payments Standard, PayPal |
Cheddar::SERVICE_GPWEBPAY |
GP webpay, Global Payments Europe |
Cheddar::SERVICE_ITERMINAL |
iTerminal, Poštová banka (firstdata.lv backend) |
Cheddar::SERVICE_ITERMINAL2 |
iTerminal, Poštová banka (sia.eu backend) |
Second argument to the function call is an associative array of configuration options. Which options have to be used and which have no effect at all depends on the service provider. The next table lists all possible attributes:
Attribute name | Data type | Required? | Notes |
---|---|---|---|
amount |
float | ✓ | amount required in the specified currency |
currency |
string | ✓ | currency code or numeric code according to ISO 4217 |
variable_symbol |
string | ✓ | |
constant_symbol |
string | ||
card_id |
string | optional card token in periodical payments applicable only to ComfortPay transactions |
|
payer_name |
string | ✓ | customer’s name |
payer_email |
string | ✓ | customer’s email (which has to be a valid e-mail address) |
language |
string | customer’s language | |
description |
string | reference for the customer | |
return_url or callback |
string | ✓ | URL to return to after the payment iTerminal does not use this attribute since you have to set this up once for all transactions in their administration interface |
notification_url |
string | URL to send notifications to required for PayPal transactions |
|
cpp_logo_image |
string | header image at PayPal applicable only to PayPal transactions |
|
cpp_cart_border_color |
string | HEX code of colour at PayPal applicable only to PayPal transactions |
|
periodicity |
integer | periodicity in days, when the next periodical payment will be automatically executed; default value is 30 days applicable only to ComfortPay transactions |
Note that all of the supported currencies are available as a simple constant on \Cheddar\Currencies
class to make it easier in code.
After the call you can inspect the returning \Cheddar\Data\Payment
object, which is described in the Getting transaction details
part of this document.
To get to the URL of a payments gateway at the bank where the payment is processed just call the following:
After the payment process at the payment gateway is finished, you will be redirected to the URL you specified in return_url
/ callback
parameter during the $client->payment()->create(...) call in the example above. The URL will have two more GET parameters added - uuid
, for the payment identifier and status
, for the current status of the payment transaction (for some payment methods this may change in time, and you will be notified about the change to the URL you specified in the notification_url
parameter [see the Asynchronous transaction notifications
part of this document for more info])
Allowed transaction statuses
Status name | Description |
---|---|
none |
transaction has been created, but the user has not been redirected to bank’s payment gateway |
in_progress |
user has been redirected to bank’s payment gateway |
completed |
transaction has been successfully completed |
denied or rejected |
transaction has been rejected by the bank (the most usual reasons include user error in inputting card details and insufficient funds) |
timeout |
special temporary status used only by Tatra banka’s TatraPay service |
pending |
special status for PayPal before an IPN notification has resolved the transaction status as either rejected or completed |
cancelled |
in case of periodical payments available only with Tatra banka’s ComfortPay service this status means that planned transaction has been cancelled |
expired |
old payment without clear result (e.g. user abandoned the payment form while at bank’s gateway) |
Getting transaction details
To get all details of an existing payment transaction simply pass the UUID of the payment to the following method:
Afterwards you can inspect the returning \Cheddar\Data\Payment
object, which contains these properties:
Property name | Data type | Always present? | Default value | Notes |
---|---|---|---|---|
uuid |
string | ✓ | ||
status |
string | ✓ | none | current transaction status (see the next table) |
variable_symbol |
string | ✓ | the same as was sent while creating the payment object (see previous section) | |
constant_symbol |
string | ✓ | 0308 | payment for services |
amount |
float | ✓ | 0.00 | original amount of the transaction |
refunded_amount |
float | ✓ | 0.00 | refunded amount of the transaction |
service_fee_amount |
float | ✓ | 0.00 | provision for the transaction in card payments available when using CardPay / ComfortPay and set up with PGP encrypted statements or PayPal service |
currency |
Currencies |
✓ | EUR | currency of the transaction |
periodicity |
integer | 0 | number of days in which next payment will be executed | |
periodicity_no |
integer | 1 | number of transaction in order (using the same variable symbol) | |
charge_on |
Datetime |
when was or should be this transaction executed | ||
card_expire_on |
Datetime |
null | date of card expiration available only when using ComfortPay or VÚB eCard service | |
card_no |
string | masked card number available only when using ComfortPay or VÚB eCard service | ||
transaction_identifier |
string | internal transaction identifier of the bank available only when using CardPay / ComfortPay, TatraPay or VÚB eCard service |
Asynchronous transaction notifications
Transactions may have a notification_url
attribute (in case of PayPal and ComfortPay the attribute is mandatory), that will receive a ping on every change to a transaction (in case of PayPal or ComfortPay it is also the only way to find out the status of the payment).
Cheddar calls the value of notification_url
attribute as POST request with GET attributes uuid
and signature
(which needs to be verified) and application/json
body with full payment details as explained in the previous section.
To validate the signature, you need to call the following:
In case the signature is incorrect a \Cheddar\Exceptions\MessageIntegrityException
exception is thrown, otherwise the function returns true
. After a successful validation you can trust the json-encoded body of the request.
The json-encoded body will look something like this:
Updating planned transaction
The next use case is the ability to change date and / or amount of a next planned playment. The output of the call is summary of the planned payment including its UUID.
However, also the status of the planned payment might be changed – from none
to cancelled
or the other way. Just make sure that the charge_on
attribute is set to correct value or explicitly set it, when changing the status.
Refunding transactions
With Poštová banka’s iTerminal service you might once request a refund on executed transaction in part, or in full. In case of Tatra banka's CardPay service you might request as many refunds as you'd like until sum of all prior refunds reaches the amount of the original transaction.
The reason
is more informative and should be one of either requested_by_customer
, fraudelent
, duplicate
or unknown
(default). Currency has to be the same as when executing the original payment.
Contributing
- 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.
TODO
- thorough tests of functionality
- ability to use your own HTTP client
Development
Install dependencies as mentioned above, then run the test suite:
Or to run an individual test file:
© 2021 BACKBONE, s.r.o.
All versions of cheddar with dependencies
ext-curl Version *
ext-hash Version *
ext-json Version *