serenity_technologies/ecobank-unified-api

Laravel wrapper for Ecobank Unified API

1.0.0 2025-10-14 23:29 UTC

Requires

• php: ^8.1
• ext-json: *
• illuminate/http: ^8.0|^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^6.0|^7.0|^8.0|^9.0
• phpunit/phpunit: ^9.0|^10.0

MIT

• Kwadwo Kyeremeh Tuffour

• api
• wrapper
• laravel
• unified
• serenity
• ecobank

README

This package provides a Laravel wrapper for the Ecobank Unified API, allowing you to easily integrate Ecobank's financial services into your Laravel applications.

Installation

You can install the package via composer:

composer require serenity_technologies/ecobank-unified-api

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=ecobank-config

This will create a config/ecobank.php file. You should modify this file to match your Ecobank credentials:

return [
    'base_url' => env('ECOBANK_BASE_URL', 'https://developer.ecobank.com'),
    'sandbox' => env('ECOBANK_SANDBOX', true),
    'credentials' => [
        'user_id' => env('ECOBANK_USER_ID'),
        'password' => env('ECOBANK_PASSWORD'),
        'lab_key' => env('ECOBANK_LAB_KEY'),
        'client_id' => env('ECOBANK_CLIENT_ID'),
    ],
    'affiliate_code' => env('ECOBANK_AFFILIATE_CODE', 'EGH'),
    'request_token' => env('ECOBANK_REQUEST_TOKEN', '/4mZF42iofzo7BDu0YtbwY6swLwk46Z91xItybhYwQGFpaZNOpsznL/9fca5LkeV'),
    'source_code' => env('ECOBANK_SOURCE_CODE', 'ECOBANK_QR_API'),
    'source_channel_id' => env('ECOBANK_SOURCE_CHANNEL_ID', 'KANZAN'),
    'defaults' => [
        'currency' => env('ECOBANK_DEFAULT_CURRENCY', 'GHS'),
        'country' => env('ECOBANK_DEFAULT_COUNTRY', 'GH'),
    ],
    'timeout' => env('ECOBANK_TIMEOUT', 30),
];

Add your Ecobank credentials to your .env file:

ECOBANK_USER_ID=your_user_id
ECOBANK_PASSWORD=your_password
ECOBANK_LAB_KEY=your_lab_key
ECOBANK_CLIENT_ID=your_client_id
ECOBANK_AFFILIATE_CODE=EGH
ECOBANK_BASE_URL=https://developer.ecobank.com
ECOBANK_SANDBOX=true

Usage

Using the Facade

use SerenityTechnologies\Ecobank\UnifiedApi\Facades\UnifiedApi;

// Get biller list
$response = UnifiedApi::collections()->getBillerList('REQUEST123');

// Get account balance
$response = UnifiedApi::accounts()->getAccountBalance('REQUEST123', '1234567890', 'Company Name');

// Process card payment
$cardPaymentData = [
    'paymentDetails' => [
        'requestId' => 'REQ123',
        'productCode' => '2310',
        'amount' => '100.00',
        'currency' => 'USD',
        'locale' => 'en_US',
        'orderInfo' => 'Order #123',
        'returnUrl' => 'https://yoursite.com/return'
    ],
    'merchantDetails' => [
        'accessCode' => 'access_code',
        'merchantID' => 'merchant_id',
        'secureSecret' => 'secure_secret'
    ]
];

$response = UnifiedApi::cardPayments()->processPayment($cardPaymentData);

Using the Helper Function

// Get biller list
$response = unifiedapi()->collections()->getBillerList('REQUEST123');

// Get account balance
$response = unifiedapi()->accounts()->getAccountBalance('REQUEST123', '1234567890', 'Company Name');

// Process card payment
$cardPaymentData = [
    'paymentDetails' => [
        'requestId' => 'REQ123',
        'productCode' => '2310',
        'amount' => '100.00',
        'currency' => 'USD',
        'locale' => 'en_US',
        'orderInfo' => 'Order #123',
        'returnUrl' => 'https://yoursite.com/return'
    ],
    'merchantDetails' => [
        'accessCode' => 'access_code',
        'merchantID' => 'merchant_id',
        'secureSecret' => 'secure_secret'
    ]
];

$response = unifiedapi()->cardPayments()->processPayment($cardPaymentData);

Response Handling

All API responses are returned as response objects with helpful methods for accessing data:

// Get biller list
$response = unifiedapi()->collections()->getBillerList('REQUEST123');

