Metadata-Version: 2.4
Name: stackapi-sdk
Version: 1.0.0
Summary: Official Python SDK for StackApi: payments, payouts, messaging, identity, bills, virtual cards, logistics and more behind one key.
Author: Stack Technology Limited
License: MIT
Project-URL: Homepage, https://stackapi.app
Project-URL: Documentation, https://stackapi.app/docs
Keywords: stackapi,nigeria,api,payments,payouts,sms,kyc,bvn,nin,virtual cards,logistics,fintech
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# StackApi Python SDK

The official Python library for [StackApi](https://stackapi.app): payments, payouts, SMS and email, identity checks,
bill payments, virtual cards, logistics, FX rates and more behind one key.

* Python 3.8 or later. **Standard library only.**
* Test keys (`Psk-test-...`) run everything in the sandbox: nothing is sent, booked or charged. Switch to a live key with the same code.

## Install

```bash
pip install stackapi-sdk
```

The package installs as `stackapi`.

## First request

```python
import os
from stackapi import StackApi

stackapi = StackApi(
    secret_key=os.environ["STACKAPI_SECRET_KEY"],
    public_key=os.environ["STACKAPI_PUBLIC_KEY"],
)

sms = stackapi.notifications.send_sms(to="08031234567", message="Your code is 123456")
print(sms["status"])
```

Every method sends the fields you give it (as keyword arguments) and returns the API's JSON answer as a dict. The
fields are the ones in the [API reference](https://stackapi.app/docs).

| Resource | Methods |
|---|---|
| `notifications` | `send_sms`, `send_bulk_sms`, `sms_status`, `send_otp`, `verify_otp`, `send_email` (`from_=`), `email_domains.*`, `inbound.*` |
| `payments` | `initiate`, `get` |
| `identity` | `verify_bvn`, `verify_nin`, `verify_phone`, `verify_cac`, `verify_bank_account`, `company_search`, `verify(check, **fields)`, `pricing` |
| `address_verifications` | `create`, `list`, `get`, `simulate_complete` |
| `vtu` | `airtime`, `data`, `plans`, `electricity`, `cable_tv`, `betting`, `education`, `verify_customer`, `transaction` |
| `payouts` | `banks`, `fees`, `resolve`, `create`, `get`, `list` |
| `banking` | `create_account`, `list_accounts`, `get_account`, `payments`, `simulate_payment`, `banks`, `resolve` |
| `fx` | `rates`, `convert(from_, to, amount)`, `history`, `currencies` |
| `cards` | `create_cardholder`, `list_cardholders`, `get_cardholder`, `create`, `list`, `get`, `fund`, `withdraw`, `freeze`, `unfreeze`, `terminate`, `transactions`, `reveal`, `simulate_transaction` |
| `logistics` | `create_address`, `list_addresses`, `get_address`, `categories`, `create_quote`, `create_shipment`, `list_shipments`, `get_shipment`, `cancel_shipment`, `simulate_shipment` |

Anything else your key can call: `stackapi.request("POST", "/v1/commerce/invoices", body={...})`.

## Errors

A non-2xx answer raises `StackApiError` with `status`, `code` (StackApi's error code, for example
`INSUFFICIENT_BALANCE`) and `message`. A request that never reached StackApi raises with `status` 0 and code
`NETWORK_ERROR`.

Reads (GET) are retried on network errors, 429 and 502/503/504. Writes are never retried by the SDK: send your own
`reference` where the endpoint takes one and repeat the call; the API answers the first result again.

## Webhooks

```python
from stackapi import verify_webhook, WebhookVerificationError

# Flask: raw = request.get_data()
event = verify_webhook(raw, request.headers, os.environ["STACKAPI_WEBHOOK_SECRET"])
# {"event": "card.transaction", "data": {...}, "timestamp": ..., "attempt": 1}
```

`verify_webhook` checks `X-StackApi-Signature` (`v1=` HMAC-SHA256 of `"<timestamp>.<raw body>"`) in constant time
and refuses a timestamp more than 5 minutes away.

## Options

`StackApi(secret_key, public_key, base_url="https://api.stackapi.app", timeout=30.0, max_retries=2)`

## License

MIT
