dits/shurjopay-laravel-package

There is no license information available for the latest version (dev-main) of this package.

dev-main 2025-10-11 07:25 UTC

Requires

• illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0

Unknown License

• Dhaka IT Solutions Ltd.

README

Laravel 8, 9, 10, 11, 12 Compatible

A modern Laravel package for integrating ShurjoPay payment gateway using the latest RESTful API.

Features

• ✅ ShurjoPay RESTful API v2 integration
• ✅ Automatic token management with caching
• ✅ Support for both Sandbox and Production environments
• ✅ Built-in payment verification
• ✅ Beautiful payment callback UI
• ✅ Fully customizable views and callbacks
• ✅ Easy to use service class
• ✅ PSR-4 autoloading

Installation

1. Install via Composer

composer require dits/shurjopay-laravel-package

2. Register Service Provider (Laravel < 5.5)

If you're using Laravel < 5.5, add the service provider to config/app.php:

'providers' => [
    // ...
    dits\ShurjopayLaravelPackage\ShurjopayServiceProvider::class,
],

3. Publish Configuration

php artisan vendor:publish --tag=shurjopay-config

This creates config/shurjopay.php in your project.

4. Publish Views (Optional)

If you want to customize the payment callback page:

php artisan vendor:publish --tag=shurjopay-views

5. Configure Environment Variables

Add the following to your .env file:

# Environment: sandbox or production
SHURJOPAY_ENVIRONMENT=sandbox

# Your ShurjoPay credentials (provided by ShurjoPay)
SHURJOPAY_USERNAME=sp_sandbox
SHURJOPAY_PASSWORD=pyyk97hu&6u6

# Merchant prefix for order IDs
SHURJOPAY_PREFIX=SP

# Optional: Custom callback URLs
SHURJOPAY_RETURN_URL=
SHURJOPAY_CANCEL_URL=

Usage

Basic Payment Flow

1. Initiate Payment

use dits\ShurjopayLaravelPackage\ShurjopayService;

class PaymentController extends Controller
{
    protected $shurjopayService;
    
    public function __construct(ShurjopayService $shurjopayService)
    {
        $this->shurjopayService = $shurjopayService;
    }
    
    public function initiatePayment(Request $request)
    {
        try {
            $paymentData = [
                // Required fields
                'amount' => 1000.00,
                'currency' => 'BDT',
                'order_id' => 'ORDER123', // Your internal order ID
                'customer_name' => 'John Doe',
                'customer_address' => '123 Main Street',
                'customer_city' => 'Dhaka',
                'customer_phone' => '01711111111',
                'customer_email' => '[e-mail]',
                
                // Optional fields
                'customer_post_code' => '1200',
                'customer_state' => 'Dhaka',
                'customer_country' => 'Bangladesh',
                'discount_amount' => 0,
                'disc_percent' => 0,
                
                // Custom data (for your reference)
                'value1' => 'Product Name',
                'value2' => 'Additional Info',
                'value3' => 'More Data',
                'value4' => 'Extra Field',
            ];
            
            $response = $this->shurjopayService->initiatePayment($paymentData);
            
            // Redirect user to payment page
            if (isset($response['checkout_url'])) {
                return redirect($response['checkout_url']);
            }
            
            return back()->with('error', 'Failed to initiate payment');
            
        } catch (\Exception $e) {
            return back()->with('error', $e->getMessage());
        }
    }
}

2. Handle Payment Callback

The package automatically handles callbacks at /shurjopay/callback route. After payment, users are redirected here with payment details.

Option A: Use Default Callback View

The package provides a beautiful default callback page that displays payment results.

Option B: Custom Callback Handling

Create a custom callback in your route and store the URL in session before initiating payment:

public function initiatePayment(Request $request)
{
    // Store custom callback URL in session
    session(['shurjopay_custom_callback' => route('payment.custom.callback')]);
    
    // Initiate payment...
    $response = $this->shurjopayService->initiatePayment($paymentData);
    
    return redirect($response['checkout_url']);
}

public function customCallback()
{
    // Get payment result from session
    $result = session('payment_result');
    
    if ($result['is_success']) {
        // Payment successful - Update your database
        // $result contains all payment information
        
        return view('payment.success', compact('result'));
    } else {
        // Payment failed or cancelled
        return view('payment.failed', compact('result'));
    }
}

3. Verify Payment Manually (Optional)

You can manually verify any payment using the ShurjoPay order ID:

