kra-connect/php-sdk

Official PHP SDK for KRA GavaConnect API - Tax compliance and verification for Kenya

0.1.2 2025-12-01 17:01 UTC

Requires

• php: ^8.1|^8.2|^8.3
• guzzlehttp/guzzle: ^7.8
• psr/cache: ^3.0
• psr/log: ^3.0
• symfony/cache: ^6.0|^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.40
• illuminate/support: ^10.0|^11.0
• mockery/mockery: ^1.6
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.0|^11.0
• symfony/http-kernel: ^6.0|^7.0
• symfony/var-dumper: ^6.0|^7.0
• vimeo/psalm: ^5.20

Suggests

• illuminate/support: Required for Laravel integration (^10.0|^11.0)
• symfony/http-kernel: Required for Symfony integration (^6.0|^7.0)

MIT

• KRA-Connect Team

• symfony
• php
• laravel
• API-Client
• kenya
• kra
• tax-compliance
• kenya-revenue-authority
• gavaconnect
• pin-verification
• tcc-verification
• eslip-validation
• nil-return

README

Official PHP SDK for Kenya Revenue Authority's GavaConnect API

Repository

• GitHub: BerjisTech/kra-connect-php-sdk
• Packagist: kra-connect/php-sdk
• Documentation: https://docs.kra-connect.dev/php

Features

• ✅ PIN Verification - Verify KRA PIN numbers
• ✅ TCC Verification - Check Tax Compliance Certificates
• ✅ e-Slip Validation - Validate electronic payment slips
• ✅ NIL Returns - File NIL returns programmatically
• ✅ Taxpayer Details - Retrieve taxpayer information
• ✅ Type Safety - Full PHP 8.1+ type declarations
• ✅ PSR Standards - PSR-4 autoloading, PSR-3 logging, PSR-6 caching
• ✅ Laravel Support - Service provider and facades
• ✅ Symfony Support - Bundle integration
• ✅ Retry Logic - Automatic retry with exponential backoff
• ✅ Caching - Response caching for improved performance
• ✅ Rate Limiting - Built-in rate limiting

Requirements

• PHP 8.1 or higher
• Composer
• ext-json

Installation

Via Composer

composer require kra-connect/php-sdk

Laravel

The package will automatically register the service provider. Publish the configuration:

php artisan vendor:publish --provider="KraConnect\Laravel\KraConnectServiceProvider"

Symfony

Register the bundle in config/bundles.php:

return [
    // ...
    KraConnect\Symfony\KraConnectBundle::class => ['all' => true],
];

Quick Start

Basic Usage

<?php

use KraConnect\KraClient;

// Initialize the client
$client = new KraClient('your-api-key');

// Verify a PIN
$result = $client->verifyPin('P051234567A');

if ($result->isValid) {
    echo "Taxpayer: " . $result->taxpayerName . "\n";
    echo "Status: " . $result->status . "\n";
} else {
    echo "Invalid PIN: " . $result->errorMessage . "\n";
}

Using Configuration

<?php

use KraConnect\KraClient;
use KraConnect\Config\KraConfig;

$config = new KraConfig(
    apiKey: 'your-api-key',
    baseUrl: 'https://api.kra.go.ke/gavaconnect/v1',
    timeout: 30,
    retries: 3
);

$client = new KraClient($config);

Laravel Usage

<?php

namespace App\Http\Controllers;

use KraConnect\Facades\KraConnect;

class TaxController extends Controller
{
    public function verifySupplier($pin)
    {
        $result = KraConnect::verifyPin($pin);

        return response()->json($result);
    }
}

Or inject the client:

<?php

use KraConnect\KraClient;

class TaxService
{
    public function __construct(
        private KraClient $kraClient
    ) {}

    public function verify($pin)
    {
        return $this->kraClient->verifyPin($pin);
    }
}

API Reference

KraClient

verifyPin(string $pinNumber): PinVerificationResult

Verify a KRA PIN number.

Parameters:

• $pinNumber - The PIN to verify (format: P + 9 digits + letter)

Returns:

• PinVerificationResult - Verification result with taxpayer details

Throws:

• InvalidPinFormatException - If PIN format is invalid
• ApiAuthenticationException - If API key is invalid
• ApiTimeoutException - If request times out
• RateLimitExceededException - If rate limit is exceeded

Example:

$result = $client->verifyPin('P051234567A');
echo $result->taxpayerName;

verifyTcc(string $tccNumber): TccVerificationResult

Verify a Tax Compliance Certificate.

Parameters:

• $tccNumber - The TCC number to verify

Returns:

• TccVerificationResult - TCC verification result

Example:

$result = $client->verifyTcc('TCC123456');
echo "Valid until: " . $result->expiryDate->format('Y-m-d');

validateEslip(string $slipNumber): EslipValidationResult

Validate an electronic payment slip.

fileNilReturn(string $pinNumber, string $period, string $obligationId): NilReturnResult

File a NIL return for a taxpayer.

