README

Secure, configurable PHP/Laravel integration with CRDB Bank’s Cybersource payment system.

📚 Table of Contents

• Features
• Requirements
• Installation
• Laravel Usage
• Plain PHP Usage
• API Reference
• Logging
• Sample Request & Response
• License

🧩 Features

• 🔒 Secure form-based Cybersource payment integration
• ✅ Laravel-ready and standalone PHP compatible
• 📦 Includes built-in validation and form signing
• 🧾 Auto-logs incoming and outgoing payloads

⚙️ Requirements

• PHP 7.4+
• Laravel 8 or later (optional)
• OpenSSL, cURL enabled
• Web access to Cybersource endpoint

⬇️ Installation

Option 1: Composer (recommended for Laravel projects)

composer require mwalupani/payment:dev-main --prefer-stable

or 

composer require mwalupani/payment



⚙️ Laravel Configuration
1. Add Environment Variables to .env:

    CYBERSOURCE_PAYMENT_ACCESS_KEY=your_access_key
    CYBERSOURCE_PAYMENT_PROFILE_ID=your_profile_id
    CYBERSOURCE_PAYMENT_SECRET_KEY=your_secret_key
    CYBERSOURCE_PAYMENT_URL=https://testsecureacceptance.cybersource.com/pay
    CYBERSOURCE_PAYMENT_LOCALE=en-us

    🛡️ Use the live URL only in production.

2. Example Controller Usage

    use Illuminate\Http\Request;
    use Crdb\Payment\CrdbController;

    class PaymentController extends Controller
    {
        protected CrdbController $crdb;

        public function __construct()
        {
            $this->crdb = new CrdbController([
                'access_key' => env('CYBERSOURCE_PAYMENT_ACCESS_KEY'),
                'profile_id' => env('CYBERSOURCE_PAYMENT_PROFILE_ID'),
                'secret_key' => env('CYBERSOURCE_PAYMENT_SECRET_KEY'),
                'locale' => env('CYBERSOURCE_PAYMENT_LOCALE', 'en-us'),
                'url' => env('CYBERSOURCE_PAYMENT_URL'),
            ]);
        }

        public function pay(Request $request)
        {
            try {
                $data = $request->only(['application_reference', 'amount', 'currency', 'is_checked']);

               

                $response = $this->crdb->handle($requestData);

                /*
                * echo json_encode($response);
                exit;
                */
                
                // Example: Just render form if successful
                if ($response['response']['status'] && isset($response['response']['data'][0])) {

                    $encoded  = $response['response']['data'][0];

                    echo $encoded; // Render form directly
                } else {
                    // Error
                    echo json_encode($response);
                }

                exit;

            } catch (\Throwable $e) {
                \Log::error('Payment error: ' . $e->getMessage());
                return response()->json([
                    'code' => 500,
                    'status' => false,
                    'message' => 'Something went wrong!' . $e->getMessage(),
                    'data' => null,
                ]);
            }
        }
    }

3. Define the Route
    use App\Http\Controllers\PaymentController;

    Route::post('/payment/crdb/get_url', [PaymentController::class, 'pay']);

4. Sample JSON Payload to Send
    {
        "application_reference": "ORDER123456",
        "amount": 1000,
        "currency": "TZS",
        "is_checked": true
    }



💻 Standalone PHP Usage PHP Example (index.php)

    <?php

require 'vendor/autoload.php'; // Make sure composer autoload is included

use Crdb\Payment\CrdbController;

// Step 1: Define configuration
$config = [
    'access_key' => 'your_access_key',
    'profile_id' => 'your_profile_id',
    'secret_key' => 'your_secret_key',
    'url' => 'https://testsecureacceptance.cybersource.com/pay', // Use live URL in production
    'locale' => 'en-us'
];

// Step 2: Create CrdbController instance
$crdb = new CrdbController($config);

// Step 3: Get POST data
$requestData = $_POST;

// Optional fallback or test data
if (empty($requestData)) {
    $requestData = [
        'application_reference' => 'ORDER123456',
        'amount' => 5000,
        'currency' => 'TZS',
        'is_checked' => true
    ];
}

// Step 4: Call the payment handler
try {
    $crdb->handle($requestData);
    exit;
} catch (Throwable $e) {
    http_response_code(500);
    header('Content-Type: application/json');
    echo json_encode([
        'response' => [
            'code' => 500,
            'status' => false,
            'message' => 'Error: ' . $e->getMessage(),
            'data' => null,
        ]
    ], JSON_PRETTY_PRINT);
}


    📤 API Reference
        handle(array $data): array

        Pass payment data. Example input:

        [
            'application_reference' => 'INV123',
            'amount' => 2000,
            'currency' => 'TZS',
            'is_checked' => true
        ]


         Returns:

            -  data: HTML form to redirect to Cybersource

            - code: HTTP-like status code (200 success, 100 validation error)
             
            - status: Boolean
             
            - message: Success or error message


🧪 Sample Response (JSON)

    ✅ On Success

        {
            "code": 200,
            "status": true,
            "message": "Success",
            "data": [
                "<form method='POST' action='...'>...</form>"
            ]
        }
      


    ❌ On Validation Error
        {
            "code": 100,
            "status": false,
            "message": "Invalid or missing application_reference",
            "data": []
        }

    📁 Logs

    Payment requests and responses are logged under:

        /logs/CRDB/YYYY/Mon/payment_config.log
    
    You can change the log structure via:

        private string $dir = 'CRDB/';
        private string $path = 'payment_config';

        🔒 Security Tips

            - Never expose secret_key to frontend
            - 
            - Use HTTPS for your routes
            - 
            - Handle Cybersource callback response validation separately


    📌 Notes

        Always validate the callback response from Cybersource on your backend.

        Make sure your secret_key is never exposed on the frontend.

        This package only prepares and signs the form for redirection — it does not handle transaction result callbacks or webhooks.
👦 Need Help?

    If you encounter any challenges or need assistance:

        📨 Email: mwalupani1234@gmail.com

        💬 WhatsApp: +255 757 062 585

        🌐 Website: https://solo.co.tz

    Feel free to reach out — I’ll support you as quickly as possible!

    📝 License

        MIT License – Use freely with attribution.