Installation

Plugipay ships three flavors of tooling. Pick the one that fits how you work:

• CLI — plugipay on your terminal. Best for one-off operations, scripting, and exploration. Doesn't require a project.
• SDK — libraries in Node.js, Python, and Go. Best for embedding Plugipay in an application.
• Raw API — if you can't or don't want to add a dependency, the REST API is fully documented and signed with HMAC.

This page covers installing the CLI and SDKs. If you want raw API access, skip ahead to the API authentication page.

CLI

The CLI is published on npm as @forjio/plugipay-cli. Install it globally:

npm install -g @forjio/plugipay-cli

Verify the install:

plugipay --version

You should see something like plugipay/0.x.y. If you get command not found, your global npm bin directory isn't on your PATH — the npm docs cover how to fix that for your shell.

Prefer not to install globally? You can run it as npx @forjio/plugipay-cli <command> for one-off uses, or add it as a dev dependency on a project.

The next step is authenticating the CLI against your Plugipay workspace.

Node.js SDK

The Node SDK is @forjio/plugipay-node:

npm install @forjio/plugipay-node

Or with pnpm / yarn:

pnpm add @forjio/plugipay-node
yarn add @forjio/plugipay-node

It's compatible with Node 18 and later. It ships with TypeScript types out of the box — no @types/* package needed.

Minimal usage:

import { PlugipayClient } from '@forjio/plugipay-node';

const plugipay = new PlugipayClient({
  keyId: process.env.PLUGIPAY_KEY_ID,
  keySecret: process.env.PLUGIPAY_KEY_SECRET,
});

const customers = await plugipay.customers.list({ limit: 10 });
console.log(customers);

The full reference is at SDK → Node.js.

Python SDK

The Python SDK is published on PyPI as plugipay:

pip install plugipay

It supports Python 3.9+. Dependencies: httpx (only).

Minimal usage:

from plugipay import PlugipayClient
import os

plugipay = PlugipayClient(
    key_id=os.environ["PLUGIPAY_KEY_ID"],
    key_secret=os.environ["PLUGIPAY_KEY_SECRET"],
)

customers = plugipay.customers.list(limit=10)
print(customers)

The full reference is at SDK → Python.

Go SDK

The Go SDK lives in the same repo as Plugipay itself:

go get github.com/hachimi-cat/saas-plugipay/sdk/go

Import it as plugipay:

import plugipay "github.com/hachimi-cat/saas-plugipay/sdk/go"

It uses only the Go standard library — no external dependencies. Requires Go 1.22+.

Minimal usage:

package main

import (
    "context"
    "fmt"
    "os"

    plugipay "github.com/hachimi-cat/saas-plugipay/sdk/go"
)

func main() {
    client, err := plugipay.NewClient(plugipay.ClientOptions{
        KeyID:     os.Getenv("PLUGIPAY_KEY_ID"),
        KeySecret: os.Getenv("PLUGIPAY_KEY_SECRET"),
    })
    if err != nil {
        panic(err)
    }

    customers, err := client.Customers.List(context.Background(), plugipay.ListParams{Limit: 10})
    if err != nil {
        panic(err)
    }
    fmt.Println(customers)
}

The full reference is at SDK → Go.

Get your API key

All three SDKs and the CLI need a Plugipay API key. To get one:

1. Sign up at plugipay.com — takes about a minute. See Sign up for the details.
2. Open the dashboard and go to Settings → API keys.
3. Click Create API key. Pick Test for development.
4. Copy the key_id and key_secret immediately — we don't show the secret again.

The convention across SDKs is to read credentials from environment variables:

Variable	Purpose
PLUGIPAY_KEY_ID	Public key identifier — safe to commit
PLUGIPAY_KEY_SECRET	Secret key — never commit, never log
PLUGIPAY_BASE_URL	Optional — only set if you're pointing at staging or a self-hosted Plugipay instance

Don't bake the secret into source. Use your environment's secret manager. For local dev, a gitignored .env file plus dotenv is fine. For production, use AWS Secrets Manager, Vault, or your platform's equivalent.

If you'd rather pass the credentials explicitly:

const plugipay = new PlugipayClient({ keyId: 'pk_test_...', keySecret: 'sk_test_...' });

plugipay = PlugipayClient(key_id='pk_test_...', key_secret='sk_test_...')

client, _ := plugipay.NewClient(plugipay.ClientOptions{KeyID: "pk_test_...", KeySecret: "sk_test_..."})

Test vs live keys

Plugipay keys are prefixed with their environment:

• pk_test_ + sk_test_ — test environment, no real money.
• pk_live_ + sk_live_ — live environment, real money.

The base URL is the same (https://api.plugipay.com); Plugipay routes the request to the correct environment based on the key. You can run test and live in parallel — create both keys, store them under different env-var names, switch by setting which one is exported.

Sandbox & staging

If you want to test against a non-production Plugipay instance — say to verify behavior before we ship a release — you can point any SDK or the CLI at staging:

export PLUGIPAY_BASE_URL=https://api-staging.plugipay.com

Test keys minted in production don't work in staging and vice versa. We can issue staging keys on request — email hello@plugipay.com if you're building an integration that needs them.

Next: take a payment

You're ready. Head to Your first payment for the next-level walkthrough beyond the Quickstart.