README

Table of Contents

• Features
• Installation
• Configuration
• Usage
• Sandbox Mode
• Testing
• License

SofizPay Laravel

A clean, fluent Laravel wrapper for the SofizPay API — CIB card payments and prepaid service operations (phone recharge, internet recharge, game top-ups, and bill payments) for Algerian merchants, with strongly-typed DTOs, response objects, and built-in sandbox mocking for service operations.

Features

• 💳 CIB Transactions — create and check the status of card payment transactions
• 📱 Service Operations — phone recharge, internet recharge, game recharge, and bill payments (Sonelgaz, ADE, Algérie Télécom)
• 🧾 Typed DTOs & Responses — no more digging through raw arrays; every request and response is a typed object
• 🧪 Built-in Sandbox Mode — Since SofizPay does not provide a sandbox environment for service operations, the package automatically fakes service requests in sandbox mode, allowing you to develop and test locally without making real API calls.- 🧩 Container-bound singleton + Facade — resolve via dependency injection or SofizPay:: facade calls
• ⚙️ Simple configuration — a single config file driven by environment variables
• 🚨 Predictable, informative error handling — every failed request throws a SofizPayRequestException carrying the underlying HTTP response

Requirements

• PHP ^8.1
• Laravel 10, 11, 12 or 13 (illuminate/support, illuminate/http)

Installation

Install the package via Composer:

composer require oussamamadjmaa/sofizpay-laravel

The service provider and facade are auto-discovered. Optionally publish the config file:

php artisan vendor:publish --provider="OussamaMadjmaa\SofizPay\SofizPayServiceProvider" --tag="config"

Configuration

Add the following to your .env file:

SOFIZPAY_ACCOUNT_ID=your_account_id
SOFIZPAY_ENCRYPTED_SK=your_encrypted_secret_key
SOFIZPAY_SANDBOX=true

Note: Set SOFIZPAY_SANDBOX=false in production to send real requests to the SofizPay API.

Usage

You can resolve SofizPay three ways — pick whichever fits your codebase:

use OussamaMadjmaa\SofizPay\SofizPay;
use OussamaMadjmaa\SofizPay\Facades\SofizPay as SofizPayFacade;

// 1. Instantiate directly (reads config automatically)
$sofizpay = new SofizPay();

// 2. Resolve the bound singleton from the container
$sofizpay = app(SofizPay::class);

// 3. Use the facade
SofizPayFacade::cibTransaction()->make($dto);

The rest of the examples below use the $sofizpay variable interchangeably with any of the three.

CIB Transactions

Create a transaction

use OussamaMadjmaa\SofizPay\DTOs\MakeCIBTransactionDTO;

$dto = new MakeCIBTransactionDTO(
    amount: 2500,
    fullName: 'Oussama Madjmaa',
    phone: '0555123456',
    email: 'amine@example.com',
    returnUrl: 'https://your-app.test/payments/callback',
    memo: 'Order #1042',
);

$response = $sofizpay->cibTransaction()->make($dto);

$response->success;          // bool
$response->transactionId;    // string
$response->cibTransactionId; // string
$response->paymentUrl;       // string — redirect the customer here
$response->status;           // string

Check a transaction's status

$status = $sofizpay->cibTransaction()->check($response->transactionId);

$status->isPaid();      // bool
$status->isPending();   // bool
$status->isFailed();    // bool
$status->isCancelled(); // bool

$status->orderNumber,
$status->orderStatus,
$status->errorCode,
$status->errorMessage,
$status->actionCodeDescription,
$status->respCodeDesc,
$status->respCode,
$status->destinationAccount,
$status->amount

Service Operations

Service operations share a common perform() flow. Convenience methods are provided for each operation type, each accepting a typed DTO.

Phone recharge

The operator is inferred automatically from the phone number prefix (05 → Ooredoo, 06 → Mobilis, 07 → Djezzy).

use OussamaMadjmaa\SofizPay\DTOs\PhoneRechargeDTO;

$dto = new PhoneRechargeDTO(
    phone: '0555123456',
    amount: 500,
    offer: 'prepaid',
);

$response = $sofizpay->serviceOperation()->performPhoneRecharge($dto);

