PHPackages ideacrafters/satim-laravel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. ideacrafters/satim-laravel ActiveLibrary[Payment Processing](/categories/payments) ideacrafters/satim-laravel ========================== Laravel package for integrating with Satim payment gateway (official Algerian interbank payment system) v1.3.1(1w ago)15001[1 issues](https://github.com/IdeaCraftersHQ/satim-laravel/issues)1MITPHPPHP ^8.1 Since Dec 23Pushed 2w agoCompare [ Source](https://github.com/IdeaCraftersHQ/satim-laravel)[ Packagist](https://packagist.org/packages/ideacrafters/satim-laravel)[ Docs](https://github.com/IdeaCraftersHQ/oss-satim-laravel)[ RSS](/packages/ideacrafters-satim-laravel/feed)WikiDiscussions main Synced today READMEChangelogDependencies (15)Versions (9)Used By (1) OSS Satim Laravel ================= [](#oss-satim-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/ed33763042b19cc9994c88a8f58ca6158b772ba53a278b36766752d090b53001/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6964656163726166746572732f736174696d2d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ideacrafters/satim-laravel)[![Total Downloads](https://camo.githubusercontent.com/e0c261d4167c38ce08318833cc4716dc4d203f92fef90e1acf3c4ed4366d5355/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6964656163726166746572732f736174696d2d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ideacrafters/satim-laravel)[![License](https://camo.githubusercontent.com/ba07bc954ff0e5f291600d1bd86eff78536b7f6b3e05329b5751fa995cd8c965/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6964656163726166746572732f736174696d2d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ideacrafters/satim-laravel)[![PHP Version](https://camo.githubusercontent.com/2b3483ccd926b72aafac2a47474884f6bfc7f344cf1cb31ba48e4953d9c1c33f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6964656163726166746572732f736174696d2d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ideacrafters/satim-laravel) Laravel package for integrating with the Satim payment gateway (official Algerian interbank payment system). Features -------- [](#features) - Register payments (generate payment links) - Confirm payment status - Process refunds - Auto-convert amounts (DA to cents) - Auto-generate order numbers - Comprehensive test coverage - Fluent/chainable API - Interface-based design Requirements ------------ [](#requirements) - PHP 8.1+ - Laravel 10.x, 11.x, 12.x, or 13.x Installation ------------ [](#installation) ``` composer require ideacrafters/satim-laravel ``` Configuration ------------- [](#configuration) Publish the configuration file: ``` php artisan vendor:publish --tag=satim-config ``` Add your Satim credentials to `.env`: ``` SATIM_USERNAME=your_username SATIM_PASSWORD=your_password SATIM_TERMINAL_ID=your_terminal_id SATIM_LANGUAGE=fr SATIM_CURRENCY=012 SATIM_API_URL=https://test2.satim.dz/payment/rest ``` ### Configuration Options [](#configuration-options) VariableDescriptionDefaultRequired`SATIM_USERNAME`Your Satim merchant username-Yes`SATIM_PASSWORD`Your Satim merchant password-Yes`SATIM_TERMINAL_ID`Your terminal ID-Yes`SATIM_LANGUAGE`Default language (fr, en, ar)`fr`No`SATIM_CURRENCY`Currency code (012 for DZD)`012`No`SATIM_API_URL`API base URL`https://test2.satim.dz/payment/rest`No`SATIM_HTTP_VERIFY_SSL`Enable SSL verification`true`No`SATIM_HTTP_TIMEOUT`Request timeout (seconds)`30`No`SATIM_HTTP_CONNECT_TIMEOUT`Connection timeout (seconds)`10`No**Environment URLs:** - Certification: `https://test2.satim.dz/payment/rest` - Staging: `https://test.satim.dz/payment/rest` - Production: `https://cib.satim.dz/payment/rest` Quick Start ----------- [](#quick-start) ### Understanding the Payment Flow [](#understanding-the-payment-flow) ``` 1. Register Payment → Receive formUrl and mdOrder 2. Redirect User → User pays on Satim's secure page 3. Callback → Satim redirects back to your site 4. Confirm Status → Verify the payment was successful ``` **Key Concepts:** - **mdOrder**: Unique payment identifier from Satim (you'll need this to confirm payment) - **returnUrl**: Where Satim redirects after successful payment - **failUrl**: Where Satim redirects if payment fails or is cancelled - **Amounts**: Always in Algerian Dinars (DA) - automatically converted to cents ### Step 1: Register Payment [](#step-1-register-payment) ``` use Ideacrafters\SatimLaravel\Facades\Satim; use Ideacrafters\SatimLaravel\Exceptions\SatimException; class PaymentController extends Controller { public function create(Request $request) { try { $payment = Satim::amount(100.00) // Amount in DA ->returnUrl(route('payment.success')) ->failUrl(route('payment.failed')) ->description('Order #123') ->register(); // Redirect user to Satim payment page return redirect($payment->formUrl); } catch (SatimException $e) { return back()->withErrors(['error' => 'Payment initialization failed']); } } } ``` ### Step 2: Handle Success Callback [](#step-2-handle-success-callback) ``` public function success(Request $request) { $mdOrder = $request->input('mdOrder'); try { $confirmation = Satim::confirm($mdOrder); if ($confirmation->isPaid()) { // Payment successful! Process the order here // Access payment details: $confirmation->amount, $confirmation->pan, etc. return view('payment.success', [ 'amount' => $confirmation->amount / 100, // Convert back to DA 'reference' => $confirmation->orderNumber, ]); } return redirect()->route('payment.failed'); } catch (SatimException $e) { return redirect()->route('payment.failed'); } } ``` ### Step 3: Handle Failed Callback [](#step-3-handle-failed-callback) ``` public function failed(Request $request) { // Payment was declined, cancelled, or failed return view('payment.failed'); } ``` Refund Payment -------------- [](#refund-payment) Process full or partial refunds for completed payments: ``` public function refund(Request $request) { try { $refund = Satim::refund( orderId: $request->order_id, // mdOrder from Satim amount: $request->amount // Amount in DA (auto-converted to cents) ); if ($refund->isSuccessful()) { return back()->with('success', 'Refund processed'); } return back()->withErrors(['error' => $refund->errorMessage]); } catch (SatimException $e) { return back()->withErrors(['error' => 'Refund failed']); } } ``` Payment Status Reference ------------------------ [](#payment-status-reference) Payment status codes returned by `confirm()`: StatusHelper MethodDescription0-Created (payment not completed)1`isPreAuthorized()`Pre-authorized2`isPaid()`**Payment completed** ✓3`isReversed()`Reversed4`isRefunded()`Refunded5`isDeclined()`Declined6`isDeclined()`Declined by fraud filterResponse Objects ---------------- [](#response-objects) ### RegisterOrderResponse [](#registerorderresponse) ``` $payment = Satim::amount(100)->returnUrl(...)->register(); $payment->orderId; // Satim order ID (mdOrder) - store this! $payment->formUrl; // Redirect user to this URL $payment->isSuccessful(); // Check if registration succeeded ``` ### ConfirmOrderResponse [](#confirmorderresponse) ``` $confirmation = Satim::confirm($mdOrder); $confirmation->isPaid(); // Payment completed (status 2) $confirmation->orderStatus; // Status code (0-6) $confirmation->amount; // Amount in cents $confirmation->pan; // Masked card number $confirmation->orderNumber; // Order reference $confirmation->approvalCode; // Bank approval code ``` ### RefundOrderResponse [](#refundorderresponse) ``` $refund = Satim::refund($orderId, $amount); $refund->isSuccessful(); // Refund succeeded $refund->errorMessage; // Error description if failed ``` Error Handling -------------- [](#error-handling) The package throws three types of exceptions: ``` use Ideacrafters\SatimLaravel\Exceptions\SatimAuthenticationException; use Ideacrafters\SatimLaravel\Exceptions\SatimPaymentException; use Ideacrafters\SatimLaravel\Exceptions\SatimException; try { $payment = Satim::amount(100)->returnUrl(...)->register(); } catch (SatimAuthenticationException $e) { // Error code 5 - Invalid credentials } catch (SatimPaymentException $e) { // Error codes 1, 2, 3, 4, 6, 14 - Payment issues } catch (SatimException $e) { // Error code 7 or unknown - System errors } ``` ### Common Error Codes [](#common-error-codes) CodeExceptionMeaningSolution0-Success-1`SatimPaymentException`Duplicate order numberUse unique order numbers2`SatimPaymentException`Payment declinedTry another card5`SatimAuthenticationException`Invalid credentialsCheck username/password6`SatimPaymentException`Order not foundVerify orderId14`SatimPaymentException`Invalid amountMin 50 DA, whole numbersAdvanced Usage -------------- [](#advanced-usage) ### Using Dependency Injection [](#using-dependency-injection) ``` use Ideacrafters\SatimLaravel\Contracts\SatimInterface; class PaymentController extends Controller { public function __construct(private SatimInterface $satim) {} public function create() { $payment = $this->satim->amount(100)->returnUrl(...)->register(); return redirect($payment->formUrl); } } ``` ### Custom Order Numbers [](#custom-order-numbers) ``` $payment = Satim::amount(100) ->orderNumber('INV' . time()) // Max 10 characters ->returnUrl(route('payment.success')) ->register(); ``` ### User-Defined Fields (UDF) [](#user-defined-fields-udf) Pass custom data through the payment: ``` $payment = Satim::amount(100) ->udf1('customer_123') // Max 20 chars each ->udf2('campaign_summer') ->udf3('referral_code') ->returnUrl(route('payment.success')) ->register(); ``` ### Language Override [](#language-override) ``` // Change language per request (default: 'fr') $payment = Satim::amount(100) ->language('en') // 'fr', 'en', or 'ar' ->returnUrl(route('payment.success')) ->register(); // Or during confirmation $confirmation = Satim::confirm($mdOrder, 'en'); ``` ### Partial Refunds [](#partial-refunds) ``` // Refund partial amount Satim::refund($orderId, 50.00); // Refund 50 DA only // Full refund $confirmation = Satim::confirm($mdOrder); $fullAmount = $confirmation->amount / 100; Satim::refund($orderId, $fullAmount); ``` Best Practices -------------- [](#best-practices) - **Always verify with confirm()**: Don't trust the redirect alone, always confirm payment status - **Store mdOrder**: Save it with your order so you can verify or refund later - **Use HTTPS**: All callback URLs must be HTTPS in production - **Handle exceptions**: Catch specific exception types for better error handling - **Validate amounts**: Minimum 50 DA, use whole numbers - **Test first**: Use test environment before going to production Troubleshooting --------------- [](#troubleshooting) ### "Error code 5: Authentication failed" [](#error-code-5-authentication-failed) Check your credentials in `.env`: ``` SATIM_USERNAME=your_correct_username SATIM_PASSWORD=your_correct_password ``` ### "Amount must be multiple of 100" [](#amount-must-be-multiple-of-100) Use whole DA amounts (integers or floats like 100, 250.00): ``` Satim::amount(100); // ✓ Good Satim::amount(100.50); // ✗ Bad - not a whole DA amount ``` ### "Invalid return URL" [](#invalid-return-url) Ensure URLs are fully qualified and use HTTPS: ``` ->returnUrl(route('payment.success')) // ✓ Good ->returnUrl('/payment/success') // ✗ Bad - relative URL ``` ### Callback not received [](#callback-not-received) - Check firewall allows incoming requests - Verify URLs are publicly accessible - Use `https://` (not `http://`) in production - For local testing, use ngrok or similar tunneling service ### SSL verification issues (local only) [](#ssl-verification-issues-local-only) ``` # ONLY for local development with self-signed certificates SATIM_HTTP_VERIFY_SSL=false ``` ⚠️ **Never disable SSL verification in production** Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Security -------- [](#security) This package handles sensitive payment information. Please ensure: - Always use HTTPS in production - Keep your Satim credentials secure (never commit to version control) - SSL verification is enabled by default - only disable for local development with self-signed certificates - Regularly update the package to receive security fixes If you discover any security-related issues, please email instead of using the issue tracker. License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 43 — FairBetter than 89% of packages Maintenance77 Regular maintenance activity Popularity20 Limited adoption so far Community17 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 76% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~30 days Recently: every ~44 days Total 7 Last Release 12d ago PHP version history (2 changes)v1.0.0PHP ^8.2 v1.1.0PHP ^8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/7fccd459a4d7a226025511ed967a180d8e259dfd41d3077a4f4b43b63e0a8be6?d=identicon)[monaam\_ic](/maintainers/monaam_ic) --- Top Contributors [![mihoubi-akram](https://avatars.githubusercontent.com/u/59308815?v=4)](https://github.com/mihoubi-akram "mihoubi-akram (19 commits)")[![y-boudehane](https://avatars.githubusercontent.com/u/109896280?v=4)](https://github.com/y-boudehane "y-boudehane (4 commits)")[![BadreddineZatout](https://avatars.githubusercontent.com/u/57811383?v=4)](https://github.com/BadreddineZatout "BadreddineZatout (1 commits)")[![monaam](https://avatars.githubusercontent.com/u/8881655?v=4)](https://github.com/monaam "monaam (1 commits)") --- Tags laravelpaymentpayment gatewayAlgeriasatimDz ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/ideacrafters-satim-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/ideacrafters-satim-laravel/health.svg)](https://phpackages.com/packages/ideacrafters-satim-laravel) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3355.3M346](/packages/psalm-plugin-laravel)[api-platform/laravel API Platform support for Laravel 58171.6k14](/packages/api-platform-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)