Python

This is the reference SDK: the others compare their requests against what this one sends.

Install #

pip install compense-sdk-python

Sync client #

import os
from compense_gateway import CompenseClient, RetryConfig

with CompenseClient(
    api_key=os.environ["COMPENSE_API_KEY"],   # cmp_...
    environment="sandbox",                    # "production" (default) | "sandbox" | "dev"
    timeout=30.0,                             # seconds per attempt
    retry=RetryConfig(max_attempts=3, retry_writes=False),
) as client:
    print(client.system.health().tenant)

Constructor parameters: api_key, environment, base_url (takes precedence over the environment), timeout, retry, user_agent, and for testing or advanced configuration transport (httpx.BaseTransport) or http_client (your own httpx.Client, which the SDK doesn’t close).

Async client #

AsyncCompenseClient has exactly the same surface; every method is awaitable. Use it in FastAPI, aiohttp or any asyncio code:

import asyncio
from compense_gateway import AsyncCompenseClient

async def main():
    async with AsyncCompenseClient(api_key=os.environ["COMPENSE_API_KEY"], environment="sandbox") as client:
        balance, loans = await asyncio.gather(
            client.wallet.balance("1032456789"),
            client.loans.list("1032456789", status="ACTIVE"),
        )
        print(balance.available.amount, loans.count)

asyncio.run(main())

Conventions #

• snake_case methods grouped by module: client.credits.submit_application(...), client.wallet.bills.pay(...), client.admin.payroll.create_novelties(...).
• Named (keyword-only) arguments for everything optional; the holder is always document.
• Writes → Transaction; reads → a typed model (Balance, Resolution, Page, OffsetPage, AffiliateLookup, WebhookEndpoint, TestClock, GatewayHealth, TransactionStatus…) or dict. Every model keeps the original body in .raw.
• Free-form fields: extra= (credits, subsidies, loan portfolio, PQRS) and **fields in the administrative module, with the contract’s names (snake_case).
• client.wallet.accounts, .cards and .fx are the same objects as client.accounts, client.cards and client.fx.
• client.health is the health services module (IPS); the gateway’s health check is client.system.health().

Errors #

from compense_gateway import (
    CompenseError, CompenseConfigError, CompenseAPIError, AuthError, NotFoundError,
    IdempotencyConflictError, ValidationError, RateLimitError, UpstreamError, ServerError,
)

CompenseAPIError exposes status, title, detail, trace_id, retry_after and the full problem (problem.type, problem.errors). Network errors are httpx’s (httpx.TransportError). See Errors.

Pagination #

Page and OffsetPage iterate over the results of that page. To walk through all of them, request the next one with page= or offset= (Pagination).

Webhooks #

from compense_gateway.webhooks import verify_webhook, WebhookVerificationError, EVENT_TYPES

event = verify_webhook(raw_body, headers, secret=[NEW_SECRET, OLD_SECRET], tolerance=300)
event.event_id, event.event, event.resource, event.is_test

It doesn’t need httpx or a client instance. Complete receivers with Flask and FastAPI are in Verifying the signature.

compense CLI #

Installing the SDK installs the compense command (key in --key or $COMPENSE_API_KEY, sandbox environment by default, JSON output): health, events, endpoints, endpoint-create, trigger, deliveries, replay, clock, simulate and listen. Full reference in CLI.

Testing #

Inject an httpx.MockTransport to test your code without a network:

import httpx
from compense_gateway import CompenseClient

def handler(request: httpx.Request) -> httpx.Response:
    assert request.headers["X-API-Key"] == "cmp_test"
    if request.url.path == "/v1/gateway/wallet/balance/":
        return httpx.Response(200, json={"total": "150000.00", "available_cash": "150000.00", "currency": "COP"})
    return httpx.Response(404, json={"title": "Not Found", "status": 404, "trace_id": "t"})

client = CompenseClient(api_key="cmp_test", environment="sandbox", transport=httpx.MockTransport(handler))
assert client.wallet.balance("1032456789").available.amount == "150000.00"

For integration tests, use a sandbox key: it’s deterministic (Sandbox).