Example:

$result = $client->fileNilReturn(
    pinNumber: 'P051234567A',
    period: '202401',
    obligationId: 'OBL123456'
);

getTaxpayerDetails(string $pinNumber): TaxpayerDetails

Retrieve detailed taxpayer information.

Configuration

$config = new KraConfig(
    apiKey: 'your-api-key',
    baseUrl: 'https://api.kra.go.ke/gavaconnect/v1',
    timeout: 30,
    retries: 3,
    cacheEnabled: true,
    cacheTtl: 3600,
    rateLimitMaxRequests: 100,
    rateLimitWindowSeconds: 60
);

Error Handling

<?php

use KraConnect\KraClient;
use KraConnect\Exceptions\{
    InvalidPinFormatException,
    ApiAuthenticationException,
    ApiTimeoutException,
    RateLimitExceededException,
    ApiException
};

try {
    $result = $client->verifyPin('P051234567A');
} catch (InvalidPinFormatException $e) {
    echo "Invalid PIN format: " . $e->getMessage();
} catch (ApiAuthenticationException $e) {
    echo "Authentication failed: " . $e->getMessage();
} catch (ApiTimeoutException $e) {
    echo "Request timed out: " . $e->getMessage();
} catch (RateLimitExceededException $e) {
    echo "Rate limit exceeded. Retry after: " . $e->getRetryAfter() . " seconds";
    sleep($e->getRetryAfter());
    // Retry
} catch (ApiException $e) {
    echo "API error: " . $e->getMessage();
    echo "Status code: " . $e->getStatusCode();
}

Laravel Configuration

After publishing, edit config/kra-connect.php:

return [
    'api_key' => env('KRA_API_KEY'),
    'base_url' => env('KRA_API_BASE_URL', 'https://api.kra.go.ke/gavaconnect/v1'),
    'timeout' => env('KRA_TIMEOUT', 30),
    'retries' => env('KRA_MAX_RETRIES', 3),
    'cache' => [
        'enabled' => env('KRA_CACHE_ENABLED', true),
        'ttl' => env('KRA_CACHE_TTL', 3600),
        'store' => env('KRA_CACHE_STORE', 'redis'),
    ],
    'rate_limit' => [
        'enabled' => env('KRA_RATE_LIMIT_ENABLED', true),
        'max_requests' => env('KRA_RATE_LIMIT_MAX_REQUESTS', 100),
        'window_seconds' => env('KRA_RATE_LIMIT_WINDOW_SECONDS', 60),
    ],
];

Add to .env:

KRA_API_KEY=your_api_key_here
KRA_API_BASE_URL=https://api.kra.go.ke/gavaconnect/v1
KRA_TIMEOUT=30
KRA_MAX_RETRIES=3
KRA_CACHE_ENABLED=true
KRA_CACHE_TTL=3600

Advanced Usage

Batch Verification

$pins = ['P051234567A', 'P051234567B', 'P051234567C'];
$results = $client->verifyPinsBatch($pins);

foreach ($results as $result) {
    echo "{$result->pinNumber}: " . ($result->isValid ? '✓' : '✗') . "\n";
}

Custom HTTP Client

use GuzzleHttp\Client;

$httpClient = new Client([
    'timeout' => 60,
    'verify' => true,
]);

$client = new KraClient('your-api-key', $httpClient);

Custom Cache

use Symfony\Component\Cache\Adapter\RedisAdapter;

$cache = new RedisAdapter(
    RedisAdapter::createConnection('redis://localhost')
);

$config = new KraConfig(
    apiKey: 'your-api-key',
    cache: $cache
);

$client = new KraClient($config);

Testing

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Run PHPStan
composer phpstan

# Fix code style
composer cs-fix

# Check code style
composer cs-check

Examples

See the examples directory for more usage examples:

• Basic PIN Verification
• Batch Processing
• Error Handling
• Laravel Integration

Development

Setup

# Clone the repository
git clone https://github.com/your-org/kra-connect.git
cd kra-connect/packages/php-sdk

# Install dependencies
composer install

# Run tests
composer test

Code Style

This package follows PSR-12 coding standards. Use PHP CS Fixer:

composer cs-fix

Static Analysis

Run PHPStan for static analysis:

composer phpstan

Publishing

Publishing to Packagist

# Update version in composer.json
# Update CHANGELOG.md

# Tag the release
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

# Packagist will automatically detect the new tag
# Or manually update on https://packagist.org/packages/kra-connect/php-sdk

GitHub Release

# Create GitHub release
gh release create v1.0.0 --title "v1.0.0" --notes "Release notes here"

Contributing

Contributions are welcome! Please:

1. Fork the repository: BerjisTech/kra-connect-php-sdk
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

MIT License - see LICENSE for details.

Support

• Documentation: https://docs.kra-connect.dev/php
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for version history.

Disclaimer

This is an independent project and is not officially affiliated with or endorsed by the Kenya Revenue Authority.