Download the PHP package tapbuy/alma without Composer

Tapbuy Alma Module

A Magento 2 module that extends the Alma Monthly Payments functionality to integrate with Tapbuy's GraphQL payment processing system.

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

• 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

• Magento 2.x
• PHP 7.4+ or 8.x
• Alma Monthly Payments module
• Magento GraphQL module

Installation

Composer Installation (Recommended)

1. Add the module to your Magento project:

2. Enable the module:

3. Run setup upgrade:

4. Compile if needed:

5. Clear cache:

Manual Installation

1. Create the directory structure:

2. Copy all module files to the directory
3. Follow steps 2-5 from the Composer installation

How It Works

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

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

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

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:

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:

URL Mapping

File Structure

Dependencies

Module Dependencies

• Magento_GraphQl: Required for GraphQL functionality

Plugin Target

• Alma\MonthlyPayments\Gateway\Request\PaymentDataBuilder: The Alma module's payment data builder

Development

Plugin Configuration

The plugin is configured in etc/di.xml:

Key Classes

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

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

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:

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:

alma/alma-monthlypayments-magento2 is cloned automatically to ~/.tapbuy-ci-cache/ on first run.

First-time setup:

Run all unit tests:

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.

Linting

Linting runs PHPMD and PHPCS (Magento2 standard) inside the same Docker container as tests. Docker must be running.

Run both linters:

Run individually:

Both linters always run when using make lint; if either fails, the command exits with a non-zero code.