README

Welcome to the official HimoSoft Payments SDK for PHP. This library allows PHP developers to quickly and securely integrate HimoSoft's payment gateway into any modern PHP application—fully compatible with Laravel, Symfony, Yii, WordPress, or standalone PHP scripts.

⚡ Key Features

🛡️ Secure HMAC-SHA256 Signatures: Sealing payload strings using exact hash matches.
🕒 Replay Attack Protection: Embedded timestamp validity checks on every request.
📋 Metadata Schema Verification: Ensures all required merchant tracking attributes are validated client-side.
🧩 Zero-Dependency Native cURL: Runs on standard PHP curl extension (compatible with PHP >= 7.0), avoiding version conflicts with libraries like Guzzle.
🌐 Mathematical URL Calibration: Uses JSON_UNESCAPED_SLASHES to align signature encodings perfectly with the server-side Python parser.

📦 Installation

Composer Installation (Recommended)

You can include this package in your project via Composer. Add this to your composer.json:

"repositories": [
    {
        "type": "path",
        "url": "./integration-package/php"
    }
],
"require": {
    "himosoft/payments": "^1.0"
}

Then run:

composer install

Manual Autoload Fallback (No-Composer / WordPress)

If you are working in an environment without Composer, you can manually load the files by copying the src/ folder to your project and registering a simple autoloader:

spl_autoload_register(function ($class) {
    $prefix = 'HimoSoft\\Payments\\';
    $base_dir = __DIR__ . '/src/'; // Point this to your copied src/ directory
    
    $len = strlen($prefix);
    if (strncmp($prefix, $class, $len) !== 0) {
        return;
    }
    
    $relative_class = substr($class, $len);
    $file = $base_dir . str_replace('\\', '/', $relative_class) . '.php';
    if (file_exists($file)) {
        require $file;
    }
});

🚀 Quickstart Guides

The PHP SDK supports both Synchronous calls (standard workflows) and Asynchronous Batch calls (for high-speed concurrent processing with zero dependencies).

1. Synchronous Quickstart (Laravel, Symfony, WordPress)

Creating a payment and retrieving its status in a standard PHP blocking request:

use HimoSoft\Payments\HimoSoftPaymentsClient;
use HimoSoft\Payments\Exceptions\HimoSoftException;

$client = new HimoSoftPaymentsClient("your_api_key", "your_api_secret", "https://pay.himosoft.com.bd");

try {
    $payment = $client->createPayment([
        "amount" => "500.00",
        "currency" => "BDT",
        "reference_id" => "INV-99081",
        "description" => "Cloud Hosting Subscription",
        "redirect_url" => "https://yourwebsite.com/success",
        
        // Required Customer Metadata
        "customer_id" => "CUST-44321",
        "customer_email" => "jane.doe@example.com",
        "customer_name" => "Jane Doe",
        
        // Required Product Metadata
        "product_name" => "Professional Shared Hosting",
        "product_price" => "500.00",
        "product_quantity" => 1
    ]);
    
    echo "Checkout URL: " . $payment['checkout_url'] . "\n";
} catch (HimoSoftException $e) {
    echo "SDK Error: " . $e->getMessage() . "\n";
}

2. Asynchronous / Concurrent Quickstart (Multi-cURL Execution Pool)

Perfect for checking the status of multiple payments in parallel, reducing latency by up to $N$ times with zero external dependencies:

use HimoSoft\Payments\HimoSoftPaymentsClient;

$client = new HimoSoftPaymentsClient("your_api_key", "your_api_secret", "https://pay.himosoft.com.bd");

// 1. Queue multiple requests asynchronously inside the cURL pool
$client->getPaymentStatusAsync("payment_id_1", function($response) {
    echo "Payment 1 is currently: " . $response['status'] . "\n";
}, function($error) {
    echo "Payment 1 check failed: " . $error->getMessage() . "\n";
});

