README

👁 CI
👁 Latest Stable Version
👁 License

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