Payment Providers

Extend PteroCA with custom payment gateways.

Payment Provider Interface

<?php
namespace Plugins\MyPlugin\Provider;

use App\Core\Payment\PaymentProviderInterface;
use App\Core\Payment\DTO\PaymentSessionDTO;

class MyPaymentProvider implements PaymentProviderInterface
{
    public function __construct(
        private readonly MyPaymentAdapter $adapter,
        private readonly LoggerInterface $logger,
    ) {}

    public function getIdentifier(): string
    {
        return 'my-provider';
    }

    public function getDisplayName(): string
    {
        return 'My Payment Provider';
    }

    public function isConfigured(): bool
    {
        // Check if required settings are present
        $apiKey = $this->pluginSettings->get('my-plugin', 'api_key');
        return !empty($apiKey);
    }

    public function createSession(
        string $userId,
        float $amount,
        string $currency,
        array $metadata = []
    ): ?PaymentSessionDTO {
        try {
            $session = $this->adapter->createPaymentSession(
                amount: $amount,
                currency: $currency,
                metadata: $metadata
            );

            return new PaymentSessionDTO(
                id: $session['id'],
                status: $session['status'],
                amount: $amount,
                currency: $currency,
                checkoutUrl: $session['checkout_url'],
                metadata: $metadata
            );
        } catch (\Exception $e) {
            $this->logger->error('Payment session creation failed', [
                'provider' => $this->getIdentifier(),
                'error' => $e->getMessage()
            ]);

            return null;
        }
    }

    public function retrieveSession(string $sessionId): ?PaymentSessionDTO
    {
        try {
            $session = $this->adapter->getSession($sessionId);

            return new PaymentSessionDTO(
                id: $session['id'],
                status: $session['status'],
                amount: $session['amount'],
                currency: $session['currency'],
                checkoutUrl: $session['checkout_url'],
                metadata: $session['metadata']
            );
        } catch (\Exception $e) {
            $this->logger->error('Payment session retrieval failed', [
                'provider' => $this->getIdentifier(),
                'session_id' => $sessionId,
                'error' => $e->getMessage()
            ]);

            return null;
        }
    }

    public function getIcon(): string
    {
        return 'fab fa-cc-stripe';  // FontAwesome icon
    }

    public function getDescription(): string
    {
        return 'Accept payments via My Payment Provider';
    }

    public function getSupportedCurrencies(): array
    {
        return ['USD', 'EUR', 'GBP', 'PLN'];
    }

    public function getMetadata(): array
    {
        return [
            'website' => 'https://myprovider.com',
            'support_email' => '[email protected]',
        ];
    }

    public function getSuccessCallbackRoute(): string
    {
        return 'plugin_my_plugin_payment_success';
    }

    public function getCancelCallbackRoute(): string
    {
        return 'plugin_my_plugin_payment_cancel';
    }

    public function extractSessionIdFromCallback(Request $request): ?string
    {
        return $request->query->get('session_id');
    }

    public function buildSuccessUrl(string $baseUrl): string
    {
        return $baseUrl . '?status=success';
    }

    public function buildCancelUrl(string $baseUrl): string
    {
        return $baseUrl . '?status=cancelled';
    }
}

Required Interface Methods

Core Methods

• getIdentifier(): Unique provider identifier (e.g., "my-provider")

• getDisplayName(): Human-readable name shown to users

• getIcon(): FontAwesome icon class for UI display

• getDescription(): Brief description of the payment provider

• isConfigured(): Check if provider has required settings configured

• getSupportedCurrencies(): Array of ISO currency codes supported

• getMetadata(): Additional provider information (website, support contact)

Session Management

• createSession(): Create a new payment session and return checkout URL

• retrieveSession(): Retrieve existing session data by session ID

Callback Handling

• getSuccessCallbackRoute(): Route name for successful payment redirect

• getCancelCallbackRoute(): Route name for cancelled payment redirect

• extractSessionIdFromCallback(): Extract session ID from callback request

• buildSuccessUrl(): Build complete success redirect URL with parameters

• buildCancelUrl(): Build complete cancel redirect URL with parameters

Payment Adapter Pattern

Wrap external SDKs with an adapter:

<?php
namespace Plugins\MyPlugin\Adapter;

use MyPaymentSDK\Client;

class MyPaymentAdapter
{
    private Client $client;

    public function __construct(
        private readonly PluginSettingService $settings,
    ) {
        $apiKey = $this->settings->get('my-plugin', 'api_key');
        $this->client = new Client($apiKey);
    }

