Installing the Python SDK

The Plugipay Python SDK ships on PyPI as plugipay. Standard pip install plugipay works in any virtualenv that's already on Python 3.9 or newer.

pip install plugipay

>>> import plugipay
>>> plugipay.__version__
'0.1.0'

If both lines worked, you're done — skip to the Quickstart. The rest of this page is for people who want to be careful about their environment.

Requirements

Requirement	Version	Notes
Python	3.9+	We follow SPEC 0. 3.8 was EOL October 2024.
`httpx`	`>=0.27.0`	The only runtime dependency. Installed automatically.
OS	Any	Pure Python — no native extensions.

httpx ships with the SDK; you don't install it separately. We picked it over requests so the same wire client works for both sync and (eventually) async, and because it has saner timeout and connection-pool defaults.

Why not requests? requests is in maintenance mode upstream and doesn't have a real async story. httpx is the maintained successor recommended by the same author. If your project already pins requests, the two coexist fine — the SDK doesn't import requests at all.

Recommended: virtual environment + pip

If you don't have a virtualenv yet, create one and install into it — never pip install into your system Python on Linux or macOS.

python -m venv .venv
source .venv/bin/activate         # macOS / Linux
# .venv\Scripts\activate          # Windows PowerShell

pip install plugipay

Verify:

python -c "from plugipay import PlugipayClient; print(PlugipayClient.__module__)"
# plugipay.client

Pin the version in requirements.txt:

plugipay==0.1.0
httpx>=0.27.0

(You technically only need to pin plugipay; pip resolves httpx from our metadata. But pinning explicitly is fine and what most teams do.)

Poetry

If your project uses Poetry:

poetry add plugipay

That writes the dependency into pyproject.toml and updates poetry.lock:

[tool.poetry.dependencies]
python = "^3.9"
plugipay = "^0.1.0"

Run scripts with poetry run python my_script.py or activate the env with poetry shell.

uv

If you've moved to uv (a faster pip + virtualenv replacement):

uv venv
uv pip install plugipay

Or in a pyproject.toml-based project (uv reads PEP 621 metadata):

uv add plugipay

uv is ~10x faster than pip for cold installs and is increasingly common in CI. The wheel we publish is pure Python, so there's nothing for uv to compile — installs typically take under a second.

Pipenv

pipenv install plugipay

That writes to Pipfile:

[packages]
plugipay = "*"

Pin with plugipay = "==0.1.0" if you want strict version control.

conda

We don't publish on conda-forge. Install with pip inside a conda env:

conda create -n my-env python=3.11
conda activate my-env
pip install plugipay

This is the standard pattern for Python packages that aren't conda-packaged; conda and pip coexist within an env.

Verifying the install

A more thorough check than import plugipay:

from plugipay import PlugipayClient, verify_webhook, PlugipayError

# Constructor validates that both args are non-empty.
plug = PlugipayClient(key_id="pk_test_xxx", secret="sk_test_xxx")
print(plug.base_url)        # https://plugipay.com
print(plug.timeout)         # 30.0

# Resource namespaces are attached on the instance.
print(type(plug.customers).__name__)  # _Customers
plug.close()

If any of those raise ImportError or AttributeError, you have a partial install — clean up with pip uninstall plugipay and reinstall.

Upgrading

pip install -U plugipay

The SDK is pre-1.0, so minor versions may include small breaking changes. We document every break in the changelog on GitHub. After 1.0, the major/minor/patch contract becomes strict.

Optional: development extras

If you're contributing to the SDK or running its test suite:

pip install "plugipay[dev]"

That pulls in pytest>=8.0 and respx>=0.21.0 (an httpx mock adapter). You don't need this for normal usage.

Troubleshooting

`ERROR: Could not find a version that satisfies the requirement plugipay`

Your pip is too old to read the wheel's metadata, or it's pointing at a private index that doesn't mirror PyPI. Upgrade pip:

python -m pip install --upgrade pip

If you have a pip.conf with index-url = https://your-mirror/simple/, make sure the mirror has plugipay.

`ImportError: No module named 'httpx'`

Something stripped httpx from your env. Reinstall:

pip install --force-reinstall plugipay

This is rare — usually a pip install --no-deps mistake or an aggressive pip uninstall.

`SSL: CERTIFICATE_VERIFY_FAILED` on first request

Your Python install can't find the system CA bundle — common on older macOS Pythons installed from python.org. Run:

/Applications/Python\ 3.11/Install\ Certificates.command

…or use a Python from pyenv/uv/Homebrew, which all wire the certs up correctly.

Pinning issue with another package

If another dependency pins httpx<0.27, you'll get a resolution error. Either upgrade that package, or open an issue on the conflicting project; the SDK requires httpx>=0.27.0 (released 2024) because it relies on the stable Client API there.

Quickstart — create a customer + a checkout session.
Authentication — constructor options + env-var conventions.
API keys — if you don't have a pk_test_* / sk_test_* pair yet.