Use Daraja

Yii2 web app for exercising Safaricom Daraja services from a field-based interface. It wraps the installed josemodi97/yii2-safaricom-daraja component with local service interfaces and user-facing request forms.

Features

• Daraja service menu for STK Push, C2B, B2B/B2C/B2Pochi, transactions, Ratiba, Lipa na Bonga, subscriber checks, pull transactions, and IoT SIM Portal.
• Field-based request forms instead of raw JSON payload editing.
• STK Push password generation on submit from shortcode, passkey, and timestamp.
• Internal STK PartyA and PartyB handling: users only enter the phone number and shortcode.
• .env-driven credentials with .env.example committed and .env ignored.
• Optional endpoint override support for Daraja APIs whose sandbox path differs from the package catalog.

Screenshots

Use the top navigation menu and choose Daraja. The services page lists every supported Daraja API group.

STK Push

Open Daraja -> STK Push. The app hides generated/internal fields and generates the STK password before submitting.

C2B

Business Payments

Transactions

Ratiba

Lipa na Bonga

The page shows the exact Safaricom URL being called, which helps when checking sandbox endpoint availability.

Subscriber Info

Pull Transactions

IoT SIM Portal

Requirements

• PHP 8.2 or later
• Composer
• Yii2 dependencies installed with composer install
• A Safaricom Daraja sandbox or production app

Setup

Install dependencies:

composer install

Create your local environment file:

copy .env.example .env

Then edit .env with your real Daraja credentials. If you are testing unreleased extension changes locally, point this app's Composer repository to the local yii2-safaricom-daraja folder and run composer update josemodi97/yii2-safaricom-daraja. Otherwise, install the package version that includes buildCallbackUrl() before using the callback-enabled forms.

Required STK/Daraja values:

DARAJA_ENVIRONMENT=sandbox
DARAJA_ENV=sandbox
DARAJA_CONSUMER_KEY=your_consumer_key
DARAJA_CONSUMER_SECRET=your_consumer_secret
DARAJA_SHORT_CODE=174379
DARAJA_SHORTCODE=174379
DARAJA_PASSKEY=your_stk_passkey

Optional values:

DARAJA_CALLBACK_BASE_URL=https://your-domain.example
DARAJA_CALLBACK_SECRET=your_callback_secret
DARAJA_TEST_PHONE=254700000000
DARAJA_INITIATOR_NAME=your_initiator_name
DARAJA_INITIATOR_PASSWORD=your_initiator_password
DARAJA_SECURITY_CREDENTIAL=your_encrypted_security_credential
DARAJA_IOT_API_KEY=your_iot_api_key
DARAJA_IOT_MSISDN=254700000000

Start the app:

php -S localhost:8080 -t web

Open:

http://localhost:8080

How To Use

1. Open http://localhost:8080.
2. Click Daraja in the menu.
3. Select a service group and endpoint.
4. Fill in the visible fields.
5. Click Send request.
6. Review the response panel under the form.

For STK Push, use a phone number in 2547XXXXXXXX format. The form hides PartyA, PartyB, and Password because the app derives them before sending the request.

Callback URLs

The app now lets the installed Daraja extension build callback URLs for STK Push, C2B registration, business payments, transactions, Ratiba, and Pull Transactions. In a deployed housing application, the extension can usually derive the base URL from the current Yii web request, so users do not need to type callback URLs into the forms.

Set DARAJA_CALLBACK_BASE_URL when the app runs behind a reverse proxy, when a console or queue process builds the payload, or when you want to force a specific public domain.

localhost cannot receive Safaricom callbacks directly. For local testing, run the Yii app locally, expose it with a public HTTPS tunnel such as ngrok or Cloudflare Tunnel, then set DARAJA_CALLBACK_BASE_URL to that tunnel URL.

Endpoint Overrides

Some less common Daraja APIs can return 404 if Safaricom changes the sandbox path or exposes a different path in your Daraja portal. You can override a package endpoint path from .env without editing vendor.

Example:

DARAJA_ENDPOINT_LIPA_NA_BONGA_CALCULATE_POINTS=/v1/lipa/na/bonga/calculator-points

The request page displays the full URL being called so you can compare it with the Safaricom portal.

Troubleshooting

STK Push: Invalid Password

Safaricom expects:

base64_encode(BusinessShortCode + Passkey + Timestamp)

The app now generates that value automatically on submit. If the error persists, confirm:

• DARAJA_PASSKEY is correct.
• BusinessShortCode matches the passkey.
• Timestamp is in YYYYMMDDHHMMSS format.
• You are using the correct sandbox or production environment.

Lipa na Bonga: HTTP 404

If Lipa na Bonga is enabled but returns 404, compare the URL shown on the request page with the URL in your Daraja sandbox portal. If they differ, set an endpoint override in .env.

Project Structure

components/daraja/          Daraja service adapter
components/daraja/contracts Service interfaces
controllers/DarajaController.php
models/DarajaRequestForm.php
views/daraja/               Daraja service pages
docs/screenshots/           README screenshots

Quality Checks

Run syntax and coding-standard checks:

php -l controllers/DarajaController.php
php -l models/DarajaRequestForm.php
vendor/bin/phpcs controllers models components views