Skip to main content

​
SDK Overview

PalPluss provides official SDKs for TypeScript/Node.js, Python, and PHP. Every SDK covers the same API surface with idiomatic naming conventions and full type coverage for its language.

​
Installation

npm install @palpluss/sdk
# or
pnpm add @palpluss/sdk
# or
yarn add @palpluss/sdk

​
Client initialisation

The API key can be passed directly or read from the PALPLUSS_API_KEY environment variable. 
import { PalPluss } from '@palpluss/sdk';

const client = new PalPluss({ apiKey: 'pk_live_...' });

// or — reads PALPLUSS_API_KEY automatically
const client = new PalPluss();

​
Constructor options

OptionDefaultDescription
apiKeyPALPLUSS_API_KEY env varYour API key (pk_live_... or pk_test_...)
timeout30sPer-request timeout
autoRetryOnRateLimittrueAutomatically retry after HTTP 429
maxRetries3Maximum retry attempts
Set PALPLUSS_BASE_URL to override the base URL (sandbox, local, etc.).

​
Choose your language

TypeScript / Node.js

Next.js, NestJS, Encore.ts, plain Node.js, and more.

Python

FastAPI, Django, Flask, and async patterns.

PHP

Laravel, Symfony, and plain PHP.

​
Response shape

Every successful response is unwrapped by the SDK — you receive the data payload directly. The raw envelope looks like this: 
{
  "success": true,
  "data": { },
  "requestId": "d3f1a9b2-4a7f-4c6e-bcde-1234567890ab"
}
The SDK unwraps data and attaches requestId to error objects so you can include it in support requests.

​
Error handling

All SDKs throw a typed PalPlussApiError on non-2xx responses and a RateLimitError on HTTP 429. 
import { PalPlussApiError, RateLimitError } from '@palpluss/sdk';

try {
  const result = await client.stkPush({ amount: 500, phone: '254712345678' });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log(`Rate limited — retry after ${err.retryAfter}s`);
  } else if (err instanceof PalPlussApiError) {
    console.log(`[${err.code}] ${err.message}  requestId=${err.requestId}`);
  }
}
See Error handling guide for the full list of error codes.