public function verifyPayment($orderId)
{
    try {
        $verification = $this->shurjopayService->verifyPayment($orderId);
        
        // Check payment status
        $spCode = $verification[0]['sp_code'];
        
        if ($this->shurjopayService->isPaymentSuccessful($spCode)) {
            // Payment successful (sp_code = 1000)
            // Update order status in database
        } else {
            // Payment failed or cancelled
            // sp_code = 1001 (declined) or 1002 (cancelled)
        }
        
        return $verification;
        
    } catch (\Exception $e) {
        // Handle error
        return response()->json(['error' => $e->getMessage()], 500);
    }
}

Payment Response Codes

Code	Description
1000	Transaction successful
1001	Transaction declined by issuer bank
1002	Transaction canceled by customer

Available Methods

ShurjopayService Methods

// Generate authentication token (automatically cached)
$tokenData = $shurjopayService->getToken();

// Initiate payment
$response = $shurjopayService->initiatePayment($paymentData);

// Verify payment
$verification = $shurjopayService->verifyPayment($orderId);

// Generate custom order ID
$orderId = $shurjopayService->generateOrderId('CUSTOM123');

// Check if payment was successful
$isSuccess = $shurjopayService->isPaymentSuccessful($spCode);

// Get human-readable status message
$message = $shurjopayService->getPaymentStatusMessage($spCode);

Payment Data Structure

Payment Initiation Response

{
  "checkout_url": "https://sandbox.shurjopayment.com/...",
  "amount": 1000.00,
  "currency": "BDT",
  "sp_order_id": "sp6405ae1473f63",
  "customer_order_id": "ORDER123",
  "customer_name": "John Doe",
  "customer_address": "123 Main Street",
  "customer_city": "Dhaka",
  "customer_phone": "01711111111",
  "customer_email": "[e-mail]",
  "intent": "sale",
  "transactionStatus": "Initiated"
}

Payment Verification Response

[
  {
    "id": 1109600,
    "order_id": "sp6405c8f848b27",
    "customer_order_id": "ORDER123",
    "currency": "BDT",
    "amount": "1000.00",
    "payable_amount": "990.00",
    "discount_amount": "0.00",
    "disc_percent": 1,
    "received_amount": "990.00",
    "bank_trx_id": "ABC123456",
    "bank_status": "Success",
    "sp_code": "1000",
    "sp_message": "Success",
    "transaction_status": "Completed",
    "method": "Visa",
    "name": "John Doe",
    "email": "[e-mail]",
    "address": "123 Main Street",
    "city": "Dhaka",
    "value1": "Product Name",
    "value2": null,
    "value3": null,
    "value4": null,
    "date_time": "2023-03-06 17:06:19"
  }
]

Sandbox Testing

Test Credentials

The package comes with default sandbox credentials:

• Username: sp_sandbox
• Password: pyyk97hu&6u6
• Environment: sandbox

Test Card Information

Use these test cards in sandbox environment:

Card Number	Expiry	CVC	Name	Result
4444 4444 4444 4444	12/30	123	TEST	Success
4444 3333 2222 1111	12/30	123	TEST	Declined

Configuration Reference

The config/shurjopay.php file contains:

return [
    // 'sandbox' or 'production'
    'environment' => env('SHURJOPAY_ENVIRONMENT', 'sandbox'),
    
    // ShurjoPay credentials
    'username' => env('SHURJOPAY_USERNAME', 'sp_sandbox'),
    'password' => env('SHURJOPAY_PASSWORD', 'pyyk97hu&6u6'),
    
    // Order ID prefix
    'prefix' => env('SHURJOPAY_PREFIX', 'SP'),
    
    // Optional custom callback URLs
    'return_url' => env('SHURJOPAY_RETURN_URL', null),
    'cancel_url' => env('SHURJOPAY_CANCEL_URL', null),
];

Routes

The package registers the following route:

• GET|POST /shurjopay/callback - Payment callback handler (named: shurjopay.callback)

Changelog

Version 2.0.0

• ✅ Complete rewrite using ShurjoPay RESTful API v2
• ✅ Token-based authentication with automatic caching
• ✅ Modern Laravel HTTP client
• ✅ Improved error handling
• ✅ Beautiful default callback UI
• ✅ Better documentation

Version 1.x

• Legacy XML-based API (deprecated)

Security

• Tokens are automatically cached for 14 minutes (safe margin for 15-minute expiry)
• All API communications use HTTPS
• Sensitive data is never logged

Support

For issues, questions, or contributions, please visit:

• ShurjoPay Official Documentation
• Package Repository

License

This package is open-sourced software licensed under the MIT license.

Developed by DITS
Compatible with Laravel 8, 9, 10, 11, and 12