README

A Core PHP package for integrating with the CGrate payment service to process mobile money transactions in Zambia.

Introduction
Requirements
Installation
Configuration
Usage
Data Transfer Objects
Response Codes
Changelog
Credits
License

Introduction

CGrate (543 Konse Konse) is a payment service provider based in Zambia that facilitates mobile money transactions. This Core PHP package allows businesses to:

Process payments from mobile money accounts
Check account balances in real-time
Verify transaction status
Reverse/refund payments when necessary

The service operates via a SOAP API that requires WS-Security authentication. CGrate is widely used for integrating with local payment systems in Zambia, making it easier for businesses to accept mobile payments from customers.

For more information about CGrate payment service, visit their official website or contact their support team at support@cgrate.co.zm.

Official Documentation

For detailed information on the CGrate SOAP API, including setup instructions, request formats, and response codes, please refer to the official EVDSpec 2024.pdf document. This comprehensive guide provides all the technical specifications required for integrating with the CGrate service.

Requirements

PHP 8.2 or higher
PHP SOAP extension

Installation

composer require shubhamc4/cgrate-php

Configuration

$config = [
    'username' => 'your-username',  // Required
    'password' => 'your-password',  // Required
    'endpoint' => 'https://543.cgrate.co.zm/Konik/KonikWs?wsdl',  // Production endpoint
    'testEndpoint' => 'http://test.543.cgrate.co.zm:55555/Konik/KonikWs?wsdl',  // Test endpoint
    'testMode' => false,  // Set to true for test environment
    'options' => [  // SOAP client options
        'soap_version' => SOAP_1_1,
        'connection_timeout' => 30,
        'keep_alive' => false,
        'cache_wsdl' => WSDL_CACHE_NONE,
        'exceptions' => true,
        'trace' => false,  // Set to true for test environment
    ],
];

$client = new \CGrate\Php\Services\CGrateService($config);

Alternatively, you can use the config helper:

use CGrate\Php\Config\CGrateConfig;
use CGrate\Php\Services\CGrateService;

// Create config with username, password and test mode (optional)
$config = CGrateConfig::create(
    username: 'your-username',
    password: 'your-password',
    testMode: true
);
$client = new CGrateService($config);

Available Methods

Method	Description
`getAccountBalance()`	Get the account balance
`processCustomerPayment(PaymentRequestDTO $payment)`	Process a new customer payment
`queryTransactionStatus(string $transactionReference)`	Check the status of a payment
`reverseCustomerPayment(string $paymentReference)`	Reverse a customer payment
`generateTransactionReference(string $prefix = 'CG')`	Generate a unique transaction reference

Usage

Check Account Balance

try {
    $response = $client->getAccountBalance();

    if ($response->isSuccessful()) {
        echo "Balance: " . $response->displayBalance();
    } else {
        echo "Error: " . $response->responseMessage;
    }
} catch (\CGrate\Php\Exceptions\CGrateException $e) {
    echo "Exception: " . $e->getMessage();
}

Process Customer Payment

try {
    $payment = new \CGrate\Php\DTOs\PaymentRequestDTO(
        10.50,  // Amount
        '260970000000',  // Customer mobile number
        'PAYMENT-' . time()  // Unique payment reference
    );

    $response = $client->processCustomerPayment($payment);

    if ($response->isSuccessful()) {
        echo "Payment ID: " . $response->paymentID;
    } else {
        echo "Payment failed: " . $response->responseMessage;
    }
} catch (\CGrate\Php\Exceptions\CGrateException $e) {
    echo "Exception: " . $e->getMessage();
}

Query Transaction Status

try {
    $response = $client->queryTransactionStatus('YOUR-TRANSACTION-REFERENCE');

    if ($response->isSuccessful()) {
        echo "Transaction status: " . $response->responseMessage;
    } else {
        echo "Query failed: " . $response->responseMessage;
    }
} catch (\CGrate\Php\Exceptions\CGrateException $e) {
    echo "Exception: " . $e->getMessage();
}

Reverse Customer Payment

try {
    $response = $client->reverseCustomerPayment('YOUR-PAYMENT-REFERENCE');

    if ($response->isSuccessful()) {
        echo "Payment reversed successfully";
    } else {
        echo "Reversal failed: " . $response->responseMessage;
    }
} catch (\CGrate\Php\Exceptions\CGrateException $e) {
    echo "Exception: " . $e->getMessage();
}

Generate Transaction Reference

// Generate a reference with the default prefix 'CG'
$reference = \CGrate\Php\Services\CGrateService::generateTransactionReference();
// Result: CG-1714504562-a1b2c3d4e5f6

// Generate a reference with a custom prefix
$reference = \CGrate\Php\Services\CGrateService::generateTransactionReference('ORDER');
// Result: ORDER-1714504562-a1b2c3d4e5f6

Data Transfer Objects

The package uses read-only DTOs to handle API requests and responses:

Request DTOs

PaymentRequestDTO: Contains payment request data (transactionAmount, customerMobile, paymentReference)

Response DTOs

BalanceResponseDTO: Contains account balance information
PaymentResponseDTO: Contains payment response information
ReversePaymentResponseDTO: Contains payment reversal response information

Response Codes

The package includes a comprehensive ResponseCode enum that provides all possible response codes from the CGrate API along with their descriptions:

use CGrate\Php\Enums\ResponseCode;

// Check if a response matches a specific code
if ($response->responseCode->is(ResponseCode::SUCCESS)) {
    // Handle successful response
}

// Get the description for any response code
$description = ResponseCode::descriptionFromValue(0); // "Success"

Changelog

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

Credits

Shubham Chaudhary

License

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

shubhamc4 / cgrate-php

Maintainers

Details