README

Satim.dz PHP Client

A fully open-source PHP package for seamless integration with Satim.dz, the official interbank payment gateway in Algeria.

This package enables merchants and developers to generate secure payment links and retrieve payment statuses directly via the Satim API, facilitating transactions through both CIB and Edahabia cards.

Requirements

PHP 8.1 or higher

Satim.dz API credentials (username, password, terminal ID) via CIBWeb.dz.

Installation

You can install the package via composer:

composer require piteurstudio/satim-php

Usage

Configuration

Configure your Satim.dz API credentials using your project's preferred method of storing sensitive information.

Credentials example:

SATIM_USERNAME=your-satim-username
SATIM_PASSWORD=your-satim-password
SATIM_TERMINAL_ID=your-satim-terminal-id

Initialization

Create a new Satim client by passing your API credentials:

use PiteurStudio\Satim;

$satim = new Satim([
    'username' => env('SATIM_USERNAME'),
    'password' => env('SATIM_PASSWORD'),
    'terminal_id' => env('SATIM_TERMINAL_ID'),
]);

Main Methods

The Satim provides the following methods:

Register a new payment order: register()
Confirm the status of a payment: confirm($orderId)
Refund a payment: refund($orderId)
Retrieve payment status: status($orderId)

Generate a Payment Link

Create a payment link with a few simple method calls:

$payment = $satim
        ->amount(1000) /* Set payment amount in DZD dinars*/
        ->description('Product purchase') /* Optional: Add a description*/
        ->returnUrl('https://example.com/success')
        ->failUrl('https://example.com/fail') // Optional: Specify a different fail URL
        ->orderNumber(1234567890) // Optional: Use custom order number
        ->testMode(true) // Optional: Enable test mode
        ->language('AR') // Optional: Set payment page language (EN, AR, FR - default is FR)
        ->timeout(600) // Optional: Set payment timeout in seconds
        ->userDefinedFields([
           'customer_id' => '12345',
           'order_type' => 'premium'
       ]) // Optional: Add custom user-defined fields
        ->register();

// Retrieve payment information
$paymentDetails = $payment->getResponse();
$orderId = $payment->getOrderId();
$paymentUrl = $payment->getUrl();

// Redirect user to payment page
$payment->redirect();

Optional configuration methods:

Customize the payment process as needed for your specific use case

Confirm Payment

This method need to be used when the user is redirected back to your website after the payment process on return URL or fail URL.

To confirm the status of a payment, you can use the confirm method with the order ID returned from the payment link generation.

$orderConfirmation = $satim->confirm($orderId);

// Retrieve payment status
$orderConfirmation->getResponse();

if ($orderConfirmation->isSuccessful()) {

    echo 'Payment was successful : '.$orderConfirmation->getSuccessMessage();
    
} else {
    // Payment was not successful
    echo 'Payment was not successful' : $orderConfirmation->getErrorMessage();
    
}

Refund a Payment

To refund a payment, you can use the refundOrder method with the order ID returned from the payment link generation.

$refundOrder = $satim->refund($orderId);

$refundOrder->getResponse();

Payment Status

To retrieve the payment status, you can use the status method with the order ID returned from the payment link generation.

$orderStatus = $satim->status($orderId);

$orderStatus->getResponse();

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contribution

We welcome all contributions! Please follow these guidelines:

Document any changes in behavior — ensure README.md updated accordingly.
Write tests to cover any new functionality.
Please ensure that your pull request passes all tests.

Issues & Suggesting Features

If you encounter any issues or have ideas for new features, please open an issue.

We appreciate your feedback and contributions to help improve this package.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Extra Notes

Satim.dz system operates using the robust banking technologies provided by BPC Group.

Note that many functions in BPC Payment System are restricted for public use by Satim.dz

the official BPC Payment Documentation.

Similar Packages

The following packages provide similar functionality by interacting with Satim through third-party services, rather than directly integrating with Satim:

Chargily
Slick Pay
ALPAY

These packages may be useful depending on your use case. If you’ve developed a package that interacts with Satim via a third-party, feel free to submit a pull request to add it here.

Credits

⭐ Support

If you find this package helpful, please consider giving it a ⭐ on GitHub! Your support encourages us to keep improving the project. Thank you!

License

The MIT License (MIT). Please see License File for more information.

Disclaimer

This package is not officially affiliated with or endorsed by Satim.dz or any other third-party. The name, logo, and trademarks are the property of their respective owners.

piteurstudio / satim-php

Maintainers

Details