klix-app / merchant-api-php
Klix merchant API PHP SDK
Requires
- php: >=5.5
- ext-json: *
- ext-openssl: *
- guzzlehttp/guzzle: ^6.2
- liamdennehy/http-signatures-php: ^6.6.0
Requires (Dev)
- ext-simplexml: *
- phpunit/phpunit: ^4.8
README
Requirements
PHP 5.5 and later
Installation
Composer
To install the bindings via Composer, add the following to composer.json:
{
"require": {
"klix-app/merchant-api-php": "*@dev"
}
}
Then run composer install
Manual Installation
Download the files and include autoload.php:
require_once('/path/to/merchant-api-php/vendor/autoload.php');
Library usage
Create Klix integration configuration
KlixConfiguration class represents Klix integration configuration. Values for configuration properties and merchant's private / service provider's public keys can be found on Klix Merchant Console site.
<?php require_once(__DIR__ . '/vendor/autoload.php'); use Klix\KlixConfigurationBuilder; $apiConfiguration = KlixConfigurationBuilder::builder() ->setPrivateKey(file_get_contents('resources/keys/merchant_private_key.pem')) ->setPrivateKeyId('52a49f81-0869-40a6-8dde-96a624e61b54') ->setProviderPublicKey(file_get_contents('resources/keys/provider_public_key.pem')) ->build(); ?>
Create widget configuration
WidgetConfiguration class represents widget and order configuration.
In order to construct proper WidgetConfiguration at least widget identifier, language and order with single order item should be passed.
Single order item in this case is used to represent order total amount even if order shopping cart consists of multiple products.
<?php $orderItem = OrderItem::create() ->setAmount(120.04) ->setCurrency('EUR') ->setLabel("Order No 1234567890"); $order = Order::create() ->setOrderId("36c420f4-5487-11ea-a2e3-2e728ce88125") ->addItem($orderItem); $widgetConfiguration = WidgetConfiguration::create() ->setWidgetId("d700a786-56da-11ea-8e2d-0242ac130003") ->setLanguage("lv") ->setBackToMerchantUrl("https://merchant.home.url.com") ->setOrder($order); ?>
Multiple order items can be specified to represent all products and their quantities included in this order. Additionally to that available shipping options and card acceptance constraints can be specified.
<?php $firstOrderItem = OrderItem::create() ->setAmount(122.99) ->setCount(2) ->setCurrency("EUR") ->setLabel("Vacuum cleaner TC31") ->setOrderItemId("ff713414-56f9-11ea-82b4-0242ac130003") ->setTaxRate(0.21) ->setUnit("PIECE"); $secondOrderItem = OrderItem::create() ->setAmount(7.05) ->setCurrency('EUR') ->setLabel("Filter for TC31"); $firstShippingOption = ShippingOption::create() ->setId("courier") ->setAmount(3); $secondShippingOption = ShippingOption::create() ->setId("pickup") ->setTitle("In store pickup") ->setAmount(0) ->setCurrency("EUR"); $constraints = new OrderConstraints(); $constraints->setBrand("Citadele"); $order = Order::create() ->setOrderId("1234567890") ->addItem($firstOrderItem) ->addItem($secondOrderItem) ->addShippingOption($firstShippingOption) ->addShippingOption($secondShippingOption) ->setConstraints($constraints); $widgetConfiguration = WidgetConfiguration::create() ->setWidgetId("d700a786-56da-11ea-8e2d-0242ac130003") ->setLanguage("lv") ->setBackToMerchantUrl("https://merchant.home.url.com") ->setCertificateName("6af6c4fc-56db-11ea-8e2d-0242ac130003") ->setOrder($order); ?>
Generate widget HTML representation
In order to include Klix widget HTML to merchant web-page CheckoutWidget class instance should be obtained from CheckoutWidgetFactory.
<?php $widgetConfigurationSigner = new WidgetConfigurationSigner($apiConfiguration); $checkoutWidgetFactory = new CheckoutWidgetFactory($widgetConfigurationSigner); $checkoutWidget = $checkoutWidgetFactory->create($widgetConfiguration); $htmlRepresentation = $checkoutWidget->getHtmlRepresentation(); echo $htmlRepresentation; ?>
Previous example will print Klix widget HTML similar to:
<klix-checkout widget-id="d700a786-56da-11ea-8e2d-0242ac130003" language="lv" back-to-merchant-url="https://merchant.home.url.com" certificate-name="6af6c4fc-56db-11ea-8e2d-0242ac130003" signature="T2mN980RRnm6eTmnggYNA51RkZ/NItnPF2H4Z/c92gyBM2MuX/u8KVuQsdBlt9XDUfFq6HA2sXIr1cNWzUrTV51VHsuq5u17aTZ4a1rWPjdegjfVVI0ErIDXKrEHzvS1PJ0VvyFUBeZEQEXWTMyRGfCTgO8/pDWbEfwTXeY8HzqftaGj00ej5/upGHhVn2SDVtGsp55I7uW/PIRUWCnxxZKwA/VzALUlTGgCGoxE9fhBiFVcOVPSi0sLUReL1yw21gRWLg/uMx6tuNHK25fvtLzVLO6MigOruA5mFfT3jnHHczrkpjOeOJ+FwZ1mmkCOyCdPYC0G8CCF8C5EYBr4dA==" order="{"orderId":"36c420f4-5487-11ea-a2e3-2e728ce88125","items":[{"amount":122.99,"currency":"EUR","label":"Vacuum cleaner TC31","count":2,"unit":"PIECE","taxRate":0.21,"orderItemId":"ff713414-56f9-11ea-82b4-0242ac130003"},{"amount":7.05,"currency":"EUR","label":"Filter for TC31","count":null,"unit":null,"taxRate":null,"orderItemId":null}],"shippingOptions":[{"id":"courier","amount":3,"currency":null,"taxRate":null,"title":null,"excludeFromOrderIfFree":null},{"id":"pickup","amount":0,"currency":"EUR","taxRate":null,"title":"In store pickup","excludeFromOrderIfFree":null}],"constraints":{"paymentScheme":null,"issuer":null,"brand":"Citadele"}}"> </klix-checkout>
Note that Klix widget JavaScript should be loaded in order to properly render Klix widget web component. See Klix quick start guide.
Receive purchase completed callback
Upon purchase completion Klix back-end will send purchase completed callback to merchant's website. At that moment merchant web-shop should update order status according to payment status.
<?php use Klix\Callback\ProviderSignatureValidator; use Klix\Callback\ProviderCallbackRequestDecoder; $requestBodyString = // read request body $signature = // read request header "X-Klix-Signature" value $validator = new ProviderSignatureValidator($apiConfiguration); $decoder = new ProviderCallbackRequestDecoder($validator); $merchantOrder = $decoder->decodePurchaseFinalizedRequest($requestBodyString, $signature); echo $merchantOrder->getId(); echo $merchantOrder->getStatus(); ?>
Invoke Klix Merchant API
Klix Merchant API can be used to perform various order related operations. Klix Merchant API client (class Klix\Api\MerchantsApi) does all the heavy lifting related to HTTP request authentication using HTTP signatures.
<?php use Klix\Api\ApiClient; use Klix\Api\MerchantApi; use Klix\Api\OrderRefund; use Klix\Api\OrderRefundRequest; $orderId = '9482996d-d3b2-4518-84aa-d6649bad6e99'; $merchantId = $this->apiConfiguration->getMerchantId(); $this->orderRefundReturnsEffectiveAmount(); $merchantApi = new MerchantApi(new ApiClient($apiConfiguration), $apiConfiguration); $orderRefund = new OrderRefund(); $orderRefund->setAmount(10.00) ->setReason(RefundReason::OTHER_REFUND) ->setNote("Actual weight differs from ordered"); $request = new OrderRefundRequest($orderId, $orderRefund); $orderRefundResponse = $merchantApi->refundOrder($request); echo $orderRefundResponse->getTotalRefundedAmount(); echo $orderRefundResponse->getOrderEffectiveAmount(); ?>
Other order authorization method
Besides order authorization using order signature provided by merchant Klix supports another order authorization method using merchant's callback for more advanced use cases.
Examples
See library usage example in Klix Pay scenario.
Running tests
Check out library unit tests for more examples of Klix PHP library API usage. Command to execute all tests:
composer unit
About
License
Klix.app Merchant API PHP client library is licensed under the Apache 2.0 License - see the LICENSE file for details