CGrate PHP Package

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

Table of Contents

• Introduction
• Requirements
• Installation
• Configuration
• Usage
  • Check Account Balance
  • Get Available Cash Deposit Issuers
  • Process Customer Payment
  • Query Customer Payment
  • Process Cash Deposit
  • Generate Transaction Reference
  • Get Customer Account Issuer Name
• 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 [email protected].

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 Soap Methods

Method	Description
getAccountBalance()	Get the account balance
getAvailableCashDepositIssuers()	Get Available Cash Deposit Issuers
processCustomerPayment(PaymentRequestDTO $payment)	Process a new customer payment
queryCustomerPayment(string $transactionReference)	Check the status of a customer payment
processCashDeposit(string $paymentReference)	Process Cash Deposit

Available Static Helper Methods

Method	Description
generateTransactionReference(string $prefix = 'CG')	Generate a unique transaction reference
getCustomerIssuerName(string $customerAccount)	Get Customer Account Issuer Name

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();
}

Get Available Cash Deposit Issuers

try {
    $response = $client->getAvailableCashDepositIssuers();
    print_r($response);
} 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 Customer Payment

try {
    $response = $client->queryCustomerPayment('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();
}

Process Cash Deposit

try {
    $customerAccount = '260970000000';  // Customer mobile number
    $cashDeposit = new \CGrate\Php\DTOs\CashDepositRequestDTO(
        10.50,  // Amount
        $customerAccount,
        \CGrate\Php\Services\CGrateService::getCustomerIssuerName($customerAccount),
        'CD-' . time()  // Unique cash deposit reference
    );

    $response = $client->processCashDeposit($cashDeposit);

    if ($response->isSuccessful()) {
        echo "Depositor reference: " . $response->depositorReference;
    } else {
        echo "Cash deposit 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

Get Customer Account Issuer Name

// Get issuer name using the the customer account

$issuerName = \CGrate\Php\Services\CGrateService::getCustomerIssuerName('26097XXXXXXX');
// Result: Airtel

$issuerName = \CGrate\Php\Services\CGrateService::getCustomerIssuerName('26076XXXXXXX');
// Result: MTN

$issuerName = \CGrate\Php\Services\CGrateService::getCustomerIssuerName('26095XXXXXXX');
// Result: Zamtel

$issuerName = \CGrate\Php\Services\CGrateService::getCustomerIssuerName('26065XXXXXXX');
// Result: Unknown Issuer

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)
• CashDepositRequestDTO: Contains cash deposit request data (transactionAmount, customerAccount, issuerName, depositorReference)

Response DTOs

• BalanceResponseDTO: Contains account balance information
• PaymentResponseDTO: Contains payment response information
• CashDepositResponseDTO: Contains cash deposit 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.