Python SDK

Le SDK Python officiel de Kobara permet d’intégrer facilement :

• les paiements MonCash ;
• les liens de paiement ;
• les retraits ;
• les webhooks ;
• les notifications temps réel ;

dans vos applications backend Python.

Le SDK est optimisé pour :

• Django ;
• Flask ;
• FastAPI ;
• aiohttp ;
• applications serverless ;
• APIs modernes Python.

Installation

Installez le SDK avec pip :

BASH
content_copy
pip install kobara

Compatibilité

Initialisation

Le SDK doit être initialisé avec votre Secret Key.

⚠️ Toujours côté serveur.

PYTHON
content_copy
from kobara import Kobara
import os

client = Kobara(
    api_key=os.environ.get(
        "KOBARA_SECRET_KEY"
    )
)

Variables d’environnement

ENV
content_copy
KOBARA_SECRET_KEY=kbr_sk_live_xxxxxxxxx

Important

⚠️ Ne jamais exposer votre Secret Key :

• dans React ;
• dans le navigateur ;
• dans une app mobile ;
• dans du code frontend.

Premier paiement

Exemple FastAPI

PYTHON
content_copy
from fastapi import FastAPI
from kobara import Kobara
import os

app = FastAPI()

client = Kobara(
    api_key=os.environ.get(
        "KOBARA_SECRET_KEY"
    )
)

@app.post("/checkout")
def create_checkout():

    payment = client.payments.create(

        amount=1000,

        currency="HTG",

        description="Achat FastAPI",

        success_url=
        "https://mon-site.com/success"

    )

    return {
        "checkout_url": payment.url
    }

Explication du flux

1. Le client clique “Payer”

Votre frontend appelle :

Terminal
content_copy
POST /checkout

2. Votre backend Python crée le paiement

Le SDK :

• contacte l’API Kobara ;
• sécurise la requête ;
• communique avec MonCash ;
• prépare le checkout MonCash.

3. Kobara retourne une URL

JSON
content_copy
{
  "checkout_url":
  "https://checkout.kobara.app/pay/abc123"
}

4. Redirection utilisateur

Frontend :

JS
content_copy
window.location.href = checkout_url;

Pourquoi utiliser le SDK Python

Le SDK :

• simplifie les intégrations ;
• évite les requêtes HTTP manuelles ;
• gère les headers ;
• sécurise l’authentification ;
• valide les réponses ;
• simplifie les webhooks.

Créer un paiement

Exemple complet

PYTHON
content_copy
payment = client.payments.create(

    amount=2500,

    currency="HTG",

    description="Commande Kobara",

    customer={

        "name": "Jean Pierre",

        "email": "client@email.com",

        "phone": "50937000000"

    },

    metadata={

        "order_id": "ORDER_001"

    }

)

Paramètres disponibles

Réponse paiement

JSON
content_copy
{
  "id": "pay_123",
  "status": "pending",
  "url": "https://checkout.kobara.app/pay/123",
  "amount": 2500,
  "currency": "HTG"
}

Vérifier un paiement

PYTHON
content_copy
payment = client.payments.retrieve(
    "pay_123"
)

Exemple réponse

JSON
content_copy
{
  "id": "pay_123",
  "status": "succeeded",
  "amount": 2500
}

Lister les paiements

PYTHON
content_copy
payments = client.payments.list()

Payment Links

Créer des liens de paiement partageables.

PYTHON
content_copy
link = client.payment_links.create(

    amount=1500,

    currency="HTG",

    title="Paiement Boutique"

)

Réponse

JSON
content_copy
{
  "url":
  "https://pay.kobara.app/link/abc123"
}

Retraits

Créer un retrait MonCash.

PYTHON
content_copy
withdrawal = client.withdrawals.create(

    amount=5000,

    phone="50937000000"

)

Réponse retrait

JSON
content_copy
{
  "id": "wd_001",
  "status": "processing"
}

Webhooks

Le SDK Python aide à vérifier les signatures webhooks.

PYTHON
content_copy
event = client.webhooks.construct_event(

    payload,

    signature,

    os.environ.get(
        "KOBARA_WEBHOOK_SECRET"
    )

)

Exemple webhook FastAPI

PYTHON
content_copy
from fastapi import Request

@app.post("/webhook")
async def webhook(request: Request):

    payload = await request.body()

    signature = request.headers.get(
        "kobara-signature"
    )

    try:

        event = client.webhooks.construct_event(

            payload,

            signature,

            os.environ.get(
                "KOBARA_WEBHOOK_SECRET"
            )

        )

        print(event)

        return {"success": True}

    except Exception as e:

        return {
            "error": str(e)
        }

Types d’événements

Gestion des erreurs

Le SDK retourne des erreurs propres.

PYTHON
content_copy
try:

    payment = client.payments.create(...)

except Exception as error:

    print(str(error))

Exemple erreur

JSON
content_copy
{
  "error": {
    "code": "invalid_amount",
    "message": "Amount is required"
  }
}

Architecture recommandée

Correct

Terminal
content_copy
Frontend
↓
Backend Python
↓
Kobara SDK
↓
API Kobara
↓
MonCash / MonCash

Architecture incorrecte

Terminal
content_copy
Frontend
↓
MonCash directement

ou :

Terminal
content_copy
Frontend
↓
Secret Key Kobara

Bonnes pratiques

À faire

✅ utiliser .env ✅ utiliser HTTPS ✅ vérifier les webhooks ✅ utiliser backend sécurisé ✅ logger les erreurs

À éviter

❌ exposer Secret Key ❌ utiliser le SDK côté frontend ❌ appeler MonCash directement ❌ hardcoder les secrets

Exemple Django

PYTHON
content_copy
from django.http import JsonResponse
from kobara import Kobara
import os

client = Kobara(
    api_key=os.environ.get(
        "KOBARA_SECRET_KEY"
    )
)

def create_payment(request):

    payment = client.payments.create(

        amount=1000,

        currency="HTG"

    )

    return JsonResponse({

        "url": payment.url

    })

Exemple Flask

PYTHON
content_copy
from flask import Flask
from kobara import Kobara
import os

app = Flask(__name__)

client = Kobara(
    api_key=os.environ.get(
        "KOBARA_SECRET_KEY"
    )
)

@app.route("/checkout", methods=["POST"])
def checkout():

    payment = client.payments.create(

        amount=1000,

        currency="HTG"

    )

    return {
        "url": payment.url
    }