Omnipay Sberbank Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require andrewnovikof/omnipay-sberbank
   

   Ensure omnipay/omnipay is also installed (dependency).

2. Basic Configuration Register the gateway in Laravel’s config/services.php (or a dedicated sberbank.php):

   'sberbank' => [
       'gateway' => 'Sberbank',
       'testMode' => env('SBERBANK_TEST_MODE', false),
       'merchantId' => env('SBERBANK_MERCHANT_ID'),
       'password' => env('SBERBANK_PASSWORD'),
       'terminalKey' => env('SBERBANK_TERMINAL_KEY'),
       'accountNumber' => env('SBERBANK_ACCOUNT_NUMBER'),
       'url' => env('SBERBANK_URL', 'https://online.sberbank.ru/'), // Test: 'https://sb-online.sberbank.ru/'
   ],
   

3. First Use Case: Purchase Request

   use Omnipay\Omnipay;
   
   $gateway = Omnipay::create('Sberbank');
   $gateway->setMerchantId(config('services.sberbank.merchantId'));
   $gateway->setPassword(config('services.sberbank.password'));
   
   $response = $gateway->purchase([
       'amount' => '100.00',
       'currency' => 'RUB',
       'description' => 'Test Purchase',
       'returnUrl' => route('payment.return'),
       'cancelUrl' => route('payment.cancel'),
   ])->send();
   
   if ($response->isRedirect()) {
       $response->redirect(); // Redirect to Sberbank
   }
   

4. Handling Return Create a route (payment/return) to process the response:

   $gateway->completePurchase($request->all());
   

Implementation Patterns

Workflow: Full Payment Flow

1. Initiate Payment Use purchase() for one-click payments or authorize() for deferred capture.

   $gateway->purchase(['amount' => '200.00', 'currency' => 'RUB', ...]);
   

2. Handle Redirect Sberbank returns to returnUrl with a paymentId and status. Validate via:

   $gateway->completePurchase($request->all());
   

3. Capture/Refund After authorization, capture funds:

   $gateway->capture(['amount' => '200.00', 'currency' => 'RUB'])->send();
   

   Refunds:

   $gateway->refund(['transactionId' => $transactionId])->send();
   

4. Webhooks (Optional) Sberbank supports IPN (Instant Payment Notification). Listen for POST to /payment/webhook:

   $gateway->verifyNotification($request->all());
   

Integration Tips

• Laravel Facade: Extend Omnipay\Omnipay with a custom facade for cleaner syntax:

  class SberbankGateway extends OmnipayGateway {
      public function __construct() {
          $this->setGateway('Sberbank');
          $this->setMerchantId(config('services.sberbank.merchantId'));
          // ... other config
      }
  }
  

  Register in AppServiceProvider:

  app()->singleton('sberbank', function () {
      return new SberbankGateway();
  });
  

• Testing Use Sberbank’s test sandbox (testMode => true) with dummy credentials:

  $gateway->setTestMode(true);
  

• Logging Enable Omnipay’s logger for debugging:

  $gateway->setLogger(new \Monolog\Logger('sberbank'));
  

Gotchas and Tips

Pitfalls

1. Terminal Key vs. Password

   • terminalKey is not the same as password. The password is your merchant account password, while terminalKey is tied to a specific terminal in Sberbank’s system. Mixing them up will cause INVALID_TERMINAL_KEY errors.

2. Currency and Amount Formatting

   • Sberbank expects RUB as the currency (hardcoded in the package). Amounts must be strings (e.g., '100.00', not 100 or 100.0).
   • Non-string amounts trigger INVALID_AMOUNT errors.

3. Test Mode Quirks

   • Test mode URLs must match exactly:
     • Live: https://online.sberbank.ru/
     • Test: https://sb-online.sberbank.ru/
   • Test transactions do not settle; they’re voided automatically.

4. Redirect Validation

   • Always validate paymentId and status in the return URL. Sberbank may return false for test transactions if not configured properly.

5. Character Encoding

   • Russian characters in description or returnUrl may cause issues. URL-encode them:

     'description' => urlencode('Описание на русском'),
     

Debugging

1. Error Codes Common Sberbank errors and fixes:

   Error Code	Cause	Solution
   INVALID_TERMINAL_KEY	Wrong terminalKey or password	Double-check credentials in Sberbank panel.
   INVALID_AMOUNT	Amount not a string or wrong format	Use '100.00' (string).
   INVALID_CURRENCY	Currency not RUB	Hardcoded in package; no workaround.
   INVALID_MERCHANT	merchantId not registered	Verify with Sberbank support.

2. Logging Enable Omnipay’s debug mode:

   $gateway->setTestMode(true); // Logs all requests/responses
   

Extension Points

1. Custom Fields Sberbank supports additional fields like orderId or customerEmail. Extend the gateway:

   $gateway->setAdditionalData([
       'orderId' => 'ORD123',
       'customerEmail' => 'user@example.com',
   ]);
   

2. Webhook Handling Parse Sberbank’s IPN payloads:

   $data = $request->all();
   $gateway->verifyNotification($data); // Returns true/false
   

   Example payload:

   [
       'paymentId' => '123456',
       'status' => 'success',
       'amount' => '100.00',
       'currency' => 'RUB',
       'signature' => '...', // Verify with your secret key
   ]
   

3. Recurring Payments Use authorize() + capture() for deferred payments. For subscriptions, implement a cron job to capture pending authorizations:

   $authorization = $gateway->authorize(['amount' => '50.00'])->send();
   // Later...
   $gateway->capture(['amount' => '50.00', 'transactionId' => $authorization->getTransactionId()]);
   

Configuration Quirks

1. Environment Variables Ensure .env variables are loaded:

   SBERBANK_TEST_MODE=true
   SBERBANK_MERCHANT_ID=your_merchant_id
   SBERBANK_PASSWORD=your_password
   SBERBANK_TERMINAL_KEY=your_terminal_key
   SBERBANK_ACCOUNT_NUMBER=your_account_number
   

2. URL Overrides Override the base URL in config for custom endpoints (e.g., for internal testing):

   'url' => env('SBERBANK_URL', 'https://custom-test.sberbank.ru/'),
   

3. Timeouts Sberbank’s API may timeout during peak hours. Increase Laravel’s HTTP client timeout:

   $gateway->setHttpClient(new \GuzzleHttp\Client([
       'timeout' => 30,
   ]));