    public function createPaymentSession(
        float $amount,
        string $currency,
        array $metadata
    ): array {
        $response = $this->client->checkout->create([
            'amount' => $amount * 100, // Convert to cents
            'currency' => $currency,
            'metadata' => $metadata,
        ]);

        return [
            'id' => $response->id,
            'status' => $this->mapStatus($response->status),
            'checkout_url' => $response->url,
            'amount' => $amount,
            'currency' => $currency,
            'metadata' => $metadata,
        ];
    }

    public function getSession(string $sessionId): array
    {
        $response = $this->client->checkout->retrieve($sessionId);

        return [
            'id' => $response->id,
            'status' => $this->mapStatus($response->status),
            'checkout_url' => $response->url,
            'amount' => $response->amount / 100,
            'currency' => $response->currency,
            'metadata' => $response->metadata,
        ];
    }

    private function mapStatus(string $externalStatus): string
    {
        return match ($externalStatus) {
            'pending' => 'pending',
            'completed', 'paid' => 'completed',
            'failed', 'expired' => 'failed',
            default => 'pending',
        };
    }
}

Webhook Handling

#[Route('/webhook', name: 'webhook', methods: ['POST'])]
public function webhook(Request $request): Response
{
    $payload = $request->getContent();
    $signature = $request->headers->get('X-Signature');

    // Verify webhook signature
    if (!$this->verifySignature($payload, $signature)) {
        return new Response('Invalid signature', 400);
    }

    $data = json_decode($payload, true);

    // Handle webhook event
    match ($data['event']) {
        'payment.completed' => $this->handlePaymentCompleted($data),
        'payment.failed' => $this->handlePaymentFailed($data),
        default => null,
    };

    return new Response('OK', 200);
}

private function verifySignature(string $payload, string $signature): bool
{
    $secret = $this->pluginSettings->get('my-plugin', 'webhook_secret');
    $expectedSignature = hash_hmac('sha256', $payload, $secret);

    return hash_equals($expectedSignature, $signature);
}

private function handlePaymentCompleted(array $data): void
{
    $sessionId = $data['session_id'];

    // Update payment in PteroCA
    $this->paymentService->markAsPaid($sessionId);

    $this->logger->info('Payment completed', [
        'session_id' => $sessionId,
        'amount' => $data['amount']
    ]);
}

private function handlePaymentFailed(array $data): void
{
    $sessionId = $data['session_id'];

    $this->logger->warning('Payment failed', [
        'session_id' => $sessionId,
        'reason' => $data['failure_reason']
    ]);
}

Service Registration

services:
    Plugins\MyPlugin\Provider\MyPaymentProvider:
        tags: ['payment.provider']
        public: true

Important: Payment providers must be:

• Tagged with payment.provider

• Marked as public: true

External SDK Integration

Add SDK to plugin's composer.json:

{
    "name": "my-plugin/my-plugin",
    "require": {
        "payment-vendor/sdk": "^2.0"
    }
}

Install dependencies:

cd plugins/my-plugin
composer install

Configuration Schema

Define settings in plugin.json:

{
    "config_schema": {
        "api_key": {
            "type": "password",
            "required": true,
            "label": "API Key",
            "help": "Your API key from My Payment Provider",
            "hierarchy": "general"
        },
        "webhook_secret": {
            "type": "password",
            "required": true,
            "label": "Webhook Secret",
            "help": "Used to verify webhook signatures",
            "hierarchy": "general"
        },
        "test_mode": {
            "type": "boolean",
            "required": false,
            "default": false,
            "label": "Test Mode",
            "help": "Use test API endpoint",
            "hierarchy": "advanced"
        }
    }
}

Testing Payment Provider

# Enable plugin
php bin/console pteroca:plugin:enable my-plugin

# Test payment provider
php bin/console pteroca:payment:test my-provider

Error Handling

public function createSession(...): ?PaymentSessionDTO
{
    try {
        $session = $this->adapter->createPaymentSession(...);
        return new PaymentSessionDTO(...);
    } catch (ApiException $e) {
        $this->logger->error('API error', [
            'code' => $e->getCode(),
            'message' => $e->getMessage()
        ]);
        return null;
    } catch (NetworkException $e) {
        $this->logger->error('Network error', [
            'message' => $e->getMessage()
        ]);
        return null;
    } catch (\Exception $e) {
        $this->logger->error('Unexpected error', [
            'message' => $e->getMessage()
        ]);
        return null;
    }
}

Security Best Practices

1. Validate webhooks: Always verify signatures

2. Use HTTPS: Never send API keys over HTTP

3. Store secrets securely: Use password field type in config

4. Log all transactions: Track payments for auditing

5. Handle errors gracefully: Don't expose sensitive details

6. Idempotency: Handle duplicate webhook calls

7. Rate limiting: Respect API rate limits

Related Guides

• Dependencies - Register payment provider service

• Plugin Manifest - Declare composer dependencies

• Controllers & Routes - Webhook endpoints

• Best Practices - Security guidelines