- How do I install yandex-money/yandex-checkout-sdk-php in a Laravel app?
- Install it with Composer using composer require yoomoney/yandex-checkout-sdk-php. There is no Laravel service provider or facade to register, because this is a framework-agnostic PHP SDK, not a Laravel package. In practice you create a YooKassa\Client with your shopId and secret key, usually resolved from config/services.php and your .env file, and bind it as a singleton in a service provider so controllers and jobs share one instance.
- Which Laravel and PHP versions does this YooKassa SDK support?
- The SDK is not tied to a Laravel release; it only requires a supported PHP version and PSR-compatible HTTP client dependencies, so it works with any Laravel version whose PHP constraint it satisfies. Check the composer.json of the version you install for the exact PHP requirement, since older SDK releases may not support the newest PHP releases. If you prefer a Laravel-native wrapper with facades and published config, community packages exist, but this official SDK is the most actively maintained option and avoids an extra abstraction layer.
- How do I create a payment and redirect the customer to the YooKassa confirmation page?
- Build a PaymentRequest with an Amount, set capture to true for one-step payments or false for two-step authorization, and attach a ConfirmationRedirect with your return_url. Call the client's createPayment method with an idempotency key, then read confirmation_url from the response and redirect the user there. After the customer returns, do not trust the query string alone; fetch the payment by id and check its status before fulfilling the order.
- How do I receive and handle YooKassa webhook notifications in Laravel?
- Create a POST route for the notification URL, exclude it from CSRF protection in your VerifyCsrfToken middleware or bootstrap/app configuration, and parse the body with the SDK's NotificationFactory. The safest production pattern is to treat the payload as a hint: take the payment or refund id from the notification and re-fetch the object from the API before changing order state. Return a 200 response quickly, and push slow work such as emails or inventory updates onto a queued job.
- How do I issue a full or partial refund with this SDK?
- Create a CreateRefundRequest with the payment_id and an Amount for the sum you want to return, then call createRefund with an idempotency key. Passing the full captured amount produces a full refund, while a smaller amount creates a partial refund that can be repeated up to the remaining balance. Refund status moves from pending to succeeded or canceled, so listen for refund webhooks or poll the refund by id instead of assuming immediate success.
- How can I test YooKassa payments without moving real money?
- Use the sandbox shop id and test secret key from your YooKassa dashboard, and point the client at the sandbox base URL if your SDK version exposes that setting. For automated tests, mock the client or the underlying HTTP layer so feature tests never hit the real API, and assert that your code handles pending, waiting_for_capture, and canceled statuses. Keep sandbox credentials in .env.testing and never commit production keys.
- What are idempotency keys and why does the SDK require them?
- An idempotency key is a unique string you generate per operation, and YooKassa uses it to return the original result instead of creating a duplicate payment or refund when a request is retried. The SDK surfaces this as an IdempotenceKey argument on createPayment and createRefund, so always pass one, ideally a UUID stored alongside the order record. This protects you against network timeouts and double clicks, which is a real production concern for payment endpoints.
- How do I handle API errors and exceptions from the YooKassa SDK?
- The SDK throws structured exceptions such as BadApiRequestException for validation failures and ApiException for server or transport problems, and each carries an HTTP status plus an error code and description. Catch them at your payment service boundary and map known codes to user-facing messages while logging the raw response for support. Never swallow these exceptions silently, since a failed capture or refund that is not retried or reconciled will show up later as a payment mismatch.
- Does the SDK support 54-FZ receipts and fiscalization data?
- Yes, you can attach a Receipt with ReceiptItem entries, including description, quantity, amount, VAT code, and payment subject or method, to the PaymentRequest. This lets YooKassa fiscalize the sale through an online cash register without you building the receipt payload by hand. Receipt requirements depend on your tax setup, so verify the VAT and settlement fields you send against your accountant's specification.
- What is platform_fee_amount in version 1.6.9 and how do I use it for split payouts?
- Release 1.6.9 adds an optional platform_fee_amount parameter to the Transfer and Source request objects, which lets you declare the platform commission when routing part of a payment to a recipient. Adoption is a matter of passing the field where you already build Transfer or Source instances, with no config or service provider changes, so keep the calculation in one dedicated fee resolver. The main caveats are upstream: your merchant account must be enabled for platform fees, and rounding, currency, and min or max rules follow the provider's contract rather than the SDK's validation.