Tatua SDK

Listen to M-Pesa payments without Daraja credentials. Just give us your till or paybill number.

Installation

npm install tatua-sdk

Quick Start

import { TatuaClient } from 'tatua-sdk';

const tatua = new TatuaClient({
  apiKey: 'tatua_your_api_key_here',
});

// List your recent payments
const { data, pagination } = await tatua.transactions.list({ limit: 20 });

data.forEach(txn => {
  console.log(`KES ${txn.amount} from ${txn.phone} — ref: ${txn.billRef}`);
});

// Get a specific payment by M-Pesa TransID
const txn = await tatua.transactions.get('OEI2AK4Q16');
console.log(txn.customer.firstName, txn.amount);

// Get your business profile
const profile = await tatua.getProfile();
console.log(profile.name, profile.shortcode);

Listening to Payments (Webhooks)

If you want real-time notifications when a payment arrives, register a webhookUrl when signing up with Tatua. We will POST the following JSON to your URL immediately after each payment:

{
  "event": "payment.received",
  "transId": "OEI2AK4Q16",
  "shortcode": "123456",
  "phone": "254712345678",
  "amount": 1500,
  "billRef": "INV-001",
  "firstName": "John",
  "middleName": null,
  "lastName": "Doe",
  "transactionType": "Pay Bill",
  "timestamp": "2024-04-26T10:30:00.000Z"
}

Express webhook handler

import express from 'express';
import { parseWebhookPayload } from 'tatua-sdk';

const app = express();
app.use(express.json());

app.post('/payments/webhook', (req, res) => {
  // Always respond 200 immediately — process async
  res.sendStatus(200);

  const payment = parseWebhookPayload(req.body);
  if (!payment) return;

  console.log(`New payment: KES ${payment.amount} from ${payment.phone}`);
  // Save to your DB, send WhatsApp alert, etc.
});

app.listen(4000);

Fastify webhook handler

import Fastify from 'fastify';
import { parseWebhookPayload } from 'tatua-sdk';

const fastify = Fastify();

fastify.post('/payments/webhook', async (req, reply) => {
  reply.code(200).send(); // respond immediately

  const payment = parseWebhookPayload(req.body);
  if (!payment) return;

  console.log(`KES ${payment.amount} from ${payment.phone}`);
});

fastify.listen({ port: 4000 });

API Reference

TatuaClient

const tatua = new TatuaClient({
  apiKey: string,       // required — from Tatua dashboard
  gatewayUrl?: string,  // optional — defaults to https://gateway.tatua.co.ke
});

tatua.transactions.list(options?)

| Option | Type | Default | Description | |----------|----------|---------|--------------------------------------| | limit | number | 50 | Results per page (max 200) | | offset | number | 0 | Pagination offset | | from | string | — | ISO date string filter start | | to | string | — | ISO date string filter end |

Returns { data: TatuaTransaction[], pagination: { total, limit, offset, hasMore } }

tatua.transactions.get(transId)

Get a single transaction by its M-Pesa TransID (e.g. "OEI2AK4Q16").

tatua.getProfile()

Returns your business profile: { id, name, shortcode, shortcodeType, createdAt }.

parseWebhookPayload(body)

Validates and parses an incoming webhook body. Returns TatuaWebhookPayload | null.

Types

interface TatuaTransaction {
  id: string;
  transId: string;        // M-Pesa TransID
  shortcode: string;
  phone: string;          // 254XXXXXXXXX
  amount: number;         // KES
  billRef: string | null; // account ref customer typed
  customer: {
    firstName: string;
    middleName: string | null;
    lastName: string;
  };
  transactionType: string;
  orgBalance: string | null;
  webhookDelivered: boolean;
  timestamp: string;      // ISO 8601
}