Python client for the Paystack API, generated from the Paystack OpenAPI spec in this repository.
- Generated from the Paystack OpenAPI source of truth in this repo
- Includes opt-in helpers for timeouts, retries, idempotency, and structured API errors
- Keeps generated models and APIs aligned with the SDK generation spec
Python 3.9+
pip install alexasomba-paystackOr from source:
pip install git+https://github.com/alexasomba/paystack-python.gitThen import:
import alexasomba_paystackAuthenticate requests with your Paystack secret key through the generated configuration object:
configuration = alexasomba_paystack.Configuration(
access_token="sk_test_...",
)import os
import alexasomba_paystack
from alexasomba_paystack.api.transaction_api import TransactionApi
from alexasomba_paystack.models.transaction_initialize import TransactionInitialize
configuration = alexasomba_paystack.Configuration(
access_token=os.environ["PAYSTACK_SECRET_KEY"],
)
with alexasomba_paystack.ApiClient(configuration) as api_client:
api = TransactionApi(api_client)
response = api.transaction_initialize(
transaction_initialize=TransactionInitialize(
email="customer@example.com",
amount=5000,
)
)
print(response.data.authorization_url)Generated API calls return typed model instances. Catch ApiException when you need raw HTTP response details while debugging.
- Base URL:
https://api.paystack.co - HTTPS is required for all requests.
- Requests and responses are JSON-based.
- Most successful responses follow the
status,message,data, and optionalmetaenvelope described inPaystack-API/0a-Introduction.md. - Amounts are usually sent in currency subunits such as kobo, pesewas, or cents. Check the module docs for currency-specific rules.
- Server-side SDKs should use your secret key (
sk_test_*orsk_live_*). - Browser SDKs should use only your public key (
pk_test_*orpk_live_*). - Send server-side API credentials as
Authorization: Bearer YOUR_SECRET_KEY. - Test and live modes use different keys and isolated environments.
- Rotate keys if they are exposed, and never commit secret keys to source control.
- If you enable IP whitelisting in Paystack, requests from non-whitelisted IPs will be blocked.
This SDK includes opt-in helpers in alexasomba_paystack.extras:
from alexasomba_paystack.extras import create_paystack_client
client = create_paystack_client(
"YOUR_SECRET_KEY",
timeout_seconds=30,
idempotency=True,
)Use the extras layer when you want a higher-level client with timeout, retry, and idempotency behavior preconfigured.
- Paystack supports both offset pagination and cursor pagination.
- Offset pagination uses
pageandperPage. - Cursor pagination uses
use_cursor=trueplusnextorpreviouscursors returned inmeta. - Cursor pagination is especially useful for large or frequently changing datasets.
- The exact
metashape varies by endpoint and pagination mode.
- Paystack uses conventional HTTP status codes such as
200,201,400,401,404, and5xx. - Error responses typically include
status,message,type,code, and optional diagnosticmetainformation. - Error types described in
Paystack-API/0d-Errors.mdincludeapi_error,validation_error, andprocessor_error. - For charge and verify flows, always inspect the returned response body and status fields, not just the HTTP code.
This SDK is generated from the SDK spec in this monorepo and covers the operations emitted into the generated API modules under alexasomba_paystack.api.
For this SDK, these schema families are emitted as generated model modules under alexasomba_paystack.models and used by the generated API modules under alexasomba_paystack.api.
| Module | Schema / model family |
|---|---|
| Transactions | Transaction* |
| Verify Payments (Transaction verification) | VerifyResponse / TransactionFetchResponse |
| Charges | Charge* |
| Bulk Charges | BulkCharge* |
| Subaccounts | Subaccount* |
| Transaction Splits | Split* |
| Terminal | Terminal* |
| Virtual Terminal | VirtualTerminal* |
| Customers | Customer* |
| Direct Debit | DirectDebit* |
| Dedicated Virtual Accounts | DedicatedNuban* / DedicatedVirtualAccount* |
| Apple Pay | ApplePay* |
| Plans | Plan* |
| Subscriptions | Subscription* |
| Transfer Recipients | TransferRecipient* |
| Transfers | Transfer* |
| Transfers Control (OTP settings; under Transfers) | TransferEnable* / TransferDisable* / TransferFinalize* |
| Balance | Balance* |
| Payment Requests (Invoices) | PaymentRequest* |
| Verification (Resolve Account / Validate Account / Resolve Card BIN) | Verification* |
| Products | Product* |
| Storefronts | Storefront* |
| Orders | Order* |
| Payment Pages | Page* |
| Settlements | Settlement* |
| Integration | Integration* |
| Control Panel (Payment session timeout; under Integration) | ControlPanel* |
| Refunds | Refund* |
| Disputes | Dispute* |
| Banks | Bank* |
| Miscellaneous | Miscellaneous* / Currency |
These are intentionally short examples. Use them as entry points, then expand the generated models and method arguments for your use case.
response = transaction_api.transaction_initialize(
transaction_initialize=TransactionInitialize(email="customer@example.com", amount=5000)
)verified = transaction_api.transaction_verify("ref_123")charge_api.charge_create(
charge_create_request=ChargeCreateRequest(email="customer@example.com")
)bulk_charge_api.bulk_charge_initiate([
BulkChargeInitiate(authorization="AUTH_xxx", amount=5000, reference="bulk-ref-1")
])subaccount_api.subaccount_create(
subaccount_create=SubaccountCreate(business_name="Acme Stores")
)split_api.split_create(
split_create=SplitCreate(name="Main split", type="percentage", currency="NGN")
)terminals = terminal_api.terminal_list()virtual_terminal_api.virtual_terminal_create(
virtual_terminal_create=VirtualTerminalCreate(name="Web checkout terminal")
)customer_api.customer_create(
customer_create=CustomerCreate(email="customer@example.com")
)direct_debit_api.directdebit_initialize(
direct_debit_initialize_request=DirectDebitInitializeRequest(email="customer@example.com")
)dedicated_virtual_account_api.dedicated_account_assign(
dedicated_virtual_account_assign=DedicatedVirtualAccountAssign(customer=12345)
)apple_pay_api.apple_pay_register_domain(
apple_pay_param=ApplePayParam(domain_name="example.com")
)plan_api.plan_create(
plan_create=PlanCreate(name="Starter", amount=500000, interval="monthly")
)subscription_api.subscription_create(
subscription_create=SubscriptionCreate(customer="CUS_xxx", plan="PLN_xxx")
)transfer_recipient_api.transferrecipient_create(
transfer_recipient_create=TransferRecipientCreate(name="Ada Lovelace", type="nuban")
)transfer_api.transfer_create(
transfer_initiate=TransferInitiate(source="balance", amount=5000, recipient="RCP_xxx")
)transfer_api.transfer_enable_otp()balance = balance_api.balance_fetch()payment_request_api.payment_request_create(
payment_request_create=PaymentRequestCreate(amount=5000, description="Consulting invoice")
)resolved = bank_api.bank_resolve_account_number("0001234567", "057")product_api.product_create(
product_create=ProductCreate(name="T-shirt", price=5000, currency="NGN")
)storefronts = storefront_api.storefront_list()order_api.order_create(order_create=OrderCreate(customer="CUS_xxx"))page_api.page_create(page_create=PageCreate(name="Event Ticket", amount=5000))settlements = settlement_api.settlement_list()timeout = integration_api.integration_fetch_payment_session_timeout()integration_api.integration_update_payment_session_timeout(20)refund_api.refund_create(refund_create=RefundCreate(transaction=123456789, amount=5000))disputes = dispute_api.dispute_list()banks = bank_api.bank_list(country="nigeria")countries = miscellaneous_api.miscellaneous_list_countries()The generated Python client still exposes the standard OpenAPI Generator configuration surface. In normal usage, the main thing you need is bearer token configuration plus any optional HTTP client tuning.
- Node: alexasomba/paystack-node
- Axios: alexasomba/paystack-axios
- Browser: alexasomba/paystack-browser
- Go: alexasomba/paystack-go
- PHP: alexasomba/paystack-php
- Monorepo source: alexasomba/paystack-openapi
- Standalone SDK repo: https://github.com/alexasomba/paystack-python