Netopia Mobilpay Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require birkof/netopia-mobilpay
   

2. Configure environment variables in .env:

   MOBILPAY_MERCHANT_ID=your_merchant_id
   MOBILPAY_SECRET=your_secret_key
   MOBILPAY_SANDBOX=true  # Set to false for production
   MOBILPAY_PUBLIC_CERT_PATH=/path/to/sandbox.YOUR-SIGNATURE.public.cer
   MOBILPAY_PRIVATE_KEY_PATH=/path/to/sandbox.YOUR-SIGNATURE.private.key
   

3. First use case: Create a payment form

   use Mobilpay\Payment\Request\Card;
   use Mobilpay\Payment\Invoice;
   
   $request = new Card();
   $request->signature = env('MOBILPAY_MERCHANT_ID');
   $request->orderId = 'ORDER-' . Str::uuid()->toString();
   $request->confirmUrl = route('mobilpay.webhook');
   $request->returnUrl = route('checkout.success');
   
   $invoice = new Invoice();
   $invoice->currency = 'DKK';
   $invoice->amount = '49.99';
   $invoice->details = 'Premium Subscription';
   $request->invoice = $invoice;
   
   // Encrypt the request
   $request->encrypt(env('MOBILPAY_PUBLIC_CERT_PATH'));
   
   // Render the form (Blade example)
   return view('checkout.mobilpay', [
       'envKey' => $request->getEnvKey(),
       'data' => $request->getEncData(),
       'cipher' => $request->getCipher(),
       'iv' => $request->getIv(),
   ]);
   

4. Create a webhook endpoint (routes/web.php):

   Route::post('/mobilpay/webhook', [MobilpayWebhookController::class, 'handle']);
   

Where to Look First

• Package structure: Focus on Mobilpay\Payment\Request for payment flows and Mobilpay\Payment\Notify for webhook handling.
• Configuration: Check MOBILPAY_* env vars and certificate paths.
• Sandbox testing: Always test in MobilePay’s sandbox before production.

Implementation Patterns

Core Workflows

1. Payment Initiation

// Service class example
class MobilpayService
{
    public function createPayment(array $data): array
    {
        $request = new Card();
        $request->signature = env('MOBILPAY_MERCHANT_ID');
        $request->orderId = $data['order_id'];
        $request->confirmUrl = route('mobilpay.webhook');
        $request->returnUrl = $data['return_url'];

        $invoice = new Invoice();
        $invoice->currency = $data['currency'];
        $invoice->amount = $data['amount'];
        $invoice->details = $data['description'];
        $request->invoice = $invoice;

        $request->encrypt(env('MOBILPAY_PUBLIC_CERT_PATH'));

        return [
            'envKey' => $request->getEnvKey(),
            'data' => $request->getEncData(),
            'cipher' => $request->getCipher(),
            'iv' => $request->getIv(),
        ];
    }
}

2. Webhook Handling

// Controller example
class MobilpayWebhookController extends Controller
{
    public function handle(Request $request)
    {
        $privateKey = env('MOBILPAY_PRIVATE_KEY_PATH');
        $requestObj = RequestAbstract::factoryFromEncrypted(
            $request->input('env_key'),
            $request->input('data'),
            $privateKey,
            null, // No password
            $request->input('cipher'),
            $request->input('iv')
        );

        $notify = $requestObj->objPmNotify;

        // Process based on action
        switch ($notify->action) {
            case 'confirmed':
                // Update order status
                break;
            case 'canceled':
                // Handle cancellation
                break;
        }

        // Acknowledge
        return response()->xml("
            <crc error_type=\"0\" error_code=\"0\">{$notify->action}</crc>
        ");
    }
}

3. Refunds

use Mobilpay\Payment\Request\Refund;

$refund = new Refund();
$refund->signature = env('MOBILPAY_MERCHANT_ID');
$refund->orderId = 'ORDER-123';
$refund->confirmUrl = route('mobilpay.webhook');
$refund->amount = '20.00';
$refund->currency = 'DKK';
$refund->encrypt(env('MOBILPAY_PUBLIC_CERT_PATH'));

// Post to MobilePay API

Integration Tips

1. Laravel Service Container Bind the service in AppServiceProvider:

   $this->app->bind(MobilpayService::class, function ($app) {
       return new MobilpayService();
   });
   

2. Queues for Async Processing Dispatch a job after receiving a webhook:

   ProcessMobilpayWebhook::dispatch($notify)->onQueue('mobilpay');
   

3. Eloquent Model for Transactions

   class MobilpayTransaction extends Model
   {
       protected $fillable = [
           'order_id', 'amount', 'currency', 'status',
           'mobilpay_id', 'webhook_data', 'processed_at'
       ];
   
       const STATUS_PENDING = 'pending';
       const STATUS_COMPLETED = 'completed';
       const STATUS_FAILED = 'failed';
   }
   

4. Middleware for Webhook Validation

   class VerifyMobilpaySignature
   {
       public function handle(Request $request, Closure $next)
       {
           // Validate HMAC or other MobilePay-specific checks
           return $next($request);
       }
   }
   

5. Testing with Factories

   // MobilpayTransactionFactory.php
   public function definition()
   {
       return [
           'order_id' => 'ORDER-' . Str::uuid(),
           'amount' => '49.99',
           'currency' => 'DKK',
           'status' => 'pending',
           'webhook_data' => json_encode(['action' => 'confirmed']),
       ];
   }
   

Gotchas and Tips

Pitfalls

1. OpenSSL 3 Compatibility

   • If using OpenSSL 3, the library automatically switches to aes-256-cbc and requires an IV.
   • Gotcha: Forgetting to pass the iv and cipher in webhook responses will cause decryption failures.
   • Fix: Always include iv and cipher in both request and response payloads.

2. Webhook Idempotency

   • MobilePay may re-send webhooks for the same transaction.
   • Gotcha: Processing the same webhook multiple times can lead to duplicate updates.
   • Fix: Use mobilpay_id (or orderId) to deduplicate:

     if (!MobilpayTransaction::where('mobilpay_id', $notify->orderId)->exists()) {
         // Process
     }
     

3. Certificate Paths

   • Gotcha: Hardcoding certificate paths in code (e.g., /path/to/cert.cer) breaks deployments.
   • Fix: Store paths in .env and validate they exist at runtime:

     if (!file_exists(env('MOBILPAY_PUBLIC_CERT_PATH'))) {
         throw new RuntimeException('Public certificate not found');
     }
     

4. Sandbox vs. Production

   • Gotcha: Accidentally using production credentials in sandbox or vice versa.
   • Fix: Use .env variables and validate environments:

     if (env('MOBILPAY_SANDBOX') && str_contains($endpoint, 'secure.mobilpay.ro')) {
         throw new RuntimeException('Production endpoint used in sandbox mode');
     }
     

5. Error Handling

   • Gotcha: MobilePay returns numeric error codes (e.g., 1001 for invalid merchant), but the library doesn’t throw exceptions by default.
   • Fix: Explicitly check $notify->errorCode and log errors:

     if ($notify->errorCode !== 0) {
         Log::error("MobilePay error {$notify->errorCode}: {$notify->errorMessage}");
         throw new MobilpayException($notify->errorMessage, $notify->errorCode);
     }
     

Debugging Tips

1. Log Raw Requests/Responses Add this to your webhook handler to debug:

   Log::debug('MobilePay Webhook Raw Data', [
       'env_key' => $request->input('env_key'),
       'data' => $request->input('data'),
       'cipher' => $