### getKey usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/pub-key-provider.md Example of retrieving the public key from the container. Returns the decoded PEM string. ```php $pubKey = app(PubKeyProvider::class)->getKey(); // decoded PEM string ``` -------------------------------- ### flush usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/pub-key-provider.md Example of flushing the cached key after a ValidationException, then retrying once. ```php $provider = app(PubKeyProvider::class); try { $key = $provider->getKey(); } catch (ValidationException $e) { $provider->flush(); // drop bad cached key and retry once } ``` -------------------------------- ### SyncPaymentRequestDTO Usage Example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-payment-requests.md Example of initiating a sync payment request using the SyncPaymentRequestDTO. ```php $status = Monobank::syncPayment(new SyncPaymentRequestDTO( amount: 50.00, cardData: ['pan' => '4242424242424242', 'exp' => '1230', 'cvv' => '123'], )); // $status is an InvoiceStatusDTO — check ->status === InvoiceStatus::SUCCESS ``` -------------------------------- ### getQrList method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature and usage example for getQrList. GETs qr/list and maps each JSON item through QrDetailsDTO::fromArray. Returns an array of QrDetailsDTO for physical QR registers. ```php public function getQrList(): array ``` ```php foreach ($service->getQrList() as $qr) { echo $qr->qrId . ' - ' . $qr->pageUrl; } ``` -------------------------------- ### Install package with Composer Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Install the package via Composer. Requires PHP 8.3+ and Laravel 11.x-13.x. ```bash composer require aratkruglik/monobank-laravel ``` -------------------------------- ### getToken usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Retrieves the token from the service instance. ```php $token = $service->getToken(); // e.g. "your_token_here" ``` -------------------------------- ### getQrDetails method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature and usage example for getQrDetails. GETs qr/details/{rawurlencode($qrId)} with the QR id URL-encoded into the path. Returns QrDetailsDTO with shortQrId, paymentType, pageUrl, and assigned amount/ccy when set. ```php public function getQrDetails(string $qrId): QrDetailsDTO ``` ```php $qr = $service->getQrDetails('qr_id_here'); echo $qr->shortQrId; ``` -------------------------------- ### getDetails method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature and usage example for getDetails. GETs details and returns raw merchant details JSON, e.g. $details['merchantName']. ```php public function getDetails(): array ``` ```php $details = $service->getDetails(); echo $details['merchantName']; ``` -------------------------------- ### Usage example for WalletItem Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-qr-wallet-employee.md Shows how to iterate over the wallet cards and print the masked PAN and card token. ```php $cards = Monobank::getWalletCards('wallet_id_here'); foreach ($cards as $card) { echo $card->maskedPan . ' -> ' . $card->cardToken; } ``` -------------------------------- ### getWalletCards method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature and usage example for getWalletCards. GETs wallet with query ['walletId' => $walletId] and maps $response->json('wallet') ?? [] through WalletItem::fromArray. Returns an array of WalletItem with saved card tokens and masked PANs. ```php public function getWalletCards(string $walletId): array ``` ```php $cards = $service->getWalletCards('wallet_id_here'); ``` -------------------------------- ### Usage example for EmployeeItem Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-qr-wallet-employee.md Shows how to iterate over the employee list and print each employee's name. ```php foreach (Monobank::getEmployeeList() as $employee) { echo $employee->name; } ``` -------------------------------- ### PaymentResponseDTO Usage Examples Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-payment-response.md Examples showing how to use the PaymentResponseDTO returned by direct and wallet payment methods, including handling 3-D Secure redirects and failure diagnostics. ```APIDOC ## PaymentResponseDTO Usage Examples ### Description Demonstrates how to consume the PaymentResponseDTO returned by `Monobank::paymentDirect` and `Monobank::walletPayment`. ### Direct Payment with 3-D Secure Hand-off ```php $response = Monobank::paymentDirect(new PaymentDirectRequestDTO( amount: 100.00, cardData: ['pan' => '4242424242424242', 'exp' => '1230', 'cvv' => '123'], )); if ($response->tdsUrl !== null) { return redirect($response->tdsUrl); // complete 3-D Secure first } if ($response->status === InvoiceStatus::SUCCESS) { // paid immediately } ``` ### Wallet Payment with Failure Diagnostics ```php $response = Monobank::walletPayment(new WalletPaymentRequestDTO( cardToken: 'card_token_here', amount: 20.00, initiationKind: 'merchant', )); if ($response->status === InvoiceStatus::FAILURE) { Log::warning('wallet payment declined', [ 'invoiceId' => $response->invoiceId, 'reason' => $response->failureReason, ]); } ``` ``` -------------------------------- ### PubKeyProvider constructor Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/pub-key-provider.md Constructor that accepts a ClientInterface instance used for the GET pubkey request. ```php public function __construct(protected ClientInterface $client) ``` -------------------------------- ### Client get method Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/client.md Performs a GET request with query parameters, delegating to the shared request() method. The URI is a relative path appended to baseUrl. ```php public function get(string $uri, array $query = []): Response ``` -------------------------------- ### Resolve monobank services from container Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-service-provider.md Example of resolving the registered services from the container. ```php $monobank = app('monobank'); // AratKruglik\Monobank\Monobank $client = app(ClientInterface::class); // AratKruglik\Monobank\Client $pubKey = app(PubKeyProvider::class); // AratKruglik\Monobank\Services\PubKeyProvider ``` -------------------------------- ### createSubscription usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Creates a subscription and redirects the customer to the hosted page URL. ```php $subscription = $service->createSubscription(new SubscriptionRequestDTO( amount: 100.00, interval: '1m', webHookStatusUrl: 'https://site.com/sub/status', redirectUrl: 'https://site.com/thank-you' )); redirect($subscription->pageUrl); ``` -------------------------------- ### createInvoice with QR stand usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Creates an invoice with a QR stand ID so the scanned QR opens with the specified amount. ```php $invoice = $service->createInvoice(new InvoiceRequestDTO(amount: 150.00, qrId: 'qr_id_here')); ``` -------------------------------- ### InvoiceResponseDTO Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-invoice-response.md Documentation for the InvoiceResponseDTO class, including its constructor, static factory, and usage examples. ```APIDOC ## InvoiceResponseDTO ### Description Value object representing the response from `POST invoice/create`. It contains the invoice ID and the hosted payment page URL. ### Constructor ```php public function __construct( public string $invoiceId, public string $pageUrl ) {} ``` ### Parameters - **invoiceId** (string) - Required - Monobank invoice id. Store it and use it for every follow-up call: `getInvoiceStatus`, `cancelInvoice`, `removeInvoice`, `finalizeInvoice`, `getFiscalChecks`, `getReceipt`. - **pageUrl** (string) - Required - Hosted payment page URL — redirect the customer here to complete payment. ### Static Factory ```php public static function fromArray(array $data): self ``` Factory mapping a raw API response to the DTO. Mapping: `invoiceId: (string) $data['invoiceId']`, `pageUrl: (string) $data['pageUrl']`. Both fields are required. ### Usage Basic call (facade) followed by a redirect to the hosted page: ```php $invoice = Monobank::createInvoice(new InvoiceRequestDTO(amount: 100.00)); return redirect($invoice->pageUrl); ``` Instance-style usage with a hold payment and cart, then reusing the id: ```php use AratKruglik\Monobank\Monobank; $service = app('monobank'); $request = new InvoiceRequestDTO(amount: 300.00, paymentType: 'hold'); $invoice = $service->createInvoice($request); // later: capture the hold $status = $service->finalizeInvoice($invoice->invoiceId); // string status ``` Manual construction from a raw response body (e.g. in tests or adapters that bypass the service): ```php $dto = InvoiceResponseDTO::fromArray(['invoiceId' => 'inv_123', 'pageUrl' => 'https://pay.monobank.ua/p/....']); echo $dto->invoiceId; // inv_123 ``` ``` -------------------------------- ### createInvoice usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Creates an invoice with amount, destination, reference, and validity, then redirects to the hosted page URL. ```php $invoice = $service->createInvoice(new InvoiceRequestDTO( amount: 100.00, destination: 'Payment for Order #12345', reference: 'ORDER-12345', validity: 3600 )); redirect($invoice->pageUrl); ``` -------------------------------- ### Usage examples for QrDetailsDTO Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-qr-wallet-employee.md Shows how to iterate over the QR list and fetch details for a specific QR ID, printing the qrId, pageUrl, amount (or 'no amount set'), and shortQrId. ```php foreach (Monobank::getQrList() as $qr) { echo $qr->qrId . ' - ' . $qr->pageUrl . ' - ' . ($qr->amount ?? 'no amount set'); } $qr = Monobank::getQrDetails('qr_id_here'); echo $qr->shortQrId; ``` -------------------------------- ### Monobank::getQrDetails Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-facade.md Static facade method to get QR details. Mirrors the instance method on the Monobank service. ```APIDOC ## [STATIC] Monobank::getQrDetails ### Description Retrieves details of a QR code by its ID. This is a static facade method that forwards to the underlying service instance. ### Method STATIC ### Endpoint Monobank::getQrDetails(string $qrId) ### Parameters - **$qrId** (string) - Required - The QR code ID. ### Return \AratKruglik\Monobank\DTO\QrDetailsDTO ``` -------------------------------- ### getEmployeeList(): array - Fetch employee list Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature for getEmployeeList. It GETs employee/list and maps the response list through EmployeeItem::fromArray. The usage example iterates over the returned EmployeeItem array and prints each employee's name. ```php public function getEmployeeList(): array ``` ```php foreach ($service->getEmployeeList() as $employee) { echo $employee->name; } ``` -------------------------------- ### getSubscriptionDetails usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Retrieves raw subscription details for a given subscription ID. ```php $details = $service->getSubscriptionDetails('sub_id_here'); ``` -------------------------------- ### SyncPaymentRequestDTO Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-payment-requests.md Documentation for the SyncPaymentRequestDTO class, including its constructor, parameters, toArray method, and usage examples. ```APIDOC ## SyncPaymentRequestDTO ### Description DTO for the `Monobank::syncPayment` operation (`POST invoice/sync-payment`). Enforces exactly one payment source among `cardData`, `applePay`, or `googlePay`. ### Constructor ```php public function __construct( int|float $amount, public int|CurrencyCode $ccy = 980, #\SensitiveParameter public ?array $cardData = null, #\SensitiveParameter public ?array $applePay = null, #\SensitiveParameter public ?array $googlePay = null, public ?string $destination = null, public ?string $reference = null ) ``` ### Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | amount | int\|float | yes | — | Amount; normalized to cents. | | ccy | int\|CurrencyCode | no | 980 | Currency code. | | cardData | ?array | no | null | `{pan, exp, cvv}` — card source. | | applePay | ?array | no | null | Apple Pay token object — wallet source. | | googlePay | ?array | no | null | Google Pay token object — wallet source. | | destination | ?string | no | null | `merchantPaymInfo.destination`. | | reference | ?string | no | null | `merchantPaymInfo.reference`. | **Throws:** `InvalidArgumentException` when zero or more than one of `cardData` / `applePay` / `googlePay` is provided. ### toArray(): array ```php public function toArray(): array ``` Wire body: `amount`, `ccy`, `cardData`/`applePay`/`googlePay` (only the provided one survives), `merchantPaymInfo`; top-level null/empty filtered. ### Usage Example ```php $status = Monobank::syncPayment(new SyncPaymentRequestDTO( amount: 50.00, cardData: ['pan' => '4242424242424242', 'exp' => '1230', 'cvv' => '123'], )); // $status is an InvoiceStatusDTO — check ->status === InvoiceStatus::SUCCESS ``` ### Error Handling Example ```php use InvalidArgumentException; try { new SyncPaymentRequestDTO(amount: 50.00); // no source new SyncPaymentRequestDTO(amount: 50.00, // two sources cardData: ['pan' => '1', 'exp' => '1', 'cvv' => '1'], applePay: ['token' => 'x']); } catch (InvalidArgumentException $e) { // "Exactly one of cardData, applePay, or googlePay must be provided." } ``` ``` -------------------------------- ### Monobank::getQrList Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-facade.md Static facade method to get the QR list. Mirrors the instance method on the Monobank service. ```APIDOC ## [STATIC] Monobank::getQrList ### Description Retrieves the list of QR codes. This is a static facade method that forwards to the underlying service instance. ### Method STATIC ### Endpoint Monobank::getQrList() ### Return array ``` -------------------------------- ### PaymentDirectRequestDTO usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-payment-requests.md Example of using Monobank::paymentDirect with a PaymentDirectRequestDTO. Shows how to handle the 3-D Secure redirect via the tdsUrl property when it is not null. ```php $response = Monobank::paymentDirect(new PaymentDirectRequestDTO( amount: 100.00, cardData: ['pan' => '4242424242424242', 'exp' => '1230', 'cvv' => '123'], )); if ($response->tdsUrl !== null) { return redirect($response->tdsUrl); // 3-D Secure required before settlement } ``` -------------------------------- ### deleteSubscription usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Deletes a subscription and checks the boolean result. ```php $ok = $service->deleteSubscription('sub_id_here'); ``` -------------------------------- ### Monobank::walletPayment usage example Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-payment-requests.md Example usage of Monobank::walletPayment with a WalletPaymentRequestDTO. Charges a saved wallet card token. If the response contains a tdsUrl (3-D Secure), redirect the user to it. ```php $response = Monobank::walletPayment(new WalletPaymentRequestDTO( cardToken: 'card_token_here', amount: 20.00, initiationKind: 'merchant', )); if ($response->tdsUrl !== null) { redirect($response->tdsUrl); } ``` -------------------------------- ### Iterate split receivers Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-statement-fiscal-submerchant.md Example of retrieving and iterating over split receivers using Monobank::getSplitReceivers. Outputs code and IBAN. ```php $receivers = Monobank::getSplitReceivers(); foreach ($receivers as $receiver) { echo $receiver->code . ' - ' . $receiver->iban; } ``` -------------------------------- ### Client::get Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/client.md Performs a GET request to the specified URI with optional query parameters. Delegates to the shared request method. ```APIDOC ## Client::get ### Description Performs a GET request to the specified URI with optional query parameters. Delegates to the shared request method. ### Method GET ### Signature ```php public function get(string $uri, array $query = []): Response ``` ### Parameters - **uri** (string) - Required - Relative path appended to `baseUrl` (e.g. `'details'`). - **query** (array) - Optional - Query string key/value pairs. ### Returns Returns `Illuminate\Http\Client\Response` (Laravel's HTTP client response object — `.json()`, `.successful()`, `.status()`, `.header()`). ``` -------------------------------- ### walletPayment method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature and usage example for walletPayment. POSTs wallet/payment with the request array and maps to PaymentResponseDTO. Charges a saved wallet card token; check tdsUrl for 3-D Secure. ```php public function walletPayment(WalletPaymentRequestDTO $request): PaymentResponseDTO ``` ```php $resp = $service->walletPayment(new WalletPaymentRequestDTO( cardToken: 'card_token_here', amount: 20.00, initiationKind: 'merchant', )); ``` -------------------------------- ### getQrList(): array Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md GETs qr/list to retrieve a list of physical QR registers as QrDetailsDTO objects. ```APIDOC ## GET qr/list ### Description Retrieves a list of physical QR registers. ### Method GET ### Endpoint qr/list ### Parameters No parameters. ### Request Example ```php foreach ($service->getQrList() as $qr) { echo $qr->qrId . ' - ' . $qr->pageUrl; } ``` ### Response #### Success Response - **array** - Array of `QrDetailsDTO` (your physical QR registers). #### Response Example ```php // No explicit example provided ``` ``` -------------------------------- ### getQrDetails(string $qrId): QrDetailsDTO Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md GETs qr/details/{qrId} to retrieve details of a specific QR register. ```APIDOC ## GET qr/details/{qrId} ### Description Retrieves details of a specific QR register. ### Method GET ### Endpoint qr/details/{qrId} ### Parameters #### Path Parameters - **qrId** (string) - Required - QR register id. ### Request Example ```php $qr = $service->getQrDetails('qr_id_here'); ``` ### Response #### Success Response - **QrDetailsDTO** - Register details incl. `shortQrId`, `paymentType`, `pageUrl`, assigned `amount`/`ccy` when set. #### Response Example ```php echo $qr->shortQrId; ``` ``` -------------------------------- ### Create Invoice with Cart Items Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-invoice-request.md Example of creating a cart with two items and generating an invoice using Monobank::createInvoice(). The sum is provided in major units and normalized to cents. ```php $cart = [ new CartItemDTO(name: 'T-Shirt', qty: 2, sum: 50.00, code: 'tshirt-001'), new CartItemDTO(name: 'Socks', qty: 1, sum: 2.00, code: 'socks-001'), ]; $invoice = Monobank::createInvoice(new InvoiceRequestDTO(amount: 102.00, cartItems: $cart)); ``` -------------------------------- ### Iterate statement items Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-statement-fiscal-submerchant.md Example of retrieving and iterating over statement items from Monobank::getStatement. Outputs invoice ID, amount in currency units, and currency code. ```php $statement = Monobank::getStatement(from: strtotime('-1 day'), to: time()); foreach ($statement as $item) { echo $item->invoiceId . ' - ' . $item->amount / 100 . ' ' . $item->ccy; } ``` -------------------------------- ### syncPayment method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature and usage example for syncPayment. POSTs invoice/sync-payment and maps to InvoiceStatusDTO. Requires exactly one of cardData, applePay, or googlePay in the DTO. ```php public function syncPayment(SyncPaymentRequestDTO $request): InvoiceStatusDTO ``` ```php $status = $service->syncPayment(new SyncPaymentRequestDTO( amount: 50.00, cardData: ['pan' => '4242424242424242', 'exp' => '1230', 'cvv' => '123'], )); if ($status->status === InvoiceStatus::SUCCESS) { /* paid */ } ``` -------------------------------- ### Monobank::getReceipt Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-facade.md Static facade method to get a receipt. Mirrors the instance method on the Monobank service. ```APIDOC ## [STATIC] Monobank::getReceipt ### Description Retrieves a receipt for an invoice. This is a static facade method that forwards to the underlying service instance. ### Method STATIC ### Endpoint Monobank::getReceipt(string $invoiceId, ?string $email = null) ### Parameters - **$invoiceId** (string) - Required - The invoice ID. - **$email** (?string) - Optional - Email to send the receipt to. ### Return string|null ``` -------------------------------- ### SyncPaymentRequestDTO Constructor Validation Error Handling Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-payment-requests.md Example demonstrating how the constructor throws an InvalidArgumentException when payment source requirements are not met. ```php use InvalidArgumentException; try { new SyncPaymentRequestDTO(amount: 50.00); // no source new SyncPaymentRequestDTO(amount: 50.00, // two sources cardData: ['pan' => '1', 'exp' => '1', 'cvv' => '1'], applePay: ['token' => 'x']); } catch (InvalidArgumentException $e) { // "Exactly one of cardData, applePay, or googlePay must be provided." } ``` -------------------------------- ### Client::__construct Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/client.md Initializes a new Client instance with the provided configuration array. The token from the config is used as the X-Token header for authentication. ```APIDOC ## Client::__construct ### Description Initializes a new Client instance with the provided configuration array. The token from the config is used as the X-Token header for authentication. ### Method Constructor ### Signature ```php public function __construct(protected array $config) ``` ### Parameters - **config** (array) - Required - The `monobank` config array. Only `config['token']` is used (sent as `X-Token` header when non-empty). ``` -------------------------------- ### Iterate fiscal checks Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-statement-fiscal-submerchant.md Example of retrieving and iterating over fiscal checks for an invoice using Monobank::getFiscalChecks. Outputs status and type. ```php foreach (Monobank::getFiscalChecks('inv_123') as $check) { echo $check->status . ' - ' . $check->type; } ``` -------------------------------- ### deleteWalletCard method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature and usage example for deleteWalletCard. DELETEs wallet/card with query parameter cardToken. Returns true on success. ```php public function deleteWalletCard(string $cardToken): bool ``` ```php $service->deleteWalletCard('card_token_here'); ``` -------------------------------- ### Monobank::getWalletCards Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-facade.md Static facade method to get wallet cards. Mirrors the instance method on the Monobank service. ```APIDOC ## [STATIC] Monobank::getWalletCards ### Description Retrieves the list of wallet cards for a given wallet. This is a static facade method that forwards to the underlying service instance. ### Method STATIC ### Endpoint Monobank::getWalletCards(string $walletId) ### Parameters - **$walletId** (string) - Required - The wallet ID. ### Return array<\AratKruglik\Monobank\DTO\WalletItem> ``` -------------------------------- ### Monobank::getFiscalChecks Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-facade.md Static facade method to get fiscal checks. Mirrors the instance method on the Monobank service. ```APIDOC ## [STATIC] Monobank::getFiscalChecks ### Description Retrieves fiscal checks for an invoice. This is a static facade method that forwards to the underlying service instance. ### Method STATIC ### Endpoint Monobank::getFiscalChecks(string $invoiceId) ### Parameters - **$invoiceId** (string) - Required - The invoice ID. ### Return array<\AratKruglik\Monobank\DTO\FiscalCheck> ``` -------------------------------- ### getSplitReceivers(): array - Fetch split receivers Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature for getSplitReceivers. It GETs submerchant/list and maps the response list through Submerchant::fromArray. The usage example prints the code and IBAN of each split-payment receiver. ```php public function getSplitReceivers(): array ``` ```php foreach ($service->getSplitReceivers() as $receiver) { echo $receiver->code . ' - ' . $receiver->iban; } ``` -------------------------------- ### Wallet payment with failure diagnostics Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-payment-response.md Wallet payment example with failure diagnostics. After calling Monobank::walletPayment, check if the status is InvoiceStatus::FAILURE and log a warning with the invoiceId and failureReason for debugging. ```php $response = Monobank::walletPayment(new WalletPaymentRequestDTO( cardToken: 'card_token_here', amount: 20.00, initiationKind: 'merchant', )); if ($response->status === InvoiceStatus::FAILURE) { Log::warning('wallet payment declined', [ 'invoiceId' => $response->invoiceId, 'reason' => $response->failureReason, ]); } ``` -------------------------------- ### resetQrAmount method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature and usage example for resetQrAmount. POSTs qr/reset-amount with ['qrId' => $qrId] to remove the assigned amount from a QR stand. Returns true on success. ```php public function resetQrAmount(string $qrId): bool ``` ```php $service->resetQrAmount('qr_id_here'); ``` -------------------------------- ### Handle Monobank webhook event Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-webhook-controller.md Example listener that handles the WebhookReceived event. Access the payload via $event->payload and check the status field. ```php use AratKruglik\Monobank\Events\WebhookReceived; class HandleMonobankPayment { public function handle(WebhookReceived $event): void { $payload = $event->payload; // invoiceId, status, amount, ... if ($payload['status'] === 'success') { /* mark order as paid */ } } } ``` -------------------------------- ### Get fiscal checks and receipt with Monobank::getFiscalChecks and getReceipt Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Retrieves fiscal check statuses for an invoice using getFiscalChecks, then downloads a receipt file using getReceipt. The invoice ID is passed as a string argument. Iterates over the checks and prints the status and type for each. ```php $checks = Monobank::getFiscalChecks('invoice_id_here'); foreach ($checks as $check) { echo $check->status . ' - ' . $check->type; } $receiptFile = Monobank::getReceipt('invoice_id_here'); ``` -------------------------------- ### HandleMonobankPayment listener implementation Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/webhook-received-event.md Example listener implementation for the WebhookReceived event. It accesses the payload's invoiceId and status fields, and uses a match expression to handle different invoice statuses. The status is a raw string, so it is compared against InvoiceStatus enum values. ```php namespace App\Listeners; use AratKruglik\Monobank\Events\WebhookReceived; use AratKruglik\Monobank\Enums\InvoiceStatus; class HandleMonobankPayment { public function handle(WebhookReceived $event): void { $payload = $event->payload; $invoiceId = $payload['invoiceId']; $status = $payload['status']; match ($status) { InvoiceStatus::SUCCESS->value => fn() { /* mark order paid */ }, InvoiceStatus::FAILURE->value => fn() { /* mark order failed */ }, InvoiceStatus::HOLD->value => fn() { /* require finalization */ }, default => fn() { /* CREATED/PROCESSING/EXPIRED/REVERSED */ }, } } } ``` -------------------------------- ### Create subscription with SubscriptionRequestDTO Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-subscriptions.md Example usage of SubscriptionRequestDTO with Monobank::createSubscription. Creates a subscription with amount 100.00 UAH, interval '1m', and redirects to the returned pageUrl. ```php $subscription = Monobank::createSubscription(new SubscriptionRequestDTO( amount: 100.00, // 100.00 UAH per period interval: '1m', // every 1 month webHookStatusUrl: 'https://site.com/sub/status', redirectUrl: 'https://site.com/thank-you', )); return redirect($subscription->pageUrl); ``` -------------------------------- ### Basic status check with InvoiceStatusDTO Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-invoice-status.md Basic usage example showing how to check the invoice status returned by Monobank::getInvoiceStatus. It compares the status against the InvoiceStatus enum and handles success and failure cases, logging error details on failure. ```php use AratKruglik\Monobank\Enums\InvoiceStatus; $status = Monobank::getInvoiceStatus('inv_123'); if ($status->status === InvoiceStatus::SUCCESS) { // order paid — $status->finalAmount ?? $status->amount } elseif ($status->status === InvoiceStatus::FAILURE) { Log::info('payment failed', ['code' => $status->errorCode, 'text' => $status->errorText]); } ``` -------------------------------- ### getReceipt(string $invoiceId, ?string $email): ?string - Fetch receipt Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature for getReceipt. It GETs invoice/receipt with invoiceId and optional email (nulls filtered out). The usage example retrieves the receipt file reference for a given invoice. ```php public function getReceipt(string $invoiceId, ?string $email = null): ?string ``` ```php $file = $service->getReceipt('inv_123'); ``` -------------------------------- ### boot() source behavior Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-service-provider.md Source behavior of the boot method. It publishes the config file when running in console and defines the monobankWebhook route macro. ```php if ($this->app->runningInConsole()) { $this->publishes([ __DIR__.'/../config/monobank.php' => config_path('monobank.php'), ], 'monobank-config'); } Route::macro('monobankWebhook', function (string $url) { $middleware = config('monobank.webhook.middleware') ?? []; return Route::post($url, MonobankWebhookController::class) ->middleware($middleware) ->name('monobank.webhook'); }); ``` -------------------------------- ### getFiscalChecks(string $invoiceId): array - Fetch fiscal checks Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature for getFiscalChecks. It GETs invoice/fiscal-checks with the invoiceId query parameter and maps the response checks through FiscalCheck::fromArray. The usage example prints the status and type of each fiscal check. ```php public function getFiscalChecks(string $invoiceId): array ``` ```php foreach ($service->getFiscalChecks('inv_123') as $check) { echo $check->status . ' - ' . $check->type; } ``` -------------------------------- ### getStatement(int $from, ?int $to, ?string $code): array - Fetch statement Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature for getStatement. It GETs statement with parameters from, to, and code (nulls filtered out). The usage example fetches a statement for the last day and prints invoiceId and amount for each item. ```php public function getStatement(int $from, ?int $to = null, ?string $code = null): array ``` ```php $statement = $service->getStatement(from: strtotime('-1 day'), to: time()); foreach ($statement as $item) { echo $item->invoiceId . ' - ' . $item->amount; } ``` -------------------------------- ### Get employee list with Monobank::getEmployeeList Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Retrieves the list of employees configured for the merchant account, used for tips distribution. Iterates over the returned collection and prints each employee's name. ```php $employees = Monobank::getEmployeeList(); foreach ($employees as $employee) { echo $employee->name; } ``` -------------------------------- ### Client constructor Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/client.md Constructor that accepts the monobank config array. Only config['token'] is used and sent as X-Token header when non-empty. ```php public function __construct(protected array $config) ``` -------------------------------- ### getInvoiceStatus method signature and usage Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Method signature for getInvoiceStatus, which GETs invoice/status with the invoiceId query parameter and maps the response through InvoiceStatusDTO::fromArray. The usage example checks the returned status against the InvoiceStatus::SUCCESS enum to mark an order as paid. ```php public function getInvoiceStatus(string $invoiceId): InvoiceStatusDTO ``` ```php $status = $service->getInvoiceStatus('inv_123'); if ($status->status === InvoiceStatus::SUCCESS) { // mark order as paid } ``` -------------------------------- ### Get merchant details Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Get information about your merchant account. The response includes the merchant name. ```php $details = Monobank::getDetails(); echo $details['merchantName']; ``` -------------------------------- ### Publish monobank-config Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Publish the configuration file to customize settings in config/monobank.php. ```bash php artisan vendor:publish --tag="monobank-config" ``` -------------------------------- ### register() source behavior Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-service-provider.md Source behavior of the register method. It merges the package config and registers container singletons for the client, the acquiring service, and the public key provider. ```php $this->mergeConfigFrom(__DIR__.'/../config/monobank.php', 'monobank'); $this->app->singleton(ClientInterface::class, function ($app) { return new Client(config('monobank')); }); $this->app->singleton('monobank', function ($app) { return new Monobank( config('monobank'), $app->make(ClientInterface::class) ); }); $this->app->singleton(PubKeyProvider::class, function ($app) { return new PubKeyProvider($app->make(ClientInterface::class)); }); ``` -------------------------------- ### GET /wallet-cards Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Lists cards saved for a wallet/customer. ```APIDOC ## [GET] /wallet-cards ### Description Lists cards saved for a wallet/customer. ### Method GET ### Endpoint /wallet-cards ### Parameters #### Path Parameters - **walletId** (string) - Required - The wallet ID. ### Request Example GET /wallet-cards/wallet_id_here ### Response #### Success Response (200) - **cards** (array) - List of saved cards. #### Response Example { "cards": [] } ``` -------------------------------- ### GET getSubscriptionDetails Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Retrieves subscription details by subscription ID. ```APIDOC ## GET getSubscriptionDetails ### Description Retrieves subscription details by GETting `subscription/status` with the subscription ID as a query parameter. Returns the raw response JSON without DTO mapping. ### Method GET ### Endpoint `subscription/status` ### Parameters #### Query Parameters - **subscriptionId** (string) - Required - The subscription ID returned by `createSubscription`. ### Request Example ```php $details = $service->getSubscriptionDetails('sub_id_here'); ``` ### Response #### Success Response (200) - **raw JSON** (object) - The raw response JSON. #### Response Example ```php $details ``` ``` -------------------------------- ### boot() method signature Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-service-provider.md Signature of the boot method. It is called by Laravel after all service providers are registered. ```php public function boot(): void ``` -------------------------------- ### GET getToken Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md Returns the configured Monobank Acquiring token. ```APIDOC ## GET getToken ### Description Returns the configured Monobank Acquiring token (from `MONOBANK_TOKEN`), or `null` if unset. ### Method GET ### Endpoint `getToken()` ### Parameters None. ### Request Example ```php $token = $service->getToken(); ``` ### Response #### Success Response (200) - **token** (string|null) - The configured token or null. #### Response Example ```php "your_token_here" ``` ``` -------------------------------- ### GET /api/subscription/{subscriptionId} Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Retrieves details of a specific subscription by its ID. ```APIDOC ## [GET] /api/subscription/{subscriptionId} ### Description Retrieves details of a specific subscription by its ID. ### Method GET ### Endpoint /api/subscription/{subscriptionId} ### Parameters #### Path Parameters - **subscriptionId** (string) - Required - The unique identifier of the subscription. ### Request Example None ### Response #### Success Response (200) - **subscriptionId** (string) - The unique identifier of the subscription. - **status** (string) - The current status of the subscription. - **amount** (number) - The amount charged per interval. - **interval** (string) - The billing interval. #### Response Example ```json { "subscriptionId": "sub_id_here", "status": "active", "amount": 100.00, "interval": "1m" } ``` ``` -------------------------------- ### SyncPaymentRequestDTO Constructor Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-payment-requests.md The constructor initializes the payment request, converts the amount to cents, and validates that exactly one payment source is provided. ```php public function __construct( int|float $amount, public int|CurrencyCode $ccy = 980, #["SensitiveParameter"] public ?array $cardData = null, #["SensitiveParameter"] public ?array $applePay = null, #["SensitiveParameter"] public ?array $googlePay = null, public ?string $destination = null, public ?string $reference = null ) { $this->amount = AmountHelper::toCents($amount); $sources = array_filter([$this->cardData, $this->applePay, $this->googlePay], fn($v) => $v !== null); if (count($sources) !== 1) { throw new InvalidArgumentException('Exactly one of cardData, applePay, or googlePay must be provided.'); } } ``` -------------------------------- ### getDetails(): array Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank.md GETs details to retrieve raw merchant details JSON. ```APIDOC ## GET details ### Description Retrieves raw merchant details JSON. ### Method GET ### Endpoint details ### Parameters No parameters. ### Request Example ```php $details = $service->getDetails(); ``` ### Response #### Success Response - **array** - Raw merchant details JSON, e.g. `$details['merchantName']`. #### Response Example ```php echo $details['merchantName']; ``` ``` -------------------------------- ### Direct Client construction and API calls Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/client.md Constructs a Client directly outside the container using the MONOBANK_TOKEN environment variable, then posts to create an invoice and fetches its status. ```php $client = new Client(['token' => env('MONOBANK_TOKEN')]); $invoice = $client->post('invoice/create', $body)->json(); $status = $client->get('invoice/status', ['invoiceId' => 'inv_123'])->json(); ``` -------------------------------- ### GET /api/qr/{qrId} Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Retrieves details of a specific QR register by its ID. ```APIDOC ## [GET] /api/qr/{qrId} ### Description Retrieves details of a specific QR register by its ID. ### Method GET ### Endpoint /api/qr/{qrId} ### Parameters #### Path Parameters - **qrId** (string) - Required - The unique identifier of the QR register. ### Request Example None ### Response #### Success Response (200) - **shortQrId** (string) - The short version of the QR ID. #### Response Example ```json { "shortQrId": "short_qr_id" } ``` ``` -------------------------------- ### GET /api/qr/list Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Retrieves a list of QR registers (stands) associated with the merchant. ```APIDOC ## [GET] /api/qr/list ### Description Retrieves a list of QR registers (stands) associated with the merchant. ### Method GET ### Endpoint /api/qr/list ### Parameters None ### Request Example None ### Response #### Success Response (200) - **qrId** (string) - The unique identifier of the QR register. - **pageUrl** (string) - The URL of the QR page. #### Response Example ```json [ { "qrId": "qr_id_here", "pageUrl": "https://example.com/qr/qr_id_here" } ] ``` ``` -------------------------------- ### Create invoice and redirect to hosted page Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/dto-invoice-response.md Basic usage via the facade: create an invoice and redirect the customer to the hosted payment page using the pageUrl property. ```php $invoice = Monobank::createInvoice(new InvoiceRequestDTO(amount: 100.00)); return redirect($invoice->pageUrl); ``` -------------------------------- ### List QR Registers with Monobank::getQrList Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Fetches all QR registers and prints each QR's ID and page URL. Use this to list physical QR stands. ```php $list = Monobank::getQrList(); foreach ($list as $qr) { echo $qr->qrId . ' - ' . $qr->pageUrl; } ``` -------------------------------- ### MonobankWebhookController constructor Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-webhook-controller.md Constructor for MonobankWebhookController. The PubKeyProvider is injected via the container binding PubKeyProvider::class. ```php public function __construct(protected PubKeyProvider $pubKeyProvider) ``` -------------------------------- ### Register Monobank service provider singletons Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/configuration.md Service provider registration wiring: binds ClientInterface, the 'monobank' alias, and PubKeyProvider from config('monobank') (merged config/monobank.php). Used in normal Laravel usage; both classes are constructed here from the merged config. ```php // register() in src/MonobankServiceProvider.php $this->app->singleton(ClientInterface::class, fn ($app) => new Client(config('monobank'))); $this->app->singleton('monobank', fn ($app) => new Monobank(config('monobank'), $app->make(ClientInterface::class))); $this->app->singleton(PubKeyProvider::class, fn ($app) => new PubKeyProvider($app->make(ClientInterface::class))); ``` -------------------------------- ### Monobank::getStatement Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-facade.md Static facade method to get a statement. Mirrors the instance method on the Monobank service. ```APIDOC ## [STATIC] Monobank::getStatement ### Description Retrieves a statement for a given period. This is a static facade method that forwards to the underlying service instance. ### Method STATIC ### Endpoint Monobank::getStatement(int $from, ?int $to = null, ?string $code = null) ### Parameters - **$from** (int) - Required - Start timestamp. - **$to** (?int) - Optional - End timestamp. - **$code** (?string) - Optional - Statement code. ### Return array<\AratKruglik\Monobank\DTO\StatementItem> ``` -------------------------------- ### Monobank::getToken Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/_autodocs/api-reference/monobank-facade.md Static facade method to get the token. Mirrors the instance method on the Monobank service. ```APIDOC ## [STATIC] Monobank::getToken ### Description Retrieves the current token. This is a static facade method that forwards to the underlying service instance. ### Method STATIC ### Endpoint Monobank::getToken() ### Return string|null ``` -------------------------------- ### Configure .env with MONOBANK_TOKEN Source: https://github.com/aratkruglik/monobank-acquiring-laravel/blob/main/README.md Add your Monobank Acquiring Token (X-Token) and URLs to the .env file. The redirect URL is used for the payment page redirect and the webhook URL for payment notifications. ```env MONOBANK_TOKEN=your_token_here MONOBANK_REDIRECT_URL=https://your-site.com/checkout/success MONOBANK_WEBHOOK_URL=https://your-site.com/api/monobank/webhook ```