Backend

Python SDK

Sync and async Python clients with Pydantic models and retries.

Updated Jul 15, 2026SDK v1.0.0API 2026-07-01 Edit on GitHub Report an issue

Sync and async Python clients with Pydantic models and retries. This page follows the same layout as every other Korven One SDK reference — install, authenticate, ship your first request, then wire webhooks and production-grade retries.

Overview

Python is a first-party integration for the Korven One platform. It ships with typed models, a signed-webhook verifier and idempotent request helpers so you can build reliable payment, wallet and remittance flows.

Installation

API v1

pip install korvenone

Requirements

Python 3.10+
A Korven One account with sandbox and (optionally) live API keys
An HTTPS-reachable webhook endpoint for asynchronous events

Authentication

Every request is authenticated with a bearer token. Use sk_test_... in sandbox and sk_live_... once your merchant account is activated. Never ship secret keys to the browser — use publishable keys (pk_*) for client-side flows.

API v1

export KORVEN_SECRET_KEY=sk_test_...

Quickstart

Create your first payment in under a minute. The snippet below uses the sandbox environment and an idempotency key so retries are safe.

SDK v1.0.0

import os, uuid, korvenone

korven = korvenone.Client(api_key=os.environ["KORVEN_SECRET_KEY"])

payment = korven.payments.create(
  amount=250_000,
  currency="HTG",
  customer="cus_9a2b",
  idempotency_key=str(uuid.uuid4()),
)

Example response

{
  "id": "pay_01HT3M9QK7ZS9V0AB1CDEFGH",
  "object": "payment",
  "amount": 250000,
  "currency": "HTG",
  "status": "succeeded",
  "customer": "cus_9a2b",
  "receipt_number": "RCP-2026-0000142",
  "livemode": false,
  "created": 1794902400
}

Errors & retries

The Korven One API uses deterministic error codes. Any 5xx response or network failure is safe to retry with the same Idempotency-Key — the API will replay the original result instead of creating a duplicate.

Recommended strategy

Exponential backoff: 250ms, 500ms, 1s, 2s, 4s (max 5 attempts).
Always include an Idempotency-Key on writes.
Surface 4xx validation errors to the user immediately.

Rate limits

Default limits: 100 read requests / second and 25 write requests / second per API key. Response headers X-RateLimit-Remaining and X-RateLimit-Reset expose the current window; a 429 response includes a Retry-After header.

Webhooks

Subscribe to events like payment.succeeded, payment.failed and settlement.paid. Every delivery is signed with HMAC-SHA256 — verify the Korven-Signature header before trusting the payload.

Examples

Hosted checkout for one-off payments
Recurring subscriptions with proration
Marketplace split payments and payouts
Cross-border remittances with locked FX quotes