PHPackages tapbuy/alma - 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. tapbuy/alma ActiveMagento2-module tapbuy/alma =========== Tapbuy Alma Payment for Magento 2 GraphQL 1.5.2(1mo ago)0241↓100%1OSL-3.0PHPPHP ^7.4 || ^8.1CI passing Since Jul 16Pushed 1mo agoCompare [ Source](https://github.com/tapbuy/magento-alma)[ Packagist](https://packagist.org/packages/tapbuy/alma)[ RSS](/packages/tapbuy-alma/feed)WikiDiscussions develop Synced 1mo ago READMEChangelogDependencies (4)Versions (12)Used By (0) Tapbuy Alma Module ================== [](#tapbuy-alma-module) A Magento 2 module that extends the Alma Monthly Payments functionality to integrate with Tapbuy's GraphQL payment processing system. Overview -------- [](#overview) This module provides a plugin that intercepts and modifies payment data for Alma Monthly Payments, specifically to handle custom return URLs provided by Tapbuy's additional payment information. Features -------- [](#features) - **Payment Data Enhancement**: Automatically adds custom return URLs and cancellation URLs to Alma payment requests - **Request Header Validation**: Validates Tapbuy requests using custom headers for enhanced security - **GraphQL Integration**: Designed to work seamlessly with Magento 2 GraphQL API - **Error Handling**: Graceful handling of serialization errors to prevent payment process interruption - **Flexible Configuration**: Uses additional payment information to customize payment flow URLs Requirements ------------ [](#requirements) - Magento 2.x - PHP 7.4+ or 8.x - Alma Monthly Payments module - Magento GraphQL module Installation ------------ [](#installation) ### Composer Installation (Recommended) [](#composer-installation-recommended) 1. Add the module to your Magento project: ``` composer require tapbuy/alma ``` 2. Enable the module: ``` php bin/magento module:enable Tapbuy_Alma ``` 3. Run setup upgrade: ``` php bin/magento setup:upgrade ``` 4. Compile if needed: ``` php bin/magento setup:di:compile ``` 5. Clear cache: ``` php bin/magento cache:clean ``` ### Manual Installation [](#manual-installation) 1. Create the directory structure: ``` app/code/Tapbuy/Alma/ ``` 2. Copy all module files to the directory 3. Follow steps 2-5 from the Composer installation How It Works ------------ [](#how-it-works) ### Plugin Architecture [](#plugin-architecture) The module uses Magento's plugin system to intercept the `Alma\MonthlyPayments\Gateway\Request\PaymentDataBuilder::build()` method using an `afterBuild` plugin. ### Payment Data Modification [](#payment-data-modification) When a payment is processed, the plugin: 1. **Validates Request Headers**: Checks for the `X-Tapbuy-Call` header to ensure the request originates from Tapbuy 2. **Extracts Tapbuy Information**: Retrieves serialized Tapbuy data from payment additional information 3. **Deserializes Data**: Safely unserializes the Tapbuy data using Magento's serializer 4. **Maps URLs**: Maps Tapbuy URLs to Alma payment parameters: - `accept_url` → `return_url` - `cancel_url` → `customer_cancel_url` and `failure_return_url` 5. **Updates Payment Data**: Modifies the payment array with the new URL configurations ### Error Handling [](#error-handling) The plugin includes robust error handling: - Validates request headers to ensure legitimate Tapbuy requests - Catches serialization exceptions - Prevents payment process interruption - Maintains original payment flow if Tapbuy data is unavailable or headers are missing Configuration ------------- [](#configuration) ### Request Headers [](#request-headers) The module validates requests using the `X-Tapbuy-Call` header. This header must be present for the plugin to process Tapbuy payment modifications: ``` X-Tapbuy-Call: 1 ``` ### Payment Additional Information Format [](#payment-additional-information-format) The module expects Tapbuy data to be stored in the payment's additional information under the key `tapbuy` as a serialized array: ``` $payment->setAdditionalInformation('tapbuy', $serializer->serialize([ 'accept_url' => 'https://your-domain.com/success', 'cancel_url' => 'https://your-domain.com/cancel' ])); ``` ### URL Mapping [](#url-mapping) Tapbuy ParameterAlma ParameterDescription`accept_url``return_url`Success redirect URL`cancel_url``customer_cancel_url`Customer cancellation URL`cancel_url``failure_return_url`Payment failure URLFile Structure -------------- [](#file-structure) ``` Tapbuy/Alma/ ├── Plugin/ │ └── PaymentDataBuilderPlugin.php # Main plugin class ├── etc/ │ ├── di.xml # Dependency injection configuration │ └── module.xml # Module declaration ├── composer.json # Composer configuration ├── registration.php # Module registration └── README.md # This file ``` Dependencies ------------ [](#dependencies) ### Module Dependencies [](#module-dependencies) - `Magento_GraphQl`: Required for GraphQL functionality ### Plugin Target [](#plugin-target) - `Alma\MonthlyPayments\Gateway\Request\PaymentDataBuilder`: The Alma module's payment data builder Development ----------- [](#development) ### Plugin Configuration [](#plugin-configuration) The plugin is configured in `etc/di.xml`: ``` ``` ### Key Classes [](#key-classes) #### PaymentDataBuilderPlugin [](#paymentdatabuilderplugin) - **Namespace**: `Tapbuy\Alma\Plugin` - **Purpose**: Modifies Alma payment data with Tapbuy-specific URLs - **Method**: `afterBuild()` - Plugin method that runs after the original build method - **Dependencies**: - `SerializerInterface` - For handling serialized payment data - `RequestInterface` - For accessing HTTP request headers Troubleshooting --------------- [](#troubleshooting) ### Common Issues [](#common-issues) 1. **Module Not Loading** - Verify module is enabled: `php bin/magento module:status Tapbuy_Alma` - Check registration.php path is correct 2. **Plugin Not Working** - Ensure DI compilation is up to date: `php bin/magento setup:di:compile` - Verify Alma module is installed and enabled - Check that the `X-Tapbuy-Call` header is being sent with requests 3. **Serialization Errors** - Check that Tapbuy data is properly serialized before storage - Verify JSON format if using JSON serialization 4. **Headers Not Detected** - Ensure the `X-Tapbuy-Call` header is included in HTTP requests - Verify server configuration allows custom headers - Check that headers are not being stripped by proxies or load balancers ### Logging [](#logging) The module handles errors gracefully but doesn't log them by default. For debugging, you can modify the exception handling in `PaymentDataBuilderPlugin.php` to add logging: ``` } catch (\Exception $e) { // Add logging here if needed $this->logger->error('Tapbuy Alma plugin error: ' . $e->getMessage()); } ``` ### Running Tests [](#running-tests) Tests run inside a Docker container that replicates the CI environment (PHP 8.3, Magento 2.4.7-p5). Docker must be running. **Prerequisites:** clone the following sibling repository next to this one: ``` # From the parent directory git clone git@github.com:tapbuy/magento-redirect-plugin.git redirect-tracking ``` `alma/alma-monthlypayments-magento2` is cloned automatically to `~/.tapbuy-ci-cache/` on first run. **First-time setup:** ``` cp auth.json.dist auth.json # Fill in your repo.magento.com public/private keys in auth.json ``` **Run all unit tests:** ``` make test ``` On the first run, the Docker image is built and Magento is installed into a named volume (`tapbuy-magento-2.4.7-p5-php83`). Subsequent runs reuse the cached volume and are fast. > Do not use `composer test` — it runs PHPUnit without the Magento bootstrap and will fail or produce misleading results. ### Health Score 43 — FairBetter than 91% of packages Maintenance89 Actively maintained with recent releases Popularity15 Limited adoption so far Community8 Small or concentrated contributor base Maturity51 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 ~26 days Recently: every ~7 days Total 10 Last Release 59d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/0740544e5d3c7a2192d15c1cca624832e271924f3b7135183a5815216c28560b?d=identicon)[jerome-tapbuy](/maintainers/jerome-tapbuy) ![](https://www.gravatar.com/avatar/f193163becacc7142aebf5cdcddf3c47d3c66c9476e2cbcc53e38ffb46b3561f?d=identicon)[valentin\_tapbuy](/maintainers/valentin_tapbuy) --- Top Contributors [![ValentinCreative](https://avatars.githubusercontent.com/u/1830588?v=4)](https://github.com/ValentinCreative "ValentinCreative (72 commits)") ### Embed Badge ![Health badge](/badges/tapbuy-alma/health.svg) ``` [![Health](https://phpackages.com/badges/tapbuy-alma/health.svg)](https://phpackages.com/packages/tapbuy-alma) ``` ### Alternatives [mollie/magento2 Mollie Payment Module for Magento 2 1121.6M10](/packages/mollie-magento2)[dotdigital/dotdigital-magento2-extension Dotdigital for Magento 2 50374.2k18](/packages/dotdigital-dotdigital-magento2-extension)[pagbank/payment-magento PagBank - Payment for Magento and Adobe 2128.3k7](/packages/pagbank-payment-magento) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)