Omnipay3 Yandexkassa Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require andchir/omnipay3-yandexkassa
   

   Ensure your composer.json has "minimum-stability": "dev" if using a dev package.

2. Service Provider Register the gateway in config/app.php under providers:

   Omnipay\Omnipay::create('YandexKassa')
   

   Or publish the config (if available) via:

   php artisan vendor:publish --provider="Andchir\Omnipay3YandexKassa\YandexKassaServiceProvider"
   

3. First Use Case: Basic Payment

   use Omnipay\Omnipay;
   
   $gateway = Omnipay::create('YandexKassa');
   $gateway->setShopId('your_shop_id');
   $gateway->setSecretKey('your_secret_key');
   
   $response = $gateway->purchase([
       'amount' => '10.00',
       'currency' => 'RUB',
       'description' => 'Test Payment',
       'method' => 'bank_card', // or 'wallet'
       'capture' => true,
   ])->send();
   
   if ($response->isSuccessful()) {
       // Redirect to Yandex.Kassa payment page
       $paymentUrl = $response->getPaymentUrl();
       return redirect($paymentUrl);
   }
   

4. Key Config Check config/omnipay.php (if published) for:

   • shopId (Yandex.Kassa merchant ID)
   • secretKey (API secret)
   • testMode (set to true for sandbox testing)

Implementation Patterns

Workflows

1. Authorization + Capture For deferred payments (e.g., subscriptions):

   // Authorize (hold funds)
   $authResponse = $gateway->authorize(['amount' => '20.00'])->send();
   if ($authResponse->isSuccessful()) {
       $transactionId = $authResponse->getTransactionReference();
       // Later...
       $captureResponse = $gateway->capture([
           'amount' => '20.00',
           'transactionReference' => $transactionId,
       ])->send();
   }
   

2. Webhook Handling Validate Yandex.Kassa webhook signatures and process events:

   use Andchir\Omnipay3YandexKassa\Webhook\WebhookValidator;
   
   $validator = new WebhookValidator($request->getContent(), $request->get('signature'));
   if ($validator->isValid()) {
       $event = $validator->getEvent();
       // Handle event (e.g., payment.succeeded)
   }
   

3. Refunds

   $refundResponse = $gateway->refund([
       'amount' => '5.00',
       'transactionReference' => 'YK_12345',
   ])->send();
   

Integration Tips

• Laravel Routes: Route /yandex-kassa/webhook to a controller handling POST requests.
• Middleware: Use web middleware for webhook routes to access $request.
• Logging: Log failed transactions for debugging:

  \Log::error('Yandex.Kassa Error', ['response' => $response->getMessage()]);
  

• Testing: Use Yandex.Kassa’s sandbox with testMode: true.

Gotchas and Tips

Pitfalls

1. Signature Validation

   • Webhook signatures must match Yandex.Kassa’s sha1 hash of the payload + secretKey.
   • Example mismatch:

     $calculatedSignature = sha1($payload . $secretKey);
     if ($calculatedSignature !== $request->get('signature')) {
         abort(403, 'Invalid signature');
     }
     

2. Currency Mismatch

   • Yandex.Kassa only supports RUB in Russia. Hardcoding currency: 'RUB' is recommended.

3. Transaction Reference

   • Always store transactionReference (e.g., YK_12345) for future actions (capture/refund).
   • Example: YK_ prefix indicates Yandex.Kassa transactions.

4. Test Mode Quirks

   • Sandbox payments expire after 10 minutes. Test immediately after creation.
   • Use test card numbers from Yandex.Kassa docs.

Debugging

• Enable Omnipay Logging Add to config/omnipay.php:

  'log' => [
      'enabled' => true,
      'path' => storage_path('logs/omnipay.log'),
  ],
  

• Common Errors:
  • InvalidShopId: Verify shopId in config.
  • InvalidAmount: Ensure amount is a string (e.g., '10.00'), not integer.
  • 403 Forbidden: Check secretKey and webhook signature.

Extension Points

1. Custom Fields Pass additional Yandex.Kassa parameters via data array:

   $gateway->purchase([
       'amount' => '10.00',
       'data' => [
           'confirmation' => ['type' => 'redirect', 'return_url' => url('/payment/confirm')],
           'receipt' => ['customer' => ['phone' => '+79991234567']],
       ],
   ]);
   

2. Event Handling Extend Andchir\Omnipay3YandexKassa\Webhook\WebhookValidator to add custom logic for specific events (e.g., payment.cancelled).

3. Fallbacks Implement retry logic for failed transactions:

   if (!$response->isSuccessful() && $attempts < 3) {
       sleep(2);
       $attempts++;
       retry();
   }