if ($response->isSuccess()) {
    $billerList = $response->getBillerList();
    foreach ($billerList as $biller) {
        echo $biller['billerName'];
    }
} else {
    echo "Error: " . $response->getResponseMessage();
}

// Get account balance
$accountResponse = unifiedapi()->accounts()->getAccountBalance('REQUEST123', '1234567890', 'Company Name');

if ($accountResponse->isSuccess()) {
    echo "Available Balance: " . $accountResponse->getAvailableBalance();
    echo "Account Name: " . $accountResponse->getAccountName();
    echo "Account Number: " . $accountResponse->getAccountNumber();
} else {
    echo "Error: " . $accountResponse->getResponseMessage();
}

// Process card payment
$cardPaymentData = [
    'paymentDetails' => [
        'requestId' => 'REQ123',
        'productCode' => '2310',
        'amount' => '100.00',
        'currency' => 'USD',
        'locale' => 'en_US',
        'orderInfo' => 'Order #123',
        'returnUrl' => 'https://yoursite.com/return'
    ],
    'merchantDetails' => [
        'accessCode' => 'access_code',
        'merchantID' => 'merchant_id',
        'secureSecret' => 'secure_secret'
    ]
];

$cardResponse = unifiedapi()->cardPayments()->processPayment($cardPaymentData);

if ($cardResponse->isSuccess()) {
    $redirectUrl = $cardResponse->getPaymentRedirectUrl();
    $timestamp = $cardResponse->getPaymentTimestamp();
    
    // Redirect user to the payment page
    header("Location: " . $redirectUrl);
    exit;
} else {
    echo "Error: " . $cardResponse->getResponseMessage();
}

Dynamic Method Access

All response objects now support dynamic method access to response data. This allows you to access response fields as methods:

$response = unifiedapi()->accounts()->getAccountBalance('REQUEST123', '1234567890', 'Company Name');

// Traditional access
$responseCode = $response->getResponseCode();
$responseMessage = $response->getResponseMessage();

// Dynamic method access (new feature)
$responseCode = $response->response_code();
$responseMessage = $response->response_message();
$responseTimestamp = $response->response_timestamp();

// For nested associative arrays, you can chain methods:
$responseContent = $response->response_content();
if ($responseContent) {
    $hostHeaderInfo = $responseContent->hostHeaderInfo();
    if ($hostHeaderInfo) {
        $sourceCode = $hostHeaderInfo->sourceCode();
        $affiliateCode = $hostHeaderInfo->affiliateCode();
    }
}

This feature makes it easier to access deeply nested response data without having to manually traverse arrays. It also provides better IDE support with autocompletion when using modern IDEs.

Request Validation

All service methods automatically validate required fields before making API calls. If any required fields are missing, an EcobankException will be thrown with a descriptive error message:

try {
    // This will automatically validate that requestId, accountNo, and companyName are provided
    $response = unifiedapi()->accounts()->getAccountBalance('REQUEST123', '1234567890', 'Company Name');
} catch (EcobankException $e) {
    echo "Validation Error: " . $e->getMessage();
    echo "Error Timestamp: " . $e->getTimestamp(); // New: All exceptions now include a timestamp
}

Available Services

1. Token Service - For generating access tokens
2. Collection Service - For bill payments and collections
3. Remittance Service - For cross-border payments
4. Account Service - For account management
5. Status Service - For checking transaction statuses
6. Payment Service - For various payment types
7. QR Service - For QR code generation and management
8. Card Payment Service - For processing card payments

Response Objects

Each service returns a specific response object with helpful methods:

BaseResponse (Base class for all responses)

• isSuccess() - Check if the request was successful
• getResponseCode() - Get the response code
• getResponseMessage() - Get the response message
• getResponseContent() - Get the response content
• getResponseTimestamp() - Get the response timestamp
• getRawResponse() - Get the raw response array
• toArray() - Convert response to array
• Dynamic method access to any response field (new feature)

CollectionResponse

• getBillerList() - Get list of billers
• getBillerDetails() - Get biller details
• getFormData() - Get form data
• getBillerProductInfo() - Get biller product information
• getValidationData() - Get validation data

RemittanceResponse

• getInstitutionList() - Get list of institutions
• getAccountDetails() - Get account details
• getRates() - Get exchange rates
• getTransactionDetails() - Get transaction details

AccountResponse