Internet recharge

use OussamaMadjmaa\SofizPay\DTOs\InternetRechargeDTO;

$dto = new InternetRechargeDTO(
    phone: '021123456',
    amount: 2000,
    // operator defaults to 'idoom'
    // offer is inferred (ADSL vs 4G) from the phone number length if omitted
);

$response = $sofizpay->serviceOperation()->performInternetRecharge($dto);

Bill payment

use OussamaMadjmaa\SofizPay\DTOs\BillPaymentDTO;
use OussamaMadjmaa\SofizPay\Enums\BillPaymentOperator;

$dto = new BillPaymentDTO(
    amount: 3200,
    operator: BillPaymentOperator::SONELGAZ,
    bill: '123456789012',
    customerId: '00458712',
    ebb: '151541'
);

$response = $sofizpay->serviceOperation()->performBillPayment($dto);

Supported bill operators: BillPaymentOperator::ADE, BillPaymentOperator::SONELGAZ, BillPaymentOperator::ALGERIE_TELECOM.

Game recharge

use OussamaMadjmaa\SofizPay\DTOs\GameRechargeDTO;
use OussamaMadjmaa\SofizPay\Enums\GameRechargeOperator;

$dto = new GameRechargeDTO(
    amount: 1000,
    operator: GameRechargeOperator::FREEFIRE,
    playerId: 'player-id-1234',
    offer: '110'
);

$response = $sofizpay->serviceOperation()->performGameRecharge($dto);

Supported game operators: GameRechargeOperator::FREEFIRE, GameRechargeOperator::PUBG.

Every perform* call returns a PerformServiceOperationResponse:

$response->status;            // string
$response->message;           // string
$response->operationId;       // string
$response->transactionId;     // string
$response->transactionStatus; // string

Operation details

$details = $sofizpay->serviceOperation()->details($response->operationId);

$details->status;                 // string
$details->amount;                 // float
$details->blockchainTransactions; // array
$details->transactionLogs;        // array

Operation history

$history = $sofizpay->serviceOperation()->history(limit: 20, offset: 0);

$history->operations;             // ServiceOperationDetailsResponse[]
$history->pagination->totalCount; // int
$history->pagination->limit;    // int
$history->pagination->offset;    // int
$history->pagination->hasMore;    // bool

Error Handling

Any non-successful response from the SofizPay API throws a SofizPayRequestException, which carries the underlying HTTP response so you can inspect the status code and raw JSON body:

use OussamaMadjmaa\SofizPay\Exceptions\SofizPayRequestException;

try {
    $response = $sofizpay->serviceOperation()->performPhoneRecharge($dto);
} catch (SofizPayRequestException $e) {
    report($e);

    $e->getMessage();      // human-readable message
    $e->response?->status(); // e.g. 422
    $e->context();          // the decoded JSON body, e.g. ['message' => '...']
    $e->body();             // the original response body
    $e->getResponse()       // full Http response
}

Sandbox Mode

When SOFIZPAY_SANDBOX is true (the default), cibTransaction()->make(), cibTransaction()->check() will use sandbox api endpoint, and all serviceOperation() calls — is faked locally via Http::fake(), returning realistic sample payloads. This lets you build and test your integration end-to-end without a live account or network calls.

• serviceOperation()->details('INVALID_OPERATION_ID') simulates a 404 "not found" response.
• All other sandbox responses simulate success.

Switch to SOFIZPAY_SANDBOX=false to hit the real SofizPay endpoints.

Testing tip: if you want to override a sandboxed endpoint's response in your own tests (e.g. to assert your error-handling code), resolve the endpoint instance (e.g. $cib = $sofizpay->cibTransaction();) before calling Http::fake() with your override. Endpoint constructors register their own sandbox stubs, and the most recently registered Http::fake() stub wins — so faking after resolving the endpoint guarantees your override takes priority.

Testing

The package ships with a Pest test suite built on Orchestra Testbench, covering DTO serialization/inference logic, both endpoint classes, error handling, and the facade/singleton binding:

composer test

Static analysis via PHPStan:

composer analyse

License

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

Author

Oussama Madjmaa oussama@madjmaa.com