Monobank Acquiring Bundle for Symfony

Symfony bundle providing a typed HTTP client for Monobank Acquiring API.

Features

• Create payment invoices
• Check invoice status
• Fetch currency exchange rates
• Typed DTOs instead of raw arrays
• Auto-configured via Symfony DI

Requirements

• PHP 8.1+
• Symfony 6.4 / 7.x / 8.x

Installation

Step 1: Install the package

composer require 12goyuriyr/symfony-mono-acquiring-bundle

Symfony Flex will automatically register the bundle in config/bundles.php. If it didn't, add it manually:

return [
    // ...
    MonobankAcquiring\MonobankAcquiringBundle::class => ['all' => true],
];

Step 2: Configure

Add your Monobank merchant token to .env:

MONO_API_TOKEN=your_token_here

Create the bundle configuration file:

# config/packages/monobank_acquiring.yaml
monobank_acquiring:
    api_token: '%env(MONO_API_TOKEN)%'
    # api_url: 'https://api.monobank.ua'  # optional, this is the default

That's it. MonoAcquiringClientInterface is now available for dependency injection.

Usage

Inject MonoAcquiringClientInterface into your service:

use MonobankAcquiring\Client\MonoAcquiringClientInterface;

class PaymentService
{
    public function __construct(
        private readonly MonoAcquiringClientInterface $monoClient,
    ) {}

    public function createPayment(): string
    {
        $invoice = $this->monoClient->createInvoice([
            'amount' => 10000,       // amount in kopiykas (100.00 UAH)
            'ccy' => 980,            // ISO 4217 currency code (UAH)
            'merchantPaymInfo' => [
                'reference' => 'Order #123',
                'destination' => 'Payment for order #123',
            ],
            'redirectUrl' => 'https://example.com/payment/callback',
            'webHookUrl' => 'https://example.com/payment/webhook',
            'validity' => 3600,
        ]);

        // Redirect user to $invoice->getPageUrl()
        return $invoice->getInvoiceId();
    }

    public function checkStatus(string $invoiceId): bool
    {
        $status = $this->monoClient->getInvoiceStatus($invoiceId);

        return $status->isSuccess();
    }
}

Available methods

createInvoice(array $payload): InvoiceResponse

Creates a payment invoice. Returns InvoiceResponse with getInvoiceId() and getPageUrl().

See Monobank API docs for payload options.

getInvoiceStatus(string $invoiceId): InvoiceStatus

Returns InvoiceStatus with:

• getStatus() — raw status string
• isCreated(), isProcessing(), isSuccess(), isFailure(), isExpired(), isReversed() — status checks
• getAmount(), getFinalAmount(), getCcy() — payment amounts
• getFee() — gateway fee
• getPaymentInfo() — raw payment info array

getRates(): Rate[]

Returns an array of Rate objects with:

• getCurrencyCodeA(), getCurrencyCodeB() — ISO 4217 codes
• getDate() — Unix timestamp
• getRateSell(), getRateBuy(), getRateCross() — exchange rates

Error handling

All API errors throw MonoApiException:

use MonobankAcquiring\Exception\MonoApiException;

try {
    $invoice = $monoClient->createInvoice($payload);
} catch (MonoApiException $e) {
    $e->getMessage();        // error description
    $e->getHttpStatusCode(); // HTTP status code
    $e->getResponseBody();   // raw response array
}

License

MIT