Download the PHP package sslcommerz/laravel without Composer

SSLCOMMERZ Laravel Package

Table of Contents

• Installation
• Configuration
• Quick Start
• Payment Flow
• Usage
  • Initiate Payment
  • Recurring Payments (Easycheckout)
  • Validate Transaction
  • Refund
  • Query Transaction
• Callback Handling
  • Redirect URLs After Payment
• Events
• Hash Verification
• Custom Controllers
• Testing
• API Reference
• Security
• Troubleshooting

Installation

Publish Configuration

Publish Routes (Optional)

Publish Everything

Configuration

Add these variables to your .env file:

Note: SSLCOMMERZ_SALT_KEY is required for recurring payments (Easycheckout).

Quick Start

Sandbox Test Credentials

Register at https://developer.sslcommerz.com/registration/ to get your sandbox credentials.

Test Card Numbers:

Mobile OTP: 111111 or 123456

Custom Controllers

You can easily override the default callback behavior.

1. Publish the Controller Stub:

2. Update Configuration: In your config/sslcommerz.php, update the controller option to point to your new controller:

3. Customize Logic: Edit app/Http/Controllers/SslcommerzCallbackController.php to suit your needs.

Note: If you want to customize the URLs, you can also publish the routes: php artisan vendor:publish --tag=sslcommerz-routes

Payment Flow

Usage

Initiate Payment

Specialized Parameters (API v4)

Recurring Payments (Easycheckout)

SSLCOMMERZ supports recurring payments via a schedule parameter.

1. Configure SALT Key: Add SSLCOMMERZ_SALT_KEY to your .env file. This key is provided by the SSLCOMMERZ team.

2. Initiate Recurring Payment:

3. Manage Subscriptions:

Validate Transaction

Refund

Query Transaction

Logging

By default, the package logs all gateway interactions using Laravel's default log configuration. You can disable logging by setting SSLCOMMERZ_LOG_ENABLED=false.

Callback Handling

The package registers these routes automatically:

All routes exclude CSRF verification since SSLCOMMERZ sends POST requests.

By default, the prefix is ssl. You can change it via sslcommerz.routes.prefix in config/sslcommerz.php, or publish routes to customize paths.

Redirect URLs After Payment

Define your own routes and views to show the payment result to the user:

Events

Listen to these events in your EventServiceProvider:

Persistence (Handling Orders)

Since this package is database-agnostic, you should handle transaction persistence in your own application using listeners.

Example Listener:

Hash Verification

The package automatically verifies hash signatures on IPN callbacks. You can also verify manually:

Or use the middleware on your own routes:

Testing

Run Package Tests

Mock in Your Application Tests

API Reference

SSLCOMMERZ::initiate(PaymentRequestDTO|array $request): PaymentResponseDTO

Creates a payment session. If an array is passed, it is automatically converted to a DTO with sensible defaults.

SSLCOMMERZ::validate(string $valId): ValidationResponseDTO

Validates a transaction using the validation ID from callback/IPN.

SSLCOMMERZ::refund(RefundRequestDTO|array $request): RefundResponseDTO

Initiates a refund for a previously successful transaction.

SSLCOMMERZ::queryTransaction(string $tranId): TransactionQueryDTO

Queries all transactions associated with a merchant transaction ID.

SSLCOMMERZ::queryBySession(string $sessionKey): ValidationResponseDTO

Queries transaction status by SSLCOMMERZ session key.

SSLCOMMERZ::queryRefundStatus(string $refundRefId): RefundResponseDTO

Checks the current status of a refund request.

SSLCOMMERZ::verifyHash(array $data): bool

Verifies the MD5 hash signature of callback data.

Security

This package implements multiple layers of security:

1. Hash Verification: All IPN callbacks are verified using SSLCOMMERZ's MD5 signature algorithm
2. API Validation: Every successful payment is validated server-side via the Order Validation API
3. CSRF Exemption: Only callback routes from SSLCOMMERZ are CSRF-exempt
4. Logging: All gateway interactions are logged for audit trails
5. Environment Isolation: Separate endpoints for sandbox and production

Best Practices

• Always validate transactions via the API, never trust callback data alone
• Monitor risk_level in validation responses (0 = Safe, 1 = Risky)
• Use value_a through value_d to pass your own references
• Set up IPN as the primary notification method (works even if user closes browser)
• Register your production IP at SSLCOMMERZ for refund API access

Troubleshooting

License

MIT License. See LICENSE for details.