$client->getPaymentStatusAsync("payment_id_2", function($response) {
    echo "Payment 2 is currently: " . $response['status'] . "\n";
}, function($error) {
    echo "Payment 2 check failed: " . $error->getMessage() . "\n";
});

// 2. Dispatch all queued requests concurrently in a single non-blocking session!
$client->executeAsync();

📖 API Reference Guide

1. Create Payment

$client->createPayment([
    "amount" => "500.00",              // string: Payment volume (e.g. "500.00")
    "currency" => "BDT",            // string: "BDT" or "USD"
    "reference_id" => "INV-99",     // string: Your unique reference ID
    "description" => "Plan Buy",     // string: Description
    "redirect_url" => "https://...", // string: Success redirect URL
    
    // Required Customer Metadata
    "customer_id" => "CUST-100",
    "customer_email" => "mail@example.com",
    "customer_name" => "Customer Name",
    
    // Required Product Metadata
    "product_name" => "Product Name",
    "product_price" => "500.00",
    "product_quantity" => 1,

    // Optional parameters (Populated with system defaults if left empty)
    "idempotency_key" => "...",     // string: Will auto-generate a secure UUID4 if empty
    "customer_phone" => "...",      // string: Default: "01316100897"
    "customer_address" => "...",    // string: Default: "Dhaka, Bangladesh"
    "product_image" => "...",       // string: Default: "https://himosoft.com.bd"
    "product_url" => "...",         // string: Default: "https://himosoft.com.bd"
    "custom_metadata" => []         // array: Associative array of custom tags to store on the invoice
]);

2. Get Payment Status (Reconcile)

$client->getPaymentStatus($paymentId);

3. Quick DB Status Only Check

$client->verifyPayment($paymentId);

4. Force Live Gateway Reconciliation Check

$client->recheckPayment($paymentId);

5. Cancel Pending Session

$client->cancelPayment($paymentId);

6. Verify Webhook Signature (Callback protection)

use HimoSoft\Payments\HimoSoftPaymentsClient;

// Read headers and payload from request
$payload = json_decode(file_get_contents('php://input'), true);
$signatureHeader = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$timestampHeader = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';

// Verify incoming webhook signature to protect against tampering
$isValid = HimoSoftPaymentsClient::verifyWebhookSignature(
    $payload,
    $signatureHeader,
    $timestampHeader,
    "your_merchant_secret"
);

if ($isValid) {
    // Process the webhook event securely
} else {
    // Reject request (401 Unauthorized / tampered)
}

🛡️ Robust Exception Handling

You can catch specific failure states inheriting from HimoSoftException:

use HimoSoft\Payments\Exceptions\HimoSoftException;
use HimoSoft\Payments\Exceptions\HimoSoftAuthException;
use HimoSoft\Payments\Exceptions\HimoSoftValidationException;
use HimoSoft\Payments\Exceptions\HimoSoftApiException;

try {
    $payment = $client->createPayment([...]);
} catch (HimoSoftAuthException $e) {
    // Unauthorized, invalid API key, or bad signature
} catch (HimoSoftValidationException $e) {
    // Missing required fields locally or remote validation errors
} catch (HimoSoftApiException $e) {
    // Server responded with an error (e.g. 400 Bad Request, 429 Throttled)
    echo "API HTTP Code: " . $e->getStatusCode() . "\n";
    print_r($e->getResponseBody());
} catch (HimoSoftException $e) {
    // Base fallback error
}

🔒 Security Best Practices

Environment Variables: Never commit your apiSecret directly in source code repositories. Securely load them using variables (e.g., in Laravel .env file):
```
$apiSecret = env('HIMOSOFT_API_SECRET');
```
Raw JSON Signature Alignment: The HimoSoft SDK utilizes PHP native hash_hmac alongside JSON_UNESCAPED_SLASHES to seal requests. Using raw CURL manually to sign URLs or nested JSON arrays might bypass these constraints and lead to 401 Unauthorized responses. Always prefer the SDK wrapper methods.

himosoft / payments

Maintainers

Package info

Statistics

Security