README

This package simplifies the integration of the ClicToPay payment gateway into your Laravel applications.

Installation

Install the package via Composer:

composer require Souidev/laravel-clictopay

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Souidev\ClicToPayLaravel\ClicToPayLaravelServiceProvider" --tag="config"

Configure your ClicToPay credentials:

Edit the config/clictopay.php file. It's recommended to use environment variables for sensitive information:

// config/clictopay.php
return [
    'username' => env('CLICTOPAY_USERNAME'),
    'password' => env('CLICTOPAY_PASSWORD'),
    'test_mode' => env('CLICTOPAY_TEST_MODE', true),
    'return_url' => env('CLICTOPAY_RETURN_URL'),
    'fail_url' => env('CLICTOPAY_FAIL_URL'),
    'api_base_url' => env('CLICTOPAY_API_BASE_URL', '[https://test.clictopay.com/payment/rest/](https://test.clictopay.com/payment/rest/)'), // Default test URL
];

Set the corresponding environment variables in your .env file:

CLICTOPAY_USERNAME=your_username
CLICTOPAY_PASSWORD=your_password
CLICTOPAY_TEST_MODE=true  # or false
CLICTOPAY_RETURN_URL=https://your-site.com/payment/success
CLICTOPAY_FAIL_URL=https://your-site.com/payment/fail

Usage

Use the ClicToPay facade to interact with the ClicToPay API:

use Souidev\ClicToPayLaravel\Facades\ClicToPay;

try {
    // Register a payment with optional parameters
    $paymentDetails = ClicToPay::registerPayment([
        // Required parameters
        'orderNumber' => 'ORDER-12345',
        'amount' => 10000, // in cents
        'currency' => 788, // Currency code (788 for TND)
        
        // Optional parameters
        'language' => 'fr',           // fr, en, ar
        'pageView' => 'DESKTOP',      // DESKTOP or MOBILE
        'orderDescription' => 'Payment for order #12345',
        'expirationDate' => '2024-12-31T23:59:59', // ISO 8601
        'jsonParams' => json_encode([
            'email' => 'customer@example.com',  // Required if merchant notifications are enabled
            'orderNumber' => '1234567890',      // Your internal order reference
            // Add any additional parameters needed for bank processing
        ])
    ]);

    // Redirect user to ClicToPay payment page
    return redirect()->away($paymentDetails['formUrl']);

} catch (\Exception $e) {
    return back()->with('error', $e->getMessage());
}

Check payment status:

try {
    $status = ClicToPay::getPaymentStatus([
        'orderId' => 'ORDER-12345',
        'language' => 'fr' // Optional - for localized error messages
    ]);
    
    // Handle the response
    if ($status['ErrorCode'] === '0') { // No system error
        // Process the payment status
        $orderStatus = $status['OrderStatus'];
        // Possible values in $orderStatus:
        // - 0: Order registered but not paid
        // - 1: Order pre-authorized
        // - 2: Order paid
        // - 3: Authorization canceled
        // - 4: Transaction canceled
        // - 5: Authorization on hold
        // - 6: Refund
    }
} catch (\Exception $e) {
    // Handle error
}

Get extended order status:

try {
    $extendedStatus = ClicToPay::getExtendedOrderStatus([
        'orderId' => 'ORDER-12345',
        'language' => 'fr' // Optional - for localized error messages
    ]);
    
    // Handle extended status information
    if ($extendedStatus['ErrorCode'] === '0') {
        // Access additional payment information
        $orderStatus = $extendedStatus['orderStatus'];
        $amount = $extendedStatus['amount'];
        $currency = $extendedStatus['currency'];
        $date = $extendedStatus['date'];
        // ... other available fields
    }
} catch (\Exception $e) {
    // Handle error
}

The package automatically handles test/live mode based on your configuration:

Test mode: Set CLICTOPAY_TEST_MODE=true in your .env file (uses https://test.clictopay.com/payment/rest/)
Production mode: Set CLICTOPAY_TEST_MODE=false (uses https://clictopay.com/payment/rest/ or other provided URL)

Note: When customer notification is enabled for your merchant account, you must include the customer's email address in the jsonParams field as shown in the example above.

Available Methods

Refer to the ClicToPayService class for available methods. Here's a quick overview:

registerPayment(array $params): Registers a new payment.
registerPreAuth(array $params): Registers a pre-authorization.
confirmPayment(array $params): Confirms a pre-authorized payment.
cancelPayment(array $params): Cancels a payment.
refundPayment(array $params): Refunds a payment.
getPaymentStatus(array $params): Retrieves the status of a payment.

Contributing

Please see CONTRIBUTING.md for details.

License

MIT License

souidev / laravel-clictopay

Maintainers

Details