PHPackages simpay/ecommerce - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. simpay/ecommerce ActiveLibrary[Payment Processing](/categories/payments) simpay/ecommerce ================ PHP SDK for integrating SimPay payments into e-commerce platforms 1.0.3(3w ago)010MITPHPPHP >=8.1 Since Jun 9Pushed 3w agoCompare [ Source](https://github.com/SimPaypl/simpay-ecommerce)[ Packagist](https://packagist.org/packages/simpay/ecommerce)[ Docs](https://github.com/SimPaypl/simpay-ecommerce)[ RSS](/packages/simpay-ecommerce/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (2)Versions (4)Used By (0) SimPay E-commerce SDK ===================== [](#simpay-e-commerce-sdk) Wspólne SDK do obsługi płatności SimPay we wszystkich naszych pluginach e-commerce. - **Walidacja IPN** — sprawdzenie User-Agent, wymaganych pól, podpisu SHA-256, service\_id - **Walidacja IP** — pobranie listy IP SimPay z API, cache, porównanie - **Porównywanie kwot** — float-safe porównanie czy zapłacono wystarczająco - **Klient API** — tworzenie transakcji, refundy, BLIK, kanały płatności - **Builder transakcji** — budowanie payloadu z walidacją pól Instalacja ---------- [](#instalacja) W `composer.json` pluginu: ``` { "repositories": [ { "type": "path", "url": "../simpay-ecommerce" } ], "require": { "simpay/ecommerce": "*" } } ``` Struktura --------- [](#struktura) ``` src/ ├── SimPay.php # Główna fasada — punkt wejścia ├── SimPayClient.php # Klient HTTP do API (transakcje, refundy, BLIK, OneClick, kanały, IP) ├── Configuration.php # Credentials + metadata platformy ├── BlikAlias.php # DTO aliasu BLIK OneClick ├── IpnValidator.php # Walidacja webhooków (wersja UA, pola, podpis, service_id) ├── IpnPayload.php # DTO wyniku walidacji IPN (+ helpery BLIK alias) ├── IpAllowlistService.php # Walidacja IP z opcjonalnym cache ├── TransactionBuilder.php # Fluent builder payloadu transakcji ├── AmountVerifier.php # Porównywanie kwot (float-safe) ├── PaymentStatus.php # Stałe statusów (transaction_paid, alias_active, etc.) ├── CacheInterface.php # Interfejs cache — implementuj per-platforma ├── Http/ │ ├── HttpClientInterface.php │ ├── HttpResponse.php │ └── CurlHttpClient.php # Domyślna implementacja └── Exception/ ├── SimPayException.php ├── ApiException.php ├── AliasNotUniqueException.php # Błąd wieloznaczności aliasu BLIK ├── HttpException.php ├── IpnException.php └── IpNotAllowedException.php ``` Użycie ------ [](#użycie) ### Inicjalizacja [](#inicjalizacja) ``` use SimPay\SDK\SimPay; $simpay = new SimPay( bearerToken: $config->get('simpay_bearer'), serviceId: $config->get('simpay_service_id'), signatureKey: $config->get('simpay_signature_key'), platform: 'opencart', platformVersion: VERSION ); ``` ### Tworzenie transakcji [](#tworzenie-transakcji) ``` $payload = $simpay->transaction() ->setAmount((float) $order['total'], $order['currency_code']) ->setDescription('Zamówienie #' . $order['order_id']) ->setControl((string) $order['order_id']) ->setCustomer($name, $email, $ip, $countryIso) ->setReturnUrls($successUrl, $failureUrl) ->setBilling($firstName, $lastName, $street, $building, $city, $postCode, $countryIso) ->toArray(); $response = $simpay->client()->createTransaction($payload); $redirectUrl = $response['data']['redirectUrl']; ``` ### Obsługa IPN (webhook) [](#obsługa-ipn-webhook) ``` use SimPay\SDK\SimPay; use SimPay\SDK\AmountVerifier; use SimPay\SDK\PaymentStatus; $payload = json_decode(file_get_contents('php://input'), true); try { $ipn = $simpay->handleIpn( payload: $payload, userAgent: $_SERVER['HTTP_USER_AGENT'] ?? null, remoteIp: $_SERVER['REMOTE_ADDR'] ?? null // null = pomiń sprawdzenie IP ); } catch (\SimPay\SDK\Exception\IpNotAllowedException $e) { http_response_code(403); exit($e->getMessage()); } catch (\SimPay\SDK\Exception\IpnException $e) { http_response_code(400); exit($e->getMessage()); } // Rozróżnianie eventów if ($ipn->isTransactionEvent()) { if (!$ipn->isPaid()) { exit('OK'); // jeszcze nie opłacone, potwierdź odbiór } $orderId = $ipn->getControl(); $paidAmount = $ipn->getEffectiveAmount($orderCurrency); if (!AmountVerifier::isAmountSufficient($orderTotal, $paidAmount)) { http_response_code(400); exit('Amount mismatch'); } // Aktualizuj status zamówienia } if ($ipn->isRefundEvent()) { // Obsłuż refund $refundId = $ipn->data['id']; $status = $ipn->getStatus(); } exit('OK'); ``` ### Refundy [](#refundy) ``` $simpay->client()->createRefund($transactionId); // pełny $simpay->client()->createRefund($transactionId, 50.00); // częściowy ``` ### BLIK Level 0 [](#blik-level-0) ``` // Prosta płatność BLIK Level 0 (bez rejestracji aliasu) $simpay->client()->sendBlikLevel0($transactionId, '123456'); ``` ### BLIK Level 0 + OneClick (Płatności bez kodu) [](#blik-level-0--oneclick-płatności-bez-kodu) #### Krok 1: Pierwsza płatność z rejestracją aliasu [](#krok-1-pierwsza-płatność-z-rejestracją-aliasu) Podczas pierwszej płatności klient wpisuje 6-cyfrowy kod BLIK, a Ty rejestrujesz alias, aby umożliwić przyszłe płatności bez kodu: ``` use SimPay\SDK\BlikAlias; $alias = BlikAlias::register( label: 'Nazwa Twojego Sklepu', // Zgodna z certyfikacją BLIK value: 'unikalne_id_klienta_123' // Twoje wewnętrzne ID klienta ); $simpay->client()->sendBlikLevel0($transactionId, '123456', $alias); ``` #### Krok 2: Obsługa IPN aliasu (`blik:alias_status_changed`) [](#krok-2-obsługa-ipn-aliasu-blikalias_status_changed) Po płatności aplikacja bankowa zapyta klienta o zapis sklepu jako zaufanego. Nasłuchuj zdarzenia IPN `blik:alias_status_changed`: ``` $ipn = $simpay->handleIpn($payload, $userAgent, $remoteIp); if ($ipn->isBlikAliasEvent() && $ipn->isAliasActive()) { $aliasUuid = $ipn->getAliasId(); // UUID aliasu SimPay // Zapisz $aliasUuid w bazie danych przy koncie klienta $db->saveAliasUuid($userId, $aliasUuid); } ``` #### Krok 3: Płatność OneClick (bez kodu BLIK) [](#krok-3-płatność-oneclick-bez-kodu-blik) **Metoda A — przez UUID SimPay** (rekomendowana, zawsze jednoznaczna): ``` $alias = BlikAlias::fromUuid( uuid: $savedAliasUuid, // UUID z kroku 2 label: 'Nazwa Twojego Sklepu' ); $simpay->client()->sendBlikOneClick($transactionId, $alias); // HTTP 204 — klient dostaje push w aplikacji bankowej ``` **Metoda B — przez własne ID klienta** (value + type): ``` $alias = BlikAlias::fromValue( value: 'unikalne_id_klienta_123', label: 'Nazwa Twojego Sklepu' ); $simpay->client()->sendBlikOneClick($transactionId, $alias); ``` #### Obsługa błędu ALIAS\_NOT\_UNIQUE [](#obsługa-błędu-alias_not_unique) Gdy klient ma kilka aplikacji bankowych podpiętych pod to samo ID (tylko Metoda B): ``` use SimPay\SDK\Exception\AliasNotUniqueException; try { $simpay->client()->sendBlikOneClick($transactionId, $alias); } catch (AliasNotUniqueException $e) { // Wyświetl klientowi wybór banku $alternatives = $e->getAlternatives(); // Każda alternatywa: ['label' => 'PKO BP', 'blik_id' => 953824, ...] // Po wyborze klienta — ponów z blik_id: $selectedBlikId = $alternatives[$userChoice]['blik_id']; $resolvedAlias = $alias->withBlikId($selectedBlikId); $simpay->client()->sendBlikOneClick($transactionId, $resolvedAlias); } ``` ### Kanały płatności [](#kanały-płatności) ``` $channels = $simpay->client()->getChannels(); ``` Adapter HTTP (opcjonalny) ------------------------- [](#adapter-http-opcjonalny) Domyślnie SDK używa cURL. Jeśli platforma wymaga innego klienta HTTP: ``` use SimPay\SDK\Http\HttpClientInterface; use SimPay\SDK\Http\HttpResponse; class WordPressHttpClient implements HttpClientInterface { public function request(string $method, string $url, array $headers = [], ?array $body = null, int $timeout = 30): HttpResponse { $response = wp_remote_request($url, [ 'method' => $method, 'headers' => $headers, 'timeout' => $timeout, 'body' => $body !== null ? json_encode($body) : null, ]); if (is_wp_error($response)) { throw new \SimPay\SDK\Exception\HttpException($response->get_error_message()); } return new HttpResponse( wp_remote_retrieve_response_code($response), wp_remote_retrieve_body($response) ); } } $simpay = new SimPay($bearer, $serviceId, $signatureKey, 'wordpress', $version, new WordPressHttpClient()); ``` Adapter Cache (opcjonalny) -------------------------- [](#adapter-cache-opcjonalny) Przyspiesza walidację IP — zamiast odpytywać API przy każdym IPN: ``` use SimPay\SDK\CacheInterface; class PrestaShopCache implements CacheInterface { public function get(string $key): mixed { $val = \Cache::getInstance()->get($key); return $val !== false ? $val : null; } public function set(string $key, mixed $value, int $ttl = 3600): void { \Cache::getInstance()->set($key, $value, $ttl); } public function delete(string $key): void { \Cache::getInstance()->delete($key); } } $simpay = new SimPay($bearer, $serviceId, $signatureKey, 'prestashop', _PS_VERSION_, null, new PrestaShopCache()); ``` Stałe statusów -------------- [](#stałe-statusów) ``` use SimPay\SDK\PaymentStatus; PaymentStatus::isPaid($status); // transaction_paid | transaction_confirmed PaymentStatus::isFinal($status); // paid, confirmed, canceled, expired, failure, fraud, refunded PaymentStatus::isFailed($status); // canceled, expired, failure, fraud // Stałe do użycia w match/switch: PaymentStatus::TRANSACTION_PAID PaymentStatus::TRANSACTION_CANCELED PaymentStatus::TRANSACTION_EXPIRED PaymentStatus::TRANSACTION_FAILURE PaymentStatus::TRANSACTION_FRAUD PaymentStatus::TRANSACTION_REFUNDED // BLIK OneClick: PaymentStatus::ALIAS_ACTIVE PaymentStatus::ALIAS_INACTIVE PaymentStatus::ALIAS_PENDING // Typy eventów IPN: PaymentStatus::TYPE_TRANSACTION_STATUS // 'transaction:status_changed' PaymentStatus::TYPE_REFUND_STATUS // 'transaction_refund:status_changed' PaymentStatus::TYPE_BLIK_ALIAS_STATUS // 'blik:alias_status_changed' PaymentStatus::TYPE_BLIK_CODE_STATUS // 'transaction_blik_level0:code_status_changed' ``` ### Health Score 40 — FairBetter than 86% of packages Maintenance94 Actively maintained with recent releases Popularity7 Limited adoption so far Community6 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~10 days Total 3 Last Release 25d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/dcbdde5ed4a48005dff9c3bdef0c89347bb22dc6a95cd3701db8d9312fcd4587?d=identicon)[SimPay](/maintainers/SimPay) --- Top Contributors [![pawlo-code](https://avatars.githubusercontent.com/u/82768530?v=4)](https://github.com/pawlo-code "pawlo-code (4 commits)") --- Tags paymentsgatewayecommercephp-sdksimpay ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/simpay-ecommerce/health.svg) ``` [![Health](https://phpackages.com/badges/simpay-ecommerce/health.svg)](https://phpackages.com/packages/simpay-ecommerce) ``` ### Alternatives [cybersource/rest-client-php Client SDK for CyberSource REST APIs 40952.8k6](/packages/cybersource-rest-client-php)[sylius/payment-bundle Flexible payments system for Symfony e-commerce applications. 22290.4k10](/packages/sylius-payment-bundle)[sebdesign/laravel-viva-payments A Laravel package for integrating the Viva Payments gateway 4851.0k](/packages/sebdesign-laravel-viva-payments)[sylius/payment Flexible payments system for PHP e-commerce applications. 17350.1k11](/packages/sylius-payment)[litle/payments-sdk The Vantiv eCommerce PHP SDK is a PHP implementation of the \[Vantiv eCommerce\](https://developer.vantiv.com/community/ecommerce). XML API. This SDK was created to make it as easy as possible to connect process your payments with Vantiv eCommerce 19140.4k1](/packages/litle-payments-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)