CORE INFRA
MANUAL.

Quick Start

To begin orchestrating payments, first initialize the HirallPay client with your secure merchant credentials.

npm i @hirallpay/sdk

Configure your environment with the standard HirallPay variables extracted from your dashboard settings.

HirallPay_API_KEY=sk_test_51Mz...
HirallPay_WEBHOOK_SECRET=whsec_...

Project Structure

The HirallPay ecosystem is split into two primary components to separate core infrastructure from user-facing interfaces.

Environment Setup

Ensure your environment is properly configured with these core variables to enable secure API communication.

The Money Flow

When a developer adds their Daraja credentials, they're giving HirallPay their Shortcode — which is their own Paybill or Till number registered with Safaricom. That shortcode is what tells M-Pesa whose account to deposit the money into.

The Full Flow in Detail

1. Developer adds their credentials to HirallPay:
   • Consumer Key & Secret: Used to get OAuth token from Daraja
   • Passkey: Used to generate STK push password
   • Shortcode: THIS is where money lands (developer's Paybill)
2. Customer pays via developer's app.
3. HirallPay builds the STK Push request using developer's OWN credentials.
4. Safaricom receives the request, sees the shortcode, prompts the customer, and deposits money into the developer's account.
5. HirallPay never appears in this transaction at all.

So the credentials are the proof of ownership. Only the real owner of a Paybill has the matching Consumer Key, Secret, and Passkey from Daraja. When HirallPay uses those credentials, Safaricom treats it exactly as if the developer's own server made the call.

Authentication

HirallPay uses deterministic bearer tokens for all API interactions. All requests must be performed over SSL with a strictly formatted Authorization header.

curl -X POST https://api.hirallpay.dev/v1/payments/initiate \
  -H "x-api-key: sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "DARAJA",
    "amount": 1000,
    "currency": "KES",
    "customer": { "phone": "254712345678" }
  }'

STK Push (M-Pesa)

The STK Push (Sim Tool Kit) allows you to trigger a payment request directly on the user's mobile device. This is the gold standard for frictionless mobile money in Kenya.

import { HirallPayClient } from '@hirallpay/sdk';

const client = new HirallPayClient({ 
  apiKey: process.env.HIRALL_PAY_API_KEY 
});

const result = await client.payments.initiate({
  provider: 'DARAJA',
  amount: 1000,
  currency: 'KES',
  customer: {
    phone: '254712345678'
  },
  description: 'Service Payment'
});

Node.js SDK

The official HirallPay Node.js SDK provides a type-safe wrapper around our core APIs, designed for high-concurrency environments.

npm install @hirallpay/sdk

React/Next.js Integration

Use our pre-built components for a seamless checkout experience within any React framework.

Handling Webhooks

HirallPay relies on asynchronous webhooks to communicate transaction finality. Ensure your endpoint returns a 200 OK status within 200ms to avoid re-delivery.

Troubleshooting Guide

Use this guide to resolve common integration roadblocks and environment configuration issues.