Skip to main content

Requirements

Before integrating with the KRA eTIMS OSCU API using any of the Paybill SDKs (PHP, JavaScript, or Python), ensure that all technical, regulatory, and environment requirements below are met.

Failure to meet these requirements will result in authentication errors, rejected payloads, or failed audits.

1. KRA Prerequisites (Mandatory)​

OSCU Registration​

You must be approved by KRA to integrate using the OSCU (Online Sales Control Unit) flow.

  • Your business must be registered on GavaConnect
  • OSCU credentials must be issued by KRA
  • Sandbox credentials are different from production credentials

⚠️ These SDKs are OSCU-only. They will not work with non-OSCU eTIMS integrations.

Required KRA Credentials​

You will receive the following from KRA:

VariableDescription
consumer_keyOAuth client key
consumer_secretOAuth client secret
tinTaxpayer Identification Number
bhfIdBranch ID (default: 01)
dvcSrlNoOSCU device serial number
cmcKeyBranch communication key (issued after initialization)

🔑 Important: cmcKey is obtained dynamically via selectInitOsdcInfo and must be stored securely.

2. Supported Environments​

All SDKs support both sandbox and production environments.

EnvironmentPurpose
SandboxDevelopment & testing
ProductionLive KRA submissions

Sandbox behavior may differ slightly from production (e.g., relaxed serial validation), but payload validation rules are identical.

3. Language-Specific Requirements​

PHP​

  • PHP 8.1+
  • Extensions:
    • curl
    • json
    • openssl
  • Composer (Packagist)
php -v
composer -V

System & Network Requirements​

  • Outbound HTTPS access to:

    • https://sbx.kra.go.ke
    • https://etims-api.kra.go.ke

  • TLS 1.2 or higher

  • Valid system clock (time drift can cause token failures)

⏱️ Time synchronization is critical. OAuth tokens and request timestamps are time-sensitive.

5. Invoice & Date Rules (Critical)​

Invoice Numbering​

  • Must be sequential integers
  • Must be unique per branch (bhfId)
  • Strings are rejected
'invcNo' => 1   // ✅ Correct
'invcNo' => 'INV001' // ❌ Rejected

See Field Validation Rules for more details.

Date & Time Formats​

FieldFormatExample
salesDt, pchsDtYYYYMMDD20260131
cfmDt, stockRlsDtYYYYMMDDHHmmss20260131143022
lastReqDtYYYYMMDDHHmmss20260130143022
  • Future dates are rejected
  • lastReqDt must not be older than 7 days

6. Validation Behavior​

All Paybill SDKs perform local validation before sending requests to KRA:

  • Required fields are enforced
  • Data types are validated
  • KRA-specific constraints are checked early

This reduces failed submissions and simplifies debugging.

7. Security Best Practices​

  • Store credentials outside source code
  • Restrict access to token cache files
  • Rotate production credentials when staff changes
  • Log KRA responses securely (avoid exposing secrets)

Next Steps​