Sslcommerz Laravel Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require raziul/sslcommerz-laravel
   

2. Publish config (optional but recommended):

   php artisan sslcommerz:install
   

3. Configure .env:

   SSLC_SANDBOX=true
   SSLC_STORE_ID=your_store_id
   SSLC_STORE_PASSWORD=your_store_password
   SSLC_STORE_CURRENCY=BDT
   

4. Define routes in routes/web.php:

   Route::post('/sslcommerz/success', [SslcommerzController::class, 'success'])->name('sslc.success');
   Route::post('/sslcommerz/failure', [SslcommerzController::class, 'failure'])->name('sslc.failure');
   

First Use Case: Initiate a Payment

use Raziul\Sslcommerz\Facades\Sslcommerz;

$response = Sslcommerz::setOrder(100, 'INV-123', 'Premium Subscription')
    ->setCustomer('John Doe', 'john@example.com', '1234567890')
    ->makePayment();

if ($response->success()) {
    return redirect($response->gatewayPageURL());
}

Implementation Patterns

Core Workflow: Payment Lifecycle

1. Initiate Payment Chain methods for order/customer details:

   Sslcommerz::setOrder($amount, $invoiceId, $productName)
       ->setCustomer($name, $email, $phone)
       ->setShippingInfo(1, 'Dhaka, Bangladesh')
       ->makePayment();
   

2. Handle Callbacks Implement controller methods for:

   public function success(Request $request) {
       if (Sslcommerz::verifyHash($request->all())) {
           // Process valid payment
       }
   }
   

3. Post-Payment Actions

   • Validate: Sslcommerz::validatePayment($requestData, $transactionId, $amount)
   • Refund: Sslcommerz::refundPayment($bankTransactionId, $amount, 'Reason')
   • Check Status: Sslcommerz::checkRefundStatus($refundRefId)

Integration Tips

• Use Facade: Prefer Sslcommerz:: for simplicity in controllers/views.
• Service Layer: For complex logic, inject SslcommerzService via constructor.
• Webhook Handling: Validate IPN payloads with verifyHash() before processing.
• Testing: Use sandbox mode (SSLC_SANDBOX=true) for development.

Common Patterns

// 1. Payment Initiation with Custom Data
Sslcommerz::setOrder($amount, $invoiceId, 'Product')
    ->setCustomerData(['custom_field' => 'value'])
    ->makePayment();

// 2. Refund with Additional Metadata
Sslcommerz::refundPayment($txId, 50, 'Partial Refund')
    ->setRefundReason('Customer Request')
    ->execute();

Gotchas and Tips

Pitfalls

1. Hash Mismatch Errors

   • Ensure SSLC_STORE_PASSWORD matches SSLCommerz dashboard.
   • Verify verifyHash() includes all required fields (e.g., val_id, status).

2. Sandbox vs Live Mode

   • Forgetting to switch SSLC_SANDBOX=false in production causes failed transactions.
   • Test refunds in sandbox first—they behave differently than live.

3. Transaction IDs

   • transactionId (from makePayment()) ≠ bankTransactionId (used for refunds).
   • Always log these IDs for debugging.

4. Callback URL Validation

   • SSLCommerz rejects requests if callback URLs don’t match registered routes.
   • Use absolute URLs (e.g., https://yourdomain.com/sslcommerz/success).

Debugging Tips

• Enable Logging:

  Sslcommerz::setDebugMode(true); // Logs requests/responses to storage/logs/sslcommerz.log
  

• Inspect Responses:

  $response = Sslcommerz::makePayment();
  dd($response->getRawResponse()); // Raw SSLCommerz API response
  

• Common Errors:
  • Invalid Store ID/Password: Double-check .env values.
  • Invalid Signature: Ensure verifyHash() includes all fields in the correct order.

Extension Points

1. Customize Payment Data Override default fields via setCustomData():

   Sslcommerz::setCustomData(['product_id' => 123, 'user_id' => 456]);
   

2. Extend Validation Add custom rules to validatePayment() by subclassing PaymentValidator:

   class CustomValidator extends PaymentValidator {
       protected function rules() {
           return parent::rules() + ['custom_field' => 'required'];
       }
   }
   

3. Webhook Retries Implement exponential backoff for failed IPN callbacks:

   if (!Sslcommerz::verifyHash($request->all())) {
       // Retry logic or queue job
   }
   

Configuration Quirks

• Currency Handling: Ensure SSLC_STORE_CURRENCY matches SSLCommerz dashboard.
• Route Names: Customize via .env (SSLC_ROUTE_*) if conflicts exist.
• Timeouts: SSLCommerz API has a 30-second timeout; avoid long-running operations in callbacks.

Pro Tips

• Use Events: Dispatch PaymentInitiated, PaymentSucceeded, etc., for decoupled logic.
• Queue Refunds: Offload refund processing to queues:

  RefundPaymentJob::dispatch($txId, $amount, $reason);
  

• Mocking for Tests:

  $this->partialMock(Sslcommerz::class, 'makePayment')
       ->shouldReturn(new PaymentResponse(['success' => true]));