PHPackages alma/alma-php-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. [API Development](/categories/api) 4. / 5. alma/alma-php-client ActiveLibrary[API Development](/categories/api) alma/alma-php-client ==================== PHP API client for the Alma payments API 2.6.1(8mo ago)18639.5k↓13%10[8 PRs](https://github.com/alma/alma-php-client/pulls)6MITPHPPHP ^5.6 || ~7.0 || ~7.1 || ~7.2 || ~7.3 || ~7.4 || ~8.0 || ~8.1 || ~8.2 || ~8.3CI passing Since Dec 7Pushed 2mo ago3 watchersCompare [ Source](https://github.com/alma/alma-php-client)[ Packagist](https://packagist.org/packages/alma/alma-php-client)[ RSS](/packages/alma-alma-php-client/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (7)Versions (107)Used By (6) Alma PHP API client =================== [](#alma-php-api-client) This is the official PHP API client for [Alma](https://getalma.eu). This PHP API Client is being used in production on thousands of e-commerce websites and provides the necessary endpoints to build a full-fledge integration. It does not, however, implement the full Alma API as [documented here](https://api.getalma.eu/docs) yet. If you find yourself needing to use some endpoints that are not yet implemented, feel free to reach out! (or even better, submit a PR :)) Installation ------------ [](#installation) The Alma PHP API Client library is tested against all recently supported PHP versions. A modern, [supported PHP version](https://www.php.net/supported-versions.php) is highly recommended. ### Composer [](#composer) You would normally install this package via Composer: ``` composer require alma/alma-php-client ``` ### Without Composer [](#without-composer) - Head over to the [releases](https://github.com/alma/alma-php-client/releases) and grab the `alma-php-client.zip` file of the latest published library version. - Unzip the library into your vendors directory. - Require the included Composer's autoload file: ``` require_once "path/to/alma-php-client/vendor/autoload.php"; ``` - You should then be able to use Alma as if it was installed with Composer. Typical usage ------------- [](#typical-usage) An example of using the API client. (check [API documentation](https://docs.getalma.eu/reference/) for further information) ### 1. instanciate client in test mode [](#1-instanciate-client-in-test-mode) ``` $alma = new Alma\API\Client($apiKey, ['mode' => Alma\API\Client::TEST_MODE]); ``` ### 2. check eligibility [](#2-check-eligibility) ``` // ... $amountInCents = 150000; // 1500 euros $customerBillingCountry = ""; // can be an empty string but NOT null $customerShippingCountry = "FR"; // billing_address has priority over shipping_address (if not empty) try { $eligibilities = $alma->payments->eligibility( [ 'purchase_amount' => $amountInCents, 'billing_address' => [ // (optional) useful to check eligibility for a specific billing country 'country' => $customerBillingCountry // can be an empty string but not null ], 'shipping_address' => [ // (optional) useful to check eligibility for a specific shipping country 'country' => $customerShippingCountry ], 'queries' => [ [ 'installments_count' => 1, 'deferred_days' => 30, ], [ 'installments_count' => 2, ], [ 'installments_count' => 3, ], [ 'installments_count' => 4, ], [ 'installments_count' => 10, ], ], ], $raiseOnError = true // throws an exception on 4xx or 5xx http return code // instead of just returning an Eligibility Object with isEligible() === false ); } catch (Alma\API\RequestError $error) { header("HTTP/1.1 500 Internal Server Error"); die($error->getMessage()); } foreach($eligibilities as $eligibility) { if (!$eligibility->isEligible()) { die('cart is not eligible'); } } // ... ``` ### 3. check available fee plans and build payment form [](#3-check-available-fee-plans-and-build-payment-form) ``` // ... echo ""; echo "Available feePlans are:"; foreach($alma->merchants->feePlans($kind = FeePlan::KIND_GENERAL, $installmentsCounts = "all", $includeDeferred = true) as $feePlan) { if (!$feePlan->allowed) { continue; } printf('Pay in %s by %s installments count', $feePlan->getPlanKey(), $feePlan->getDeferredDays(), $feePlan->getInstallmentsCount()); printf('', $feePlan->getPlanKey(), $feePlan->getPlanKey()); } echo "Submit"; echo ""; // ... ``` You can prefer use eligibilities to do this work but this part of code allow you to get more familiar with feePlans definitions. ### 4. build a payment plan [](#4-build-a-payment-plan) ``` // ... function formatMoney(int $amount) { return sprintf("%.2f %s", round(intval($amount) / 100, 2), "€"); } function formatPercent(int $amount) { return sprintf("%.2f %s", round(intval($amount) / 100, 2), "%"); } // ... foreach($eligibilities as $eligibility) { // display following payment plan (or not eligible message) on feePlan selection using javascript. printf('', $eligibility->getPlanKey()); if (!$eligibility->isEligible()) { echo "This fee plan is not eligible!"; echo ""; continue; } if (!$paymentPlans = $eligibility->getPaymentPlan()) { echo "No payment plan found for current eligibility! (that should not happen)"; echo ""; continue; } echo ""; foreach ($paymentPlans as $paymentPlan) { $planDefinition = sprintf( "You will pay %s on %s including %s fees & %s of interest", formatMoney($paymentPlan['total_amount']), (new DateTime())->setTimestamp($paymentPlan['due_date'])->format('Y-m-d'), formatMoney($paymentPlan['customer_fee']), formatMoney($paymentPlan['customer_interest']) ); } echo ""; echo " "; echo " Annual Interest Rate:" . formatPercent($eligibility->getAnnualInterestRate()) . ""; echo " Order Amount:" . formatMoney($amountInCents); echo " Total Cost Amount:" . formatMoney($eligibility->getCustomerTotalCostAmount()); echo " "; echo ""; } // ... ``` ### 5. create a payment and redirecting a customer to the payment page [](#5-create-a-payment-and-redirecting-a-customer-to-the-payment-page) ``` // ... $payment = $alma->payments->createPayment( [ 'origin' => 'online', 'payment' => [ 'return_url' => '', 'ipn_callback_url' => '', 'purchase_amount' => 150000, 'installments_count' => 4, 'custom_data' => [ 'my_very_important_key' => '', ], 'locale' => 'fr', 'billing_address' => [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john-doe@yopmail.fr', 'line1' => '1 rue de Rome', 'postal_code' => '75001', 'city' => 'Paris', 'country' => 'FR', ], 'shipping_address' => [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john-doe@yopmail.fr', 'line1' => '1 rue de Rome', 'postal_code' => '75001', 'city' => 'Paris', 'country' => 'FR', ], ], 'customer' => [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john-doe@yopmail.fr', 'phone' => '06 12 34 56 78', 'addresses' => [ [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => 'john-doe@yopmail.fr', 'phone' => '06 12 34 56 78', ], ], ], ] ); // store $payment->id and link it to the customer order here ;) header('Location: ' . $payment->url); exit(); // ... ``` ### 6. receive notification about payment validation by IPN [](#6-receive-notification-about-payment-validation-by-ipn) (can be given on payment creation or statically defined in your Alma Dashboard) ``` // ... if (!isset($_GET['pid']) || empty($_GET['pid'])) { header("HTTP/1.1 400 Bad Request"); die(); } // retrieve your local order by payment id $order = getOrderByPaymentId($_GET['pid']) if (!$order) { header("HTTP/1.1 404 Not Found"); die(); } // check $payment->state & do the order / customer stuff you want here :D header("HTTP/1.1 200"); exit(); // ... ``` ### 7. retrieve payment information and display status [](#7-retrieve-payment-information-and-display-status) ``` // ... $payment = $alma->payments->fetch($paymentId); switch($payment->state) { case Alma\API\Entities\Payment::STATE_IN_PROGRESS: break; case Alma\API\Entities\Payment::STATE_PAID: break; } // ... ``` License ------- [](#license) Alma PHP Client is distributed under [the MIT license](LICENSE). ### Health Score 66 — FairBetter than 99% of packages Maintenance76 Regular maintenance activity Popularity48 Moderate usage in the ecosystem Community31 Small or concentrated contributor base Maturity92 Battle-tested with a long release history Bus Factor3 3 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 ~42 days Recently: every ~79 days Total 60 Last Release 242d ago Major Versions v0.0.7 → v1.0.02019-03-01 1.11.2 → 2.0.02024-01-24 PHP version history (4 changes)v1.5.1PHP ^5.6 v1.5.2PHP >=5.6 1.11.1PHP ^5.6 || ~7.0 || ~7.1 || ~7.2 || ~7.3 || ~7.4 || ~8.0 || ~8.1 || ~8.2 2.1.0PHP ^5.6 || ~7.0 || ~7.1 || ~7.2 || ~7.3 || ~7.4 || ~8.0 || ~8.1 || ~8.2 || ~8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/d9536070edb2e5206ca489e7cce6f6a8cdecf2da9a4f64d9be3d82c6204565d8?d=identicon)[alma\_integrations](/maintainers/alma_integrations) --- Top Contributors [![Francois-Gomis](https://avatars.githubusercontent.com/u/97046219?v=4)](https://github.com/Francois-Gomis "Francois-Gomis (94 commits)")[![Benjamin-Freoua-Alma](https://avatars.githubusercontent.com/u/89775252?v=4)](https://github.com/Benjamin-Freoua-Alma "Benjamin-Freoua-Alma (93 commits)")[![olance](https://avatars.githubusercontent.com/u/314079?v=4)](https://github.com/olance "olance (72 commits)")[![joyet-simon](https://avatars.githubusercontent.com/u/43644110?v=4)](https://github.com/joyet-simon "joyet-simon (63 commits)")[![carine-bonnafous](https://avatars.githubusercontent.com/u/131184161?v=4)](https://github.com/carine-bonnafous "carine-bonnafous (35 commits)")[![ClaireAlma](https://avatars.githubusercontent.com/u/110386752?v=4)](https://github.com/ClaireAlma "ClaireAlma (29 commits)")[![alma-renovate-bot[bot]](https://avatars.githubusercontent.com/in/855130?v=4)](https://github.com/alma-renovate-bot[bot] "alma-renovate-bot[bot] (22 commits)")[![gdraynz](https://avatars.githubusercontent.com/u/5525902?v=4)](https://github.com/gdraynz "gdraynz (18 commits)")[![syjust-alma](https://avatars.githubusercontent.com/u/103112683?v=4)](https://github.com/syjust-alma "syjust-alma (14 commits)")[![remi-zuffinetti](https://avatars.githubusercontent.com/u/117717315?v=4)](https://github.com/remi-zuffinetti "remi-zuffinetti (7 commits)")[![PaulRouss3l](https://avatars.githubusercontent.com/u/40837250?v=4)](https://github.com/PaulRouss3l "PaulRouss3l (6 commits)")[![webaaz](https://avatars.githubusercontent.com/u/489498?v=4)](https://github.com/webaaz "webaaz (6 commits)")[![arnaudrolland](https://avatars.githubusercontent.com/u/3249959?v=4)](https://github.com/arnaudrolland "arnaudrolland (5 commits)")[![raharima](https://avatars.githubusercontent.com/u/1227734?v=4)](https://github.com/raharima "raharima (3 commits)")[![remic-alma](https://avatars.githubusercontent.com/u/121117838?v=4)](https://github.com/remic-alma "remic-alma (3 commits)")[![Jir4](https://avatars.githubusercontent.com/u/717155?v=4)](https://github.com/Jir4 "Jir4 (3 commits)")[![CamilleFljt](https://avatars.githubusercontent.com/u/112871182?v=4)](https://github.com/CamilleFljt "CamilleFljt (3 commits)")[![hyahiaoui](https://avatars.githubusercontent.com/u/27744312?v=4)](https://github.com/hyahiaoui "hyahiaoui (2 commits)")[![Natim](https://avatars.githubusercontent.com/u/229453?v=4)](https://github.com/Natim "Natim (1 commits)")[![iseghiri](https://avatars.githubusercontent.com/u/25384332?v=4)](https://github.com/iseghiri "iseghiri (1 commits)") --- Tags almaapi-clientphpphp-library ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/alma-alma-php-client/health.svg) ``` [![Health](https://phpackages.com/badges/alma-alma-php-client/health.svg)](https://phpackages.com/packages/alma-alma-php-client) ``` ### Alternatives [sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.4k5.6M651](/packages/sylius-sylius)[algolia/algoliasearch-client-php API powering the features of Algolia. 69433.0M114](/packages/algolia-algoliasearch-client-php)[theodo-group/llphant LLPhant is a library to help you build Generative AI applications. 1.5k311.5k5](/packages/theodo-group-llphant)[wheelpros/fitment-platform-api Magento 2 (Open Source) 12.1k1.2k](/packages/wheelpros-fitment-platform-api)[avalara/avataxclient Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API. 517.9M7](/packages/avalara-avataxclient)[alexacrm/dynamics-webapi-toolkit Web API toolkit for Microsoft Dynamics 365 and Dynamics CRM 81324.1k1](/packages/alexacrm-dynamics-webapi-toolkit) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)