cosmic-python-sdk 0.2.0

Official Python SDK for the Cosmic Gateway payment processing API

Cosmic Python SDK

Official Python client SDK for the Cosmic Gateway payment processing API.

Features

• Complete payment lifecycle — charge, capture, refund, and query payments
• Customer management — create, retrieve, and list customers
• Transaction history — paginated transaction listing with filters
• Webhook verification — HMAC-SHA256 signature verification for incoming webhooks
• Idempotency — automatic idempotency key generation to safely retry requests
• Retry with backoff — automatic retry on 5xx errors and rate limits (429)
• Request timeout — configurable timeout per request
• Environment switching — built-in sandbox and production endpoints
• Input validation — pre-flight validation of amounts, currencies, emails, and more
• Typed request/response models — dataclass-based types for all API objects
• Sensitive data masking — automatic masking of API keys, PAN, and CVC in logs

Installation

pip install cosmic-python-sdk

Requires Python 3.8+.

Development installation

pip install cosmic-python-sdk[dev]

Quick Start

from cosmic_sdk import CosmicGateway

client = CosmicGateway(
    api_key="sk_test_...",
    environment="sandbox",  # or "production"
)

# Charge a payment
result = client.payments.charge({
    "amount": 1999,        # $19.99 in cents
    "currency": "usd",
    "source": "tok_visa_4242",
    "description": "Test payment",
})

if result["success"]:
    print("Payment ID:", result["transactionId"])
    print("New balance:", result["newBalance"])
else:
    print("Payment failed:", result["status"])

Configuration

Option	Type	Default	Description
api_key	str	required	Your secret API key
environment	str	'production'	API environment: 'sandbox' or 'production'
base_url	str	environment default	Custom API base URL (overrides environment)
timeout	int	30000	Request timeout in milliseconds

Environment URLs

Environment	URL
sandbox	https://api.sandbox.cosmicgateway.com
production	https://api.cosmicgateway.com

Retry Configuration

The SDK retries failed requests with exponential backoff. Configure via RetryConfig:

from cosmic_sdk import CosmicGateway
from cosmic_sdk.config import RetryConfig

client = CosmicGateway(
    api_key="sk_test_...",
    environment="sandbox",
)

client.config.retry = RetryConfig(
    max_retries=5,
    base_delay_ms=200,
    max_delay_ms=10000,
)

API Reference

Payments

client.payments.charge(request)

Process a payment charge.

result = client.payments.charge({
    "amount": 1999,
    "currency": "usd",
    "source": "tok_abc123",
    "description": "Order #1234",
    "metadata": {"orderId": "ORD-12345"},
    "idempotencyKey": "uuid-v4",  # optional — auto-generated if omitted
})

Success response:

{
    "success": True,
    "transactionId": "txn_...",
    "referenceId": "ref_...",
    "processor": "stripe",
    "region": "us",
    "amount": 1999,
    "currency": "usd",
    "settlement": {  # present for cross-currency payments
        "from": "usd",
        "to": "kes",
        "originalAmount": 1999,
        "convertedAmount": 289855,
        "rate": 145.0,
    },
    "newBalance": 50000,
    "fraudScore": 0.02,
    "kycVerified": "verified",
}

Failed response:

{
    "success": False,
    "transactionId": "txn_...",
    "referenceId": None,
    "processor": "stripe",
    "region": "us",
    "status": "failed",
}

client.payments.retrieve(payment_id)

Retrieve payment details by ID.

payment = client.payments.retrieve("pay_abc123")

client.payments.list(params=None)

List payments with optional filtering.

result = client.payments.list({
    "page": 1,
    "limit": 20,
    "status": "SUCCESS",
    "startDate": "2026-01-01T00:00:00Z",
    "endDate": "2026-12-31T23:59:59Z",
})

Refunds

client.refunds.create(request)

Create a refund for a payment.

result = client.refunds.create({
    "paymentId": "pay_abc123",
    "amount": 500,  # partial refund (optional, defaults to full)
    "reason": "Customer requested refund",
    "metadata": {"ticketId": "TKT-999"},
})

client.refunds.retrieve(refund_id)

refund = client.refunds.retrieve("ref_abc123")

client.refunds.list(params=None)

Customers

client.customers.create(request)

customer = client.customers.create({
    "email": "[e-mail]",
    "name": "John Doe",
    "phone": "[phone]",
    "metadata": {"signupSource": "web"},
})

client.customers.retrieve(customer_id)

client.customers.list(params=None)

Transactions

client.transactions.list(params=None)

result = client.transactions.list({
    "page": 1,
    "limit": 20,
})

client.transactions.retrieve(transaction_id)

Webhook Verification

from cosmic_sdk.webhooks import verify_webhook_signature

payload = request.body  # raw bytes
signature = request.headers.get("X-Cosmic-Signature")  # "sha256=..."
secret = "whsec_..."

event = verify_webhook_signature(payload, signature, secret)
# {"event": "payment.succeeded", "transactionId": "txn_1", ...}

The SDK verifies the sha256= HMAC signature using timing-safe comparison (hmac.compare_digest).

Raises WebhookVerificationError if the signature is missing, malformed, or doesn't match.

Health Check

health = client.health()
# {"status": "ok"}

Raw HTTP Methods

The SDK exposes get() and post() for direct API access if needed:

# Raw GET
resp = client.get("/customers", params={"limit": 10})

# Raw POST
resp = client.post("/customers", json={"email": "[e-mail]"})

Error Handling

The SDK raises typed exceptions for all failure modes:

Exception	HTTP Status	When
ValidationError	400	Invalid input
AuthenticationError	401	Missing or invalid credentials
PaymentFailedError	402	Payment was declined
NotFoundError	404	Resource not found
RateLimitError	429	Too many requests
ServerError	500	Gateway internal error
ServiceUnavailableError	503	Service temporarily down
WebhookVerificationError	—	Webhook signature invalid

from cosmic_sdk.errors import PaymentFailedError, ValidationError

try:
    result = client.payments.charge({
        "amount": -1,
        "currency": "usd",
        "source": "tok_abc",
    })
except ValidationError as e:
    print("Bad input:", e)
except PaymentFailedError as e:
    print("Payment declined:", e.transaction_id)

Retry Behavior

• 5xx errors — retried with exponential backoff (base delay doubles each attempt)
• 429 rate limits — respects the Retry-After header
• Network errors — retried as transient failures
• 4xx errors (except 429) — not retried (these are client errors)
• Configurable via RetryConfig

Idempotency

All mutation endpoints (charge, create, etc.) accept an optional idempotency_key. If omitted, a UUID v4 is generated automatically. The gateway uses the api_key + idempotency_key pair to detect duplicate requests and return the cached response.

Sensitive Data Masking

The logger automatically masks sensitive fields (API keys, PAN, CVC, auth tokens) in logs. Set the log level to DEBUG to inspect request/response shapes without exposing secrets:

import logging
client._logger = GatewayLogger(level=logging.DEBUG)

Development

# Clone and install with dev dependencies
pip install -e ".[dev]"

# Run tests
python3 -m pytest tests/

# Run with coverage
python3 -m pytest tests/ --cov=cosmic_sdk

# Build distribution
python3 -m build

License

MIT