Download the PHP package jeffreyvanhees/laravel-online-payment-platform without Composer

Laravel Online Payment Platform SDK

A modern Laravel package for integrating with the Online Payment Platform API. Built with SaloonPHP and Spatie Laravel Data for an excellent developer experience.

[!WARNING]
This package is not affiliated with, endorsed by, or officially connected to Online Payment Platform B.V. It is an independent, community-driven implementation for integrating with their API. Also, this package is not intended for production use yet. It is still in development and may contain breaking changes.

✨ Features

• 🚀 Laravel 11 & 12 Support - Full support for the latest Laravel versions
• 🛡️ Type Safety - Fully typed DTOs using Spatie Laravel Data
• 🏗️ Service Container - Native Laravel service container integration
• 🎭 Facade Support - Clean, expressive API using Laravel facades
• 🔧 SaloonPHP Foundation - Built on the robust SaloonPHP HTTP client
• 🧪 Comprehensive Testing - HTTP recording/replay for reliable tests
• 📚 Intuitive API - Fluent interface: OnlinePaymentPlatform::merchants()->ubos()->create()
• 🔄 Environment Support - Seamless sandbox/production switching
• ⚡ Exception Handling - Detailed custom exceptions for all error scenarios
• 🔄 Pagination Support - Built-in pagination with SaloonPHP

📋 Requirements

• PHP 8.2 or higher
• Laravel 11.0 or 12.0

🚀 Installation

Install the package via Composer:

Publish the configuration file:

Configure your API credentials and URLs in your .env file:

📚 API Documentation

📋 API Endpoints Index

• Merchants - Create consumer/business merchants, manage contacts, addresses, UBOs, and profiles
• Transactions - Create payments, retrieve status, update transaction details
• Refunds - Process transaction refunds and list refund history
• Global Settlements - Platform-wide settlement reporting and detailed rows
• Charges - Balance transfers between merchants and fee management
• Mandates - SEPA Direct Debit mandates and recurring transactions
• Withdrawals - Merchant payouts to bank accounts
• Disputes - Handle transaction disputes and chargebacks
• Files - Upload and manage documents for verification/evidence
• Partners - Partner configuration and settings management
• Pagination - Handle paginated API responses

🎯 Usage

The package provides multiple ways to interact with the Online Payment Platform API:

Using the Facade (Recommended)

The facade provides the cleanest and most Laravel-like API:

Using Dependency Injection

Inject the connector directly into your classes (or create instances using the make() method):

Using Type-Safe DTOs

For maximum type safety and IDE support, use the provided Data Transfer Objects:

Merchants

Update Operations

The SDK provides comprehensive update functionality for all merchant-related resources:

Sandbox Testing & Status Updates

For testing purposes, the SDK provides sandbox-only methods to simulate status changes:

Flexible Input Types

All SDK methods accept both DTOs and arrays for maximum flexibility:

Transactions

Refunds

Global Settlements

Charges

Mandates

Withdrawals

Disputes

Files

Partners

Pagination

When building API integrations, you may encounter scenarios where the server doesn't provide all results in a single response. Instead, it divides results into several pages. This strategy is called pagination, and integrating it into your application can be tedious and repetitive.

With this SDK, you can leverage SaloonPHP's powerful pagination plugin to reduce boilerplate code and iterate through every result across every page in one loop. When you set a limit, it will automatically fetch as many pages as necessary to get all results.

Key Benefits:

• Automatic: No manual page tracking or URL construction
• Memory Efficient: Processes one page at a time, not all at once
• Error Resilient: Handles API errors gracefully
• Flexible: Works with any limit size you specify

⚙️ Configuration

The configuration file (config/opp.php) allows you to customize various aspects:

🚨 Error Handling

The package provides detailed exception handling:

🧪 Testing

Run the test suite:

Test Coverage

The package includes comprehensive tests covering all API endpoints with 85.2% code coverage:

• ✅ 302 tests covering all major endpoints and DTOs
• ✅ 1250 assertions ensuring functionality
• ✅ Merchant operations - CRUD, contacts, addresses, bank accounts, settlements, UBOs, profiles
• ✅ Transaction lifecycle - create, retrieve, update, delete
• ✅ Payment flows - charges, mandates, withdrawals, disputes
• ✅ File operations - upload, retrieval, management
• ✅ Partner configuration - settings management
• ✅ Error handling - graceful sandbox environment handling

Coverage reports are generated in multiple formats:

• Terminal: Real-time coverage during test runs
• HTML: Detailed browsable report in coverage-report/
• XML: Machine-readable format for CI/CD integration

📖 Advanced Usage

Custom HTTP Client Configuration

Note: The package automatically registers the connector in Laravel's service container using the configuration from config/opp.php. No manual service provider binding is needed.

🚀 Releases

This package uses automated versioning and releases:

• Automatic: Patch version bump on every push to main branch
• Manual: Use commit messages to control version bumps:
  • [major] in commit message → Major version bump (e.g., 1.0.0 → 2.0.0)
  • [minor] in commit message → Minor version bump (e.g., 1.0.0 → 1.1.0)
  • Default → Patch version bump (e.g., 1.0.0 → 1.0.1)
• Skip Release: Add [skip release] to commit message to skip version bump

Manual Release Trigger

You can also manually trigger a release via GitHub Actions:

1. Go to Actions → Release workflow
2. Click "Run workflow"
3. Select the version bump type (patch/minor/major)

🤝 Contributing

Please see CONTRIBUTING.md for details on how to contribute.

📝 License

The MIT License (MIT). Please see License File for more information.

🙏 Credits

• Built with SaloonPHP
• DTOs powered by Spatie Laravel Data
• Testing with Pest PHP