PHPackages thepay/api-client - 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. thepay/api-client ActiveLibrary[Payment Processing](/categories/payments) thepay/api-client ================= API client for ThePay - payment gate API v3.0.0(1mo ago)6400.1k↓35.5%12PHPPHP ~7.4|~8.0CI passing Since Oct 15Pushed 1mo ago5 watchersCompare [ Source](https://github.com/ThePay/api-client)[ Packagist](https://packagist.org/packages/thepay/api-client)[ RSS](/packages/thepay-api-client/feed)WikiDiscussions v3.x Synced 2d ago READMEChangelog (10)Dependencies (22)Versions (51)Used By (2) PHP SDK for ThePay.cz ===================== [](#php-sdk-for-thepaycz) This is the official highly compatible public package of The Pay SDK which interacts with The Pay's REST API. To get started see examples below. Requirements ------------ [](#requirements) All necessary requirements are defined in [composer.json](../composer.json) `require` property. We strongly recommend SDK installation using [Composer](https://getcomposer.org/)! Installation ------------ [](#installation) ``` composer require thepay/api-client ``` Installation with suggested PSR http client. ``` composer require thepay/api-client guzzlehttp/guzzle ``` This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Support & Contributions --------------------------- [](#support--contributions) If you find any bug, please submit the [issue](https://github.com/ThePay/api-client/issues/new/choose) to GitHub directly. Feel free to contribute via Github [issues](https://github.com/ThePay/api-client/issues) and [pull requests](https://github.com/ThePay/api-client/pulls). We will respond as soon as possible. Please keep in mind backward compatibility, and do not change the requirements without prior administrator agreement. Preconditions ------------- [](#preconditions) ### Testing the integration [](#testing-the-integration) **To test the integration** you can create simplified "ready-to-go" DEMO account in our [DEMO environment](https://demo.admin.thepay.cz/registration). You can find all the necessary credentials in "Implementation" section under your merchant profile: [![](../doc/img/the-admin-credentials.png)](../doc/img/the-admin-credentials.png) ### Access credentials [](#access-credentials) Make sure that you have all required credentials and that you've set up the API access in [administration](https://admin.thepay.cz), in the Implementation section. The required credentials are: - merchant ID - project ID - password for API access ### IP address whitelisting [](#ip-address-whitelisting) You must whitelist the IP address of the machine which will be accessing the API in the project settings. You can use a particular IP address or specify a range. The whitelisting setup can be found in the same place as the credentials, that is the Implementation section of the administration. Usage ----- [](#usage) You will work with two classes when using this SDK. - TheConfig - for setting up the library - TheClient - for core functionality (calling the API, rendering helpers) Configuration with TheConfig ---------------------------- [](#configuration-with-theconfig) All constructor parameters are described in [php doc](../src/TheConfig.php) ``` $merchantId = '86a3eed0-95a4-11ea-ac9f-371f3488e0fa'; $projectId = 3; $apiPassword = 'secret'; $apiUrl = 'https://demo.api.thepay.cz/'; // production: 'https://api.thepay.cz/' $gateUrl = 'https://demo.gate.thepay.cz/'; // production: 'https://gate.thepay.cz/' $language = 'cs'; $theConfig = new \ThePay\ApiClient\TheConfig( $merchantId, $projectId, $apiPassword, $apiUrl, $gateUrl ); $theConfig->setLanguage($language); ``` TheClient instance ------------------ [](#theclient-instance) Make sure to prepare the necessary dependencies before creating the `\ThePay\ApiClient\TheClient` instance. In any case of dependencies preparation, you MUST check if your PSR-18 HTTP client, will return real PSR-7 network stream! Because some API endpoints are not paginated for example: [getAccountStatementGPC](../doc/download-account-transaction-GPC.md), and can contain big amount of data! If an HTTP client will try load full response to memory, some of your API calls can crash on out of memory error! ### With dependency injection [](#with-dependency-injection) If you're using automatic dependency injection (as most frameworks do), all dependencies except `TheConfig`(which you configured in the previous section) will be injected automatically - including PSR-standard interfaces, provided your application already includes implementations of them. ### Without dependency injection [](#without-dependency-injection) In case you are not using dependency injection, you will have to set up the classes manually as shown in the following example: ``` /** @var \ThePay\ApiClient\TheConfig $theConfig */ // TheClient instance dependencies $signatureService = new \ThePay\ApiClient\Service\SignatureService($theConfig); /** @var \Psr\Http\Client\ClientInterface $httpClient some PSR-18 implementation */ /** @var \Psr\Http\Message\RequestFactoryInterface $requestFactory some PSR-17 implementation */ /** @var \Psr\Http\Message\StreamFactoryInterface $streamFactory some PSR-17 implementation */ // if you install suggested guzzle implementation you can use this: // you MUST use RequestOptions::STREAM with true value! // https://docs.guzzlephp.org/en/stable/request-options.html#stream // $httpClient = new \GuzzleHttp\Client([\GuzzleHttp\RequestOptions::STREAM => true]); // $requestFactory = $streamFactory = new \GuzzleHttp\Psr7\HttpFactory(); $apiService = new \ThePay\ApiClient\Service\ApiService( $theConfig, $signatureService, $httpClient, $requestFactory, $streamFactory ); $thePayClient = new \ThePay\ApiClient\TheClient( $theConfig, $apiService ); ``` Usual payment workflow ---------------------- [](#usual-payment-workflow) Creating a payment involves three steps: - creating a payment link through which the customer will realize the payment - handling the return of a customer to your website - handling server-to-server notifications which are sent by us every time the payment state is changed All of these steps will need to be implemented by yourself, but fear not, we have prepared examples that you can take on your journey through our SDK. ### 1. Payment creation [](#1-payment-creation) #### REST API [](#rest-api) The payment is created via the REST API, after which the customer is typically redirected to the URL provided in the response. ``` /** @var \ThePay\ApiClient\TheClient $thePayClient */ /** @var \ThePay\ApiClient\Model\CreatePaymentCustomer $customer */ // Specify the payment parameters (100,- Kč) including it's unique identifier $paymentParams = new \ThePay\ApiClient\Model\CreatePaymentParams(10000, 'CZK', 'uid123', $customer); // Get the payment link and redirect the customer whenever you want $payment = $thePayClient->createPayment($paymentParams); $redirectLink = $payment->getPayUrl(); ``` For more details and examples see [Payment creation](../doc/create-payment.md#creating-payment). #### Payment method [](#payment-method) By default, the customer selects their preferred payment method directly at ThePay gateway. This is the most common approach used by e-shops. If needed, you can also preselect the payment method on your side before redirecting the customer. In this case, the payment will be initialized with the chosen method already set. For details and examples of fetching available methods, preselecting a method, changing it, or preventing customers from changing it, see [Managing payment methods](../doc/managing-payment-methods). #### Payment amount is unchangeable [](#payment-amount-is-unchangeable) ⚠️ Please note that the amount specified during payment creation cannot be changed later. Once a payment is created, it is not possible to modify the amount. This means that if the order is updated on your side and the final amount changes, you will need to create a new payment by making a new API call with the updated amount and a new unique identifier. #### Payment flow and changes [](#payment-flow-and-changes) You should always create only one payment (with its unique UID) for each order in your e-shop. This means that if the customer navigates back and forth, they should use the same payment link to complete the process. A new payment should be created only if the order itself changes (e.g., the final amount changes). #### TL;DR - summary [](#tldr---summary) - The payment is created via a call to our API. - The payment method selection can be done either in your e-shop or through ThePay gateway. - Always create only one payment per order, regardless of how the payment is initiated — unless the payment amount changes. In that case, treat it as an entirely new payment. ### 2. Customer return [](#2-customer-return) After a successful payment — or if the customer decides to return to the e-shop without completing the payment — they are redirected to the return URL. #### Return URL address [](#return-url-address) The return URL should point to the page in your e-shop where you want the customer to land after leaving the payment gateway. You can set the return URL either in ThePay administration or by passing it as a parameter when creating the payment. - If the return URL is set in ThePay administration, the parameter is optional and will override the configured value if provided. - If the return URL is *not* set in ThePay administration, then the parameter is *required* when creating the payment. #### Query parameters [](#query-parameters) When the customer is redirected, two query parameters are appended to the URL: - payment\_uid - project\_id These parameters can be used, for example, to distinguish between different projects if you use the same return endpoint for multiple e-shops. #### Payment state check upon return [](#payment-state-check-upon-return) The payment state must always be verified when the customer returns to your e-shop, as it may not yet be in the "paid" state. For example, the customer might return without completing the payment. #### General example of handling the customer return [](#general-example-of-handling-the-customer-return) [See how to make TheClient](#theclient-instance) ``` /** @var \ThePay\ApiClient\TheClient $thePayClient */ $payment = $thePayClient->getPayment($uid); // check if the payment is paid if ($payment->wasPaid()) { // Check if the order isn't labeled as paid yet in your e-shop. If not, do so here. // ... } ``` ### 3. Server-to-server notification [](#3-server-to-server-notification) A payment may take some time to process, or the customer may not return to your e-shop (e.g., by closing the browser window). You don’t need to worry about this — whenever the payment state changes, we will automatically send a server-to-server notification to your system. Notifications are triggered every time the payment state changes, for example, when the payment is completed or expires. Because not all state changes indicate a successful payment, you must always verify the current payment state upon receiving a notification to determine what has actually occurred. #### Notification URL [](#notification-url) Similar to the return URL, the notification URL can be set either in ThePay administration or passed as a parameter when creating the payment #### Payment state check upon receiving a notification [](#payment-state-check-upon-receiving-a-notification) The payment state check you perform here is the same as the one you should do when the customer returns to your e-shop. [See how to make TheClient](#theclient-instance) ``` /** @var \ThePay\ApiClient\TheClient $thePayClient */ $payment = $thePayClient->getPayment($uid); // check if the payment is paid if ($payment->wasPaid()) { // Check if the order isn't labeled as paid yet. If not, do so here. // ... } ``` More and detailed usage examples -------------------------------- [](#more-and-detailed-usage-examples) You can find more usage examples at [folder /doc](../doc/index.md). Money calculations ------------------ [](#money-calculations) For safe and accurate money calculations, we recommend using the [moneyphp/money](https://github.com/moneyphp/money) package. Please do not use floats to store or calculate prices, as they can lead to precision errors. ``` composer require moneyphp/money ``` ### Health Score 60 — FairBetter than 98% of packages Maintenance90 Actively maintained with recent releases Popularity41 Moderate usage in the ecosystem Community24 Small or concentrated contributor base Maturity73 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits 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 ~45 days Recently: every ~12 days Total 46 Last Release 51d ago Major Versions v1.7.0 → v2.0.02023-08-21 v1.7.1 → v2.1.32025-04-29 v1.x-dev → v2.x-dev2026-05-12 v2.x-dev → v3.0.02026-05-12 PHP version history (4 changes)v1.0.0PHP ~5.3|~7.0 v1.1.5PHP ~5.3|~7.0|~8.0 v2.0.0PHP ~7.4|~8.0 v1.7.1PHP ~5.3 || ~7.0 || >=8.0 <8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/3424a3040bd1ccb71ea3eaa16ba318720fee3dae91463571108bf599a23ba207?d=identicon)[dajc@thepay.cz](/maintainers/dajc@thepay.cz) ![](https://www.gravatar.com/avatar/64a6cbe4471b93105c8cc507ad87bf454ec387e43d3e6ce65252681052ece620?d=identicon)[ThePayIT](/maintainers/ThePayIT) ![](https://www.gravatar.com/avatar/8a456805dab25d1c9ea236d7edc025eb9326dcd48dedea82ae2ba06aae9d309c?d=identicon)[JT](/maintainers/JT) --- Top Contributors [![Triplkrypl](https://avatars.githubusercontent.com/u/15320684?v=4)](https://github.com/Triplkrypl "Triplkrypl (142 commits)")[![AlexKratky](https://avatars.githubusercontent.com/u/33813757?v=4)](https://github.com/AlexKratky "AlexKratky (106 commits)")[![tymajiri](https://avatars.githubusercontent.com/u/36740383?v=4)](https://github.com/tymajiri "tymajiri (61 commits)")[![joseftraxler](https://avatars.githubusercontent.com/u/98177220?v=4)](https://github.com/joseftraxler "joseftraxler (43 commits)")[![petrknap](https://avatars.githubusercontent.com/u/8299754?v=4)](https://github.com/petrknap "petrknap (9 commits)")[![nofutur3](https://avatars.githubusercontent.com/u/1681221?v=4)](https://github.com/nofutur3 "nofutur3 (8 commits)")[![jirkadajc](https://avatars.githubusercontent.com/u/1590760?v=4)](https://github.com/jirkadajc "jirkadajc (7 commits)")[![blackwolf-cz](https://avatars.githubusercontent.com/u/360896?v=4)](https://github.com/blackwolf-cz "blackwolf-cz (5 commits)")[![xhomap](https://avatars.githubusercontent.com/u/15964891?v=4)](https://github.com/xhomap "xhomap (2 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/thepay-api-client/health.svg) ``` [![Health](https://phpackages.com/badges/thepay-api-client/health.svg)](https://phpackages.com/packages/thepay-api-client) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k34.4k15](/packages/tempest-framework)[guzzlehttp/psr7 PSR-7 message implementation that also provides common utility methods 8.0k1.1B4.0k](/packages/guzzlehttp-psr7)[typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 85036.3k](/packages/flow-php-flow)[cakephp/cakephp The CakePHP framework 8.9k19.5M1.8k](/packages/cakephp-cakephp)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k5.9M736](/packages/sylius-sylius) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)