README

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)

Add the module to your Magento project:

composer require tapbuy/alma

Enable the module:

php bin/magento module:enable Tapbuy_Alma

Run setup upgrade:

php bin/magento setup:upgrade

Compile if needed:

php bin/magento setup:di:compile

Clear cache:

php bin/magento cache:clean

Manual Installation

Create the directory structure:

app/code/Tapbuy/Alma/

Copy all module files to the directory
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:

Validates Request Headers: Checks for the X-Tapbuy-Call header to ensure the request originates from Tapbuy
Extracts Tapbuy Information: Retrieves serialized Tapbuy data from payment additional information
Deserializes Data: Safely unserializes the Tapbuy data using Magento's serializer
Maps URLs: Maps Tapbuy URLs to Alma payment parameters:
- accept_url → return_url
- cancel_url → customer_cancel_url and failure_return_url
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:

X-Tapbuy-Call: 1

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

Tapbuy Parameter	Alma Parameter	Description
`accept_url`	`return_url`	Success redirect URL
`cancel_url`	`customer_cancel_url`	Customer cancellation URL
`cancel_url`	`failure_return_url`	Payment failure URL

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

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:

<type name="Alma\MonthlyPayments\Gateway\Request\PaymentDataBuilder">
    <plugin name="tapbuy_alma_payment_data_builder" 
            type="Tapbuy\Alma\Plugin\PaymentDataBuilderPlugin"
            sortOrder="10"/>
</type>

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

Module Not Loading
- Verify module is enabled: php bin/magento module:status Tapbuy_Alma
- Check registration.php path is correct
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
Serialization Errors
- Check that Tapbuy data is properly serialized before storage
- Verify JSON format if using JSON serialization
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:

} catch (\Exception $e) {
    // Add logging here if needed
    $this->logger->error('Tapbuy Alma plugin error: ' . $e->getMessage());
}

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.

Linting

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

Run both linters:

make lint

Run individually:

make phpmd   # PHP Mess Detector
make phpcs   # PHP CodeSniffer (Magento2 standard)

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

tapbuy / alma

Package info

Security

Statistics