> ## Documentation Index
> Fetch the complete documentation index at: https://docs.palpluss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> Official PalPluss SDKs for TypeScript, Python, and PHP — install, configure, and start processing payments in minutes.

# 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

<CodeGroup>
  ```bash TypeScript / Node.js theme={null}
  npm install @palpluss/sdk
  # or
  pnpm add @palpluss/sdk
  # or
  yarn add @palpluss/sdk
  ```

  ```bash Python theme={null}
  pip install palpluss
  ```

  ```bash PHP theme={null}
  composer require palpluss/sdk
  ```
</CodeGroup>

***

## Client initialisation

The API key can be passed directly or read from the `PALPLUSS_API_KEY` environment variable.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { PalPluss } from '@palpluss/sdk';

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

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

  ```python Python theme={null}
  from palpluss import PalPluss

  client = PalPluss(api_key="pk_live_...")

  # or — reads PALPLUSS_API_KEY automatically
  client = PalPluss()
  ```

  ```php PHP theme={null}
  use PalPluss\PalPluss;

  $client = new PalPluss(apiKey: 'pk_live_...');

  // or — reads PALPLUSS_API_KEY automatically
  $client = new PalPluss();
  ```
</CodeGroup>

### Constructor options

| Option                 | Default                    | Description                                   |
| ---------------------- | -------------------------- | --------------------------------------------- |
| `apiKey`               | `PALPLUSS_API_KEY` env var | Your API key (`pk_live_...` or `pk_test_...`) |
| `timeout`              | `30s`                      | Per-request timeout                           |
| `autoRetryOnRateLimit` | `true`                     | Automatically retry after HTTP 429            |
| `maxRetries`           | `3`                        | Maximum retry attempts                        |

Set `PALPLUSS_BASE_URL` to override the base URL (sandbox, local, etc.).

***

## Choose your language

<CardGroup cols={3}>
  <Card title="TypeScript / Node.js" icon="js" href="/sdks/typescript">
    Next.js, NestJS, Encore.ts, plain Node.js, and more.
  </Card>

  <Card title="Python" icon="python" href="/sdks/python">
    FastAPI, Django, Flask, and async patterns.
  </Card>

  <Card title="PHP" icon="php" href="/sdks/php">
    Laravel, Symfony, and plain PHP.
  </Card>
</CardGroup>

***

## Response shape

Every successful response is unwrapped by the SDK — you receive the `data` payload directly. The raw envelope looks like this:

```json theme={null}
{
  "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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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}`);
    }
  }
  ```

  ```python Python theme={null}
  from palpluss import PalPlussApiError, RateLimitError

  try:
      result = client.stk_push(amount=500, phone="254712345678")
  except RateLimitError as e:
      print(f"Rate limited — retry after {e.retry_after}s")
  except PalPlussApiError as e:
      print(f"[{e.code}] {e}  request_id={e.request_id}")
  ```

  ```php PHP theme={null}
  use PalPluss\Http\Errors\PalPlussApiError;
  use PalPluss\Http\Errors\RateLimitError;

  try {
      $result = $client->stkPush(amount: 500, phone: '254712345678');
  } catch (RateLimitError $e) {
      echo "Rate limited — retry after {$e->retryAfter}s\n";
  } catch (PalPlussApiError $e) {
      echo "[{$e->errorCode}] {$e->getMessage()}  requestId={$e->requestId}\n";
  }
  ```
</CodeGroup>

See [Error handling guide](/guides/errors) for the full list of error codes.