payever / sdk-php
PHP SDK for payever
Installs: 56 981
Dependents: 1
Suggesters: 0
Security: 0
Stars: 7
Watchers: 5
Forks: 1
Open Issues: 0
Requires (Dev)
- behat/behat: ^3.4
- friendsofphp/php-cs-fixer: ^2.18
- laminas/laminas-diactoros: ^2.5
- laminas/laminas-httphandlerrunner: ^1.4
- phpmd/phpmd: ^2.9
- phpunit/phpunit: ^9
- squizlabs/php_codesniffer: ^3.5
Suggests
- ext-mcrypt: If you want to use mcrypt at PseudoRandomStringGenerator
- ext-openssl: If you want to use openssl at PseudoRandomStringGenerator
- ext-pdo: If you want to use MySQLLock
- dev-master
- 4.7.1
- 4.7.0
- 4.6.0
- 4.5.0
- 4.4.0
- 4.3.1
- 4.3.0
- 4.2.0
- 4.1.1
- 4.1.0.1
- 4.1.0
- 4.0.1
- 4.0.0
- 3.5.0
- 3.4.1
- 3.4.0
- 3.3.0
- 3.2.1
- 3.2.0
- 3.1.3
- 3.1.2
- 3.1.1.4
- 3.1.1.3
- 3.1.1.2
- 3.1.1.1
- 3.1.1.0
- 3.1.0
- 3.0.13
- 3.0.12
- 3.0.11
- 3.0.10
- 3.0.9
- 3.0.8
- 3.0.7
- 3.0.6
- 3.0.5
- 3.0.4
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- 2.12.0
- 2.11.0
- 2.10.0
- 2.9.0
- 2.8.0
- 2.7.0
- 2.6.0
- 2.5.9
- 2.5.8
- 2.5.7
- 2.5.6
- 2.5.5
- 2.5.4
- 2.5.3
- 2.5.2
- 2.5.1
- 2.5.0
- 2.4.0
- 2.3.0
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.2
- 2.1.1
- 2.1.0
- 2.0.0
- 2.0.0-rc.4
- 2.0.0-rc.3
- 2.0.0-rc.1
- 1.x-dev
- 1.4.1
- 1.4.0
- 1.3.5-p2
- 1.3.4
- 1.3.3
- 1.3.2
- 1.2.0
This package is auto-updated.
Last update: 2024-10-22 21:17:32 UTC
README
This repository contains the open source PHP SDK that allows you to access payever from your PHP app.
This library follows semantic versioning. Read more on semver.org.
Please note: this SDK is used within the payever plugins. It is NOT suitable for custom API integrations. If you would like to integrate with us via API, please visit https://docs.payever.org/shopsystems/api and follow the instructions and code examples provided there.
Troubleshooting
If you faced an issue you can contact us via official support channel - support@getpayever.com
Requirements
- PHP 5.4.0 and later
- PHP cURL extension
Installation
You can use Composer or install manually
Composer
The preferred method is via composer. Follow the installation instructions if you do not already have composer installed.
Once composer is installed, execute the following command in your project root to install this library:
composer require payever/sdk-php
Manual Installation
Alternatively you can download the package entirety. The Releases page lists all stable versions.
Uncompress the zip file and invoke the autoloader in your project:
require_once '/path/to/sdk-php/lib/Payever/ExternalIntegration/Core/Engine.php'; \Payever\ExternalIntegration\Core\Engine::registerAutoloader();
Documentation
Raw HTTP API docs can be found here - https://docs.payever.org/shopsystems/api
Enums
The are several list of fixed string values used inside API. For convenience they are represented as constants and grouped into classes.
- Core
ChannelSet
- list of available payever API channels
- Payments
PaymentMethod
- list of available payever payment methodsStatus
- list of available payever payment statuses
- ThirdParty
ActionEnum
- list of available actions (webhooks)DirectionEnum
- list of available action directions
- Products
ProductTypeEnum
- list of available payever product types
- Plugins
PluginCommandNameEnum
- list of available plgin command types
API Clients
HTTP API communication with payever happens through API clients. There are several of them for different API categories:
Each one is described in details below.
Configuration
Each API client requires configuration object as the first argument of client's constructor. In order to get the valid configuration object you need to have valid API credentials:
- Client ID
- Client Secret
- Business UUID
Additionally, you need to tell which API channel you're using:
use Payever\ExternalIntegration\Core\ClientConfiguration; use Payever\ExternalIntegration\Core\Enum\ChannelSet; $clientId = 'your-oauth2-client-id'; $clientSecret = 'your-oauth2-client-secret'; $businessUuid = '88888888-4444-4444-4444-121212121212'; $clientConfiguration = new ClientConfiguration(); $clientConfiguration ->setClientId($clientId) ->setClientSecret($clientSecret) ->setBusinessUuid($businessUuid) ->setChannelSet(ChannelSet::CHANNEL_MAGENTO) ->setApiMode(ClientConfiguration::API_MODE_LIVE) ;
NOTE: All examples below assume you have ClientConfiguration
instantiated inside $clientConfiguration
variable.
Logging
You can setup logging of all API interactions by providing PSR-3 compatible logger instance.
In case if you don't have PSR-3 compatible logger at hand - this SKD contains simple file logger:
use Psr\Log\LogLevel; use Payever\ExternalIntegration\Core\Logger\FileLogger; $logger = new FileLogger(__DIR__.'/payever.log', LogLevel::INFO); $clientConfiguration->setLogger($logger);
PaymentsApiClient
This API client is used in all payment-related interactions.
Create payment and obtain redirect url
use Payever\ExternalIntegration\Payments\Enum\PaymentMethod; use Payever\ExternalIntegration\Payments\PaymentsApiClient; use Payever\ExternalIntegration\Payments\Http\RequestEntity\CreatePaymentRequest; $paymentsApiClient = new PaymentsApiClient($clientConfiguration); $createPaymentEntity = new CreatePaymentRequest(); $createPaymentEntity ->setOrderId('1001') ->setAmount(100.5) ->setFee(10) ->setCurrency('EUR') ->setPaymentMethod(PaymentMethod::METHOD_SANTANDER_DE_INSTALLMENT) ->setSalutation('mr') ->setFirstName('John') ->setLastName('Doe') ->setCity('Hamburg') ->setCountry('DE') ->setZip('10111') ->setStreet('Awesome street, 10') ->setEmail('john.doe@example.com') ->setPhone('+450001122') ->setSuccessUrl('https://your.domain/success?paymentId=--PAYMENT-ID--') ->setCancelUrl('https://your.domain/checkout?reason=cancel') ->setFailureUrl('https://your.domain/checkout?reason=failure') ->setNoticeUrl('https://your.domain/async-payment-callback?paymentId=--PAYMENT-ID--') ->setCart([ [ 'name' => 'test', 'sku' => 'test', 'identifier' => 'test', 'price' => 100.5, 'vatRate' => 0, 'quantity' => 1, ] ]) ; try { $response = $paymentsApiClient->createPaymentRequest($createPaymentEntity); $responseEntity = $response->getResponseEntity(); header(sprintf('Location: %s', $responseEntity->getRedirectUrl()), true); exit; } catch (\Exception $exception) { echo $exception->getMessage(); }
Retrieve payment details by id
use Payever\ExternalIntegration\Payments\PaymentsApiClient; use Payever\ExternalIntegration\Payments\Http\MessageEntity\RetrievePaymentResultEntity; $paymentId = '--PAYMENT-ID--'; $paymentsApiClient = new PaymentsApiClient($clientConfiguration); try { $response = $paymentsApiClient->retrievePaymentRequest($paymentId); /** @var RetrievePaymentResultEntity $payment */ $payment = $response->getResponseEntity()->getResult(); $status = $payment->getStatus(); } catch(\Exception $exception) { echo $exception->getMessage(); }
Cancel the payment by id
use Payever\ExternalIntegration\Payments\PaymentsApiClient; use Payever\ExternalIntegration\Payments\Action\ActionDecider; $paymentId = '--PAYMENT-ID--'; $paymentsApiClient = new PaymentsApiClient($clientConfiguration); $actionDecider = new ActionDecider($paymentsApiClient); try { if ($actionDecider->isActionAllowed($paymentId, ActionDecider::ACTION_CANCEL, false)) { $paymentsApiClient->cancelPaymentRequest($paymentId); } } catch(\Exception $exception) { echo $exception->getMessage(); }
Trigger Santander shipping-goods payment action
use Payever\ExternalIntegration\Payments\PaymentsApiClient; use Payever\ExternalIntegration\Payments\Action\ActionDecider; $paymentId = '--PAYMENT-ID--'; $paymentsApiClient = new PaymentsApiClient($clientConfiguration); $actionDecider = new ActionDecider($paymentsApiClient); try { if ($actionDecider->isActionAllowed($paymentId, ActionDecider::ACTION_SHIPPING_GOODS, false)) { $paymentsApiClient->shippingGoodsPaymentRequest($paymentId); } } catch(\Exception $exception) { echo $exception->getMessage(); }
ThirdPartyApiClient
This client can be used to initiate webhook-based data flow between your system and payever. As of now, only product and inventory webhooks are supported.
How it works:
- generate a unique string (
externalId
) to identify yourself inside payever system; - create a data subscription with a list of webhooks you wish to consume;
- whenever specific event happens inside payever system you will receive an HTTP request to your webhook URL;
Subscribe
use Payever\ExternalIntegration\Core\PseudoRandomStringGenerator; use Payever\ExternalIntegration\ThirdParty\Enum\ActionEnum; use Payever\ExternalIntegration\ThirdParty\ThirdPartyApiClient; use Payever\ExternalIntegration\ThirdParty\Http\RequestEntity\SubscriptionRequestEntity; use Payever\ExternalIntegration\ThirdParty\Http\MessageEntity\SubscriptionActionEntity; $tmpApiClient = new ThirdPartyApiClient($clientConfiguration); $randomSource = new PseudoRandomStringGenerator(); $subscriptionEntity = new SubscriptionRequestEntity(); // save it in persistent storage for future use $externalId = $randomSource->generate(); $subscriptionEntity->setExternalId($externalId); $actionEntity = new SubscriptionActionEntity(); // your webhook details $actionEntity->setName(ActionEnum::ACTION_CREATE_PRODUCT) ->setUrl('https://my.shop.com/webhook/?action=create-product&token=' . $externalId) ->setMethod('POST'); $subscriptionEntity->addAction($actionEntity); try { $tmpApiClient->subscribe($subscriptionEntity); } catch(\Exception $exception) { echo $exception->getMessage(); }
You can find the full list of available webhooks here.
Check subscription status
Useful when you need to check if your subscription is active or check the list of webhooks.
use Payever\ExternalIntegration\ThirdParty\ThirdPartyApiClient; use Payever\ExternalIntegration\ThirdParty\Http\RequestEntity\SubscriptionRequestEntity; use Payever\ExternalIntegration\ThirdParty\Http\ResponseEntity\SubscriptionResponseEntity; $tmpApiClient = new ThirdPartyApiClient($clientConfiguration); $subscriptionEntity = new SubscriptionRequestEntity(); $externalId = ''; // retrieve it from your persistent storage $subscriptionEntity->setExternalId($externalId); try { $response = $tmpApiClient->getSubscriptionStatus($subscriptionEntity); /** @var SubscriptionResponseEntity $subscription */ $subscription = $response->getResponseEntity(); $id = $subscription->getId(); } catch(\Exception $exception) { echo $exception->getMessage(); }
Unsubscribe
If you want to stop receiving webhook updates - you would need to call "unsubscribe" method.
use Payever\ExternalIntegration\ThirdParty\ThirdPartyApiClient; use Payever\ExternalIntegration\ThirdParty\Http\RequestEntity\SubscriptionRequestEntity; $tmpApiClient = new ThirdPartyApiClient($clientConfiguration); $subscriptionEntity = new SubscriptionRequestEntity(); $externalId = ''; // retrieve it from your persistent storage $subscriptionEntity->setExternalId($externalId); try { $tmpApiClient->unsubscribe($subscriptionEntity); } catch(\Exception $exception) { echo $exception->getMessage(); }
Handling action (webhook) requests
Of course you can handle webhook requests manually, but there are several classes and interfaces for easier webhook handling.
You can define a class for each webhook type by implementing ActionHandlerInterface
:
use Payever\ExternalIntegration\ThirdParty\Action\ActionHandlerInterface; use Payever\ExternalIntegration\ThirdParty\Action\ActionPayload; use Payever\ExternalIntegration\ThirdParty\Action\ActionResult; use Payever\ExternalIntegration\ThirdParty\Enum\ActionEnum; use Payever\ExternalIntegration\Products\Http\RequestEntity\ProductRequestEntity; class MyCreateProductActionHandler implements ActionHandlerInterface { public function getSupportedAction() { return ActionEnum::ACTION_CREATE_PRODUCT; // Which webhook type this class intends to handle? } public function handle(ActionPayload $actionPayload, ActionResult $actionResult) { /** @var ProductRequestEntity $payeverProduct */ $payeverProduct = $actionPayload->getPayloadEntity(); if (!$payeverProduct->getSku()) { $actionResult->addError('Product must have SKU'); return; } if (productExists()) { // TODO: update product inside your system $actionResult->incrementUpdated(); } else { // TODO: create product inside you system $actionResult->incrementCreated(); } // no need to handle exceptions here } }
Once you created such handler classes for all webhooks, you can combine them into ActionHandlerPool
and use InwardActionProcessor
to handle all the routines for you:
use Psr\Log\LogLevel; use Payever\ExternalIntegration\Core\Logger\FileLogger; use Payever\ExternalIntegration\ThirdParty\Action\ActionHandlerPool; use Payever\ExternalIntegration\ThirdParty\Action\InwardActionProcessor; use Payever\ExternalIntegration\ThirdParty\Action\ActionResult; $actionName = $_REQUEST['action']; $token = $_REQUEST['token']; if (!$actionName) { // respond with 400 HTTP status code exit; } $externalId = '';// retrieve from your persistent storage if (!$token || $token !== $externalId) { // respond with 401 HTTP status code exit; } $logger = new FileLogger(__DIR__.'/payever.log', LogLevel::INFO); try { $actionResult = new ActionResult(); $actionHandlerPool = new ActionHandlerPool([ new MyCreateProductActionHandler(), new MyUpdateProductActionHandler(), //... ]); $actionProcessor = new InwardActionProcessor( $actionHandlerPool, $actionResult, $logger ); $actionResult = $actionProcessor->process($actionName); echo (string) $actionResult; // respond with 200 status } catch (\Exception $exception) { $logger->critical(sprintf('Webhook processing failed: %s', $exception->getMessage())); // respond with 500 status }
ProductsApiClient
This client class is dependant on ThirdPartyApiClient
and requires active third-party subscription with known externalId
;
This API client can be used to create/update/delete (NOTE: "read" operation is not available atm) operations over payever products. Please note that products between any external system and payever are identified by SKU field.
Create or update product
use Payever\ExternalIntegration\Products\ProductsApiClient; use Payever\ExternalIntegration\Products\Http\RequestEntity\ProductRequestEntity; $productsApiClient = new ProductsApiClient($clientConfiguration); $productEntity = new ProductRequestEntity(); $productEntity->setTitle('Awesome Product') ->setActive(true) ->setSku('AWSM1') ->setPrice(100.5) ->setCurrency('EUR') ->setDescription('Awesome product description') ->setImages([ 'https://my.shop.com/images/awsm1.png', ]) ->setCategories([ 'Awesome Goods', ]) ->setShipping([ 'width' => 1, 'height' => 1, 'length' => 1, 'weight' => 2, ]); $externalId = '';// retrieve it from your persistent storage $productEntity->setExternalId($externalId); try { $productsApiClient->createOrUpdateProduct($productEntity); } catch(\Exception $exception) { echo $exception->getMessage(); }
Delete/remove product
use Payever\ExternalIntegration\Products\ProductsApiClient; use Payever\ExternalIntegration\Products\Http\RequestEntity\ProductRemovedRequestEntity; $productsApiClient = new ProductsApiClient($clientConfiguration); $productRemovedEntity = new ProductRemovedRequestEntity(); $productRemovedEntity->setSku('AWSM1'); $externalId = '';// retrieve it from your persistent storage $productRemovedEntity->setExternalId($externalId); try { $productsApiClient->removeProduct($productRemovedEntity); } catch(\Exception $exception) { echo $exception->getMessage(); }
InventoryApiClient
This client class is dependent on ThirdPartyApiClient
and requires active third-party subscription with known externalId
;
This API client can be used to create/add/subtract (NOTE: "read" operation is not available atm) operations over payever inventory. Please note that product inventory between any external system and payever are identified by SKU field.
Create product inventory record
"Create" operation can be done only once, all further "create" requests with the same SKU will be ignored. Use add/subtract operations to change the value of inventory once it created.
use Payever\ExternalIntegration\Inventory\InventoryApiClient; use Payever\ExternalIntegration\Inventory\Http\RequestEntity\InventoryCreateRequestEntity; $inventoryApiClient = new InventoryApiClient($clientConfiguration); $inventoryCreateEntity = new InventoryCreateRequestEntity(); $inventoryCreateEntity->setSku('AWSM1') ->setStock(15); $externalId = '';// retrieve it from your persistent storage $inventoryCreateEntity->setExternalId($externalId); try { $inventoryApiClient->createInventory($inventoryCreateEntity); } catch (Exception $exception) { echo $exception->getMessage(); }
Add (increase) inventory value
use Payever\ExternalIntegration\Inventory\InventoryApiClient; use Payever\ExternalIntegration\Inventory\Http\RequestEntity\InventoryChangedRequestEntity; $inventoryApiClient = new InventoryApiClient($clientConfiguration); $inventoryChangeEntity = new InventoryChangedRequestEntity(); $inventoryChangeEntity->setSku('AWSM1') ->setQuantity(5); // read as: +5 to existing value $externalId = '';// retrieve it from your persistent storage $inventoryChangeEntity->setExternalId($externalId); try { $inventoryApiClient->addInventory($inventoryChangeEntity); } catch (Exception $exception) { echo $exception->getMessage(); }
Subtract (decrease) inventory value
use Payever\ExternalIntegration\Inventory\InventoryApiClient; use Payever\ExternalIntegration\Inventory\Http\RequestEntity\InventoryChangedRequestEntity; $inventoryApiClient = new InventoryApiClient($clientConfiguration); $inventoryChangeEntity = new InventoryChangedRequestEntity(); $inventoryChangeEntity->setSku('AWSM1') ->setQuantity(3); // read as: -3 to existing value $externalId = '';// retrieve it from your persistent storage $inventoryChangeEntity->setExternalId($externalId); try { $inventoryApiClient->subtractInventory($inventoryChangeEntity); } catch (Exception $exception) { echo $exception->getMessage(); }
License
Please see the license file for more information.