• getAccountBalance() - Get account balance information
• getAccountDetails() - Get account details
• getAccountName() - Get account name
• getAvailableBalance() - Get available balance
• getCurrentBalance() - Get current balance
• getAccountNumber() - Get account number
• getAccountStatus() - Get account status
• getCurrency() - Get account currency
• getStatement() - Get account statement
• getAccountCreationDetails() - Get account creation details
• getAccountBalanceData() - Get structured account balance data model
• getAccountInquiryData() - Get structured account inquiry data model
• getThirdPartyAccountInquiryData() - Get structured third party account inquiry data model
• getStatementTransactions() - Get array of structured statement transaction data models

StatusResponse

• getTransactionStatus() - Get transaction status
• getEtokenStatus() - Get etoken status
• isTransactionSuccessful() - Check if transaction was successful
• getTransactionStatusCode() - Get transaction status code
• getTransactionStatusReason() - Get transaction status reason

PaymentResponse

• getPaymentDetails() - Get payment details
• getTransactionReference() - Get transaction reference
• isPaymentSuccessful() - Check if payment was successful

QrResponse

• getQrCode() - Get QR code base64 string
• getTerminalId() - Get terminal ID
• getMerchantCode() - Get merchant code
• getSecretKey() - Get secret key
• getDynamicQr() - Get dynamic QR string
• getDynamicQrBase64() - Get dynamic QR base64 string
• getMccList() - Get MCC list

CardPaymentResponse

• getPaymentRedirectUrl() - Get payment redirect URL
• getPaymentTimestamp() - Get payment timestamp
• getPaymentDetails() - Get payment details

TokenResponse

• getToken() - Get access token
• getUsername() - Get username
• isTokenValid() - Check if token is valid

Data Models

The package now includes structured data models for easier data access:

Account Data Models

• AccountBalanceData - Structured data model for account balance responses
• AccountInquiryData - Structured data model for account inquiry responses
• ThirdPartyAccountInquiryData - Structured data model for third party account inquiry responses
• StatementTransaction - Structured data model for individual statement transactions

Bills Payment Data Models

• BillFormData - Structured data model for bill form data
• Biller - Structured data model for biller information
• BillerDetails - Structured data model for biller details
• BillerProductInfo - Structured data model for biller product information
• FormDataValue - Structured data model for form data values

Host Header Info Data Model

• HostHeaderInfo - Structured data model for host header information

Available Methods

Token Service

• generateToken() - Generate access token

Collection Service

• getBillerList($requestId) - Get list of billers
• getBillerDetails($requestId, $billerCode) - Get biller details
• validateBiller($data) - Validate a biller
• postBillPayment($paymentData) - Post a bill payment

Remittance Service

• getInstitutionList($requestId) - Get list of institutions
• nameEnquiry($requestId, $accountNo, $destinationCountry) - Perform name enquiry
• getRates($requestId) - Get exchange rates
• transactionEnquiry($requestId, $transactionReference) - Enquire about a transaction
• crossBorderPayment($paymentData) - Make cross-border payment

Account Service

• getAccountBalance($requestId, $accountNo, $companyName) - Get account balance
• accountEnquiry($requestId, $accountNo, $companyName) - Account enquiry
• accountEnquiryThirdParty($requestId, $accountNo, $destinationBankCode, $companyName) - Third party account enquiry
• generateStatement($data) - Generate account statement
• createExpressAccount($data) - Create express account
• createAccount($data) - Create internal account

Status Service

• checkTransactionStatus($requestId) - Check transaction status
• checkEtokenStatus($requestId) - Check etoken status

Payment Service

• makePayment($paymentData) - Make various types of payments

QR Service

• getMcc($requestId) - Get Merchant Category Code
• createQr($data) - Create QR code
• generateDynamicQr($data) - Generate dynamic QR payment
• addQrTerminal($data) - Add QR terminal

Card Payment Service

• processPayment($paymentData) - Process card payment
• createPayment($requestId, $productCode, $amount, $currency, $locale, $orderInfo, $returnUrl, $accessCode, $merchantID, $secureSecret) - Create card payment with individual parameters

Response Structure

All responses follow the Ecobank API structure:

[
    'response_code' => 200,           // HTTP response code or Ecobank status code
    'response_message' => 'success',  // Response message
    'response_content' => [...],      // Actual response data
    'response_timestamp' => '...'     // Timestamp of response
]

Exception Handling

The package now includes enhanced exception handling with timestamp information:

try {
    $response = unifiedapi()->accounts()->getAccountBalance('REQUEST123', '1234567890', 'Company Name');
} catch (EcobankException $e) {
    // All exceptions now include a timestamp in the message
    // Format: [YYYYMMDDHHmmss] Error message
    echo "Error: " . $e->getMessage();
    
    // You can also access the timestamp separately
    echo "Timestamp: " . $e->getTimestamp();
}

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

License

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