Intégration SDK Python - OneClickDz Flexy API

Vue d’ensemble

Le SDK Navio Python fournit une interface claire et idiomatique pour intégrer les paiements Navio dans vos applications Python. Conçu avec les annotations de type Python 3.8+ et les dataclasses pour la meilleure expérience développeur.

API Pythonique

Interface claire avec annotations de type complètes et dataclasses

Type Safe

Annotations de type complètes avec dataclasses et enums

Validation des entrées

Validation côté client pour un retour d’erreur rapide

Dépendances minimales

Ne requiert que le package requests

Prérequis

Python 3.8 ou supérieur
pip

Installation

Installez via pip :

pip install ocpay-python-sdk

Ou installez depuis les sources :

git clone https://github.com/oneclickdz/ocpay-python-sdk.git
cd ocpay-python-sdk
pip install -e .

Démarrage rapide

1. Initialiser le SDK

from ocpay import OCPay

ocpay = OCPay("your-api-access-token")

Stockez votre clé API dans des variables d’environnement, jamais codée en dur dans le code source.

2. Créer un lien de paiement

from ocpay import OCPay, FeeMode
from ocpay.types import ProductInfo, CreateLinkRequest

ocpay = OCPay("your-api-key")

request = CreateLinkRequest(
    product_info=ProductInfo(
        title="Premium Subscription",
        amount=5000,  # Amount in DZD (500–500,000)
        description="Monthly access to all premium features",
    ),
    fee_mode=FeeMode.NO_FEE,
    success_message="Thank you for your purchase!",
    redirect_url="https://yourstore.com/success?orderId=12345",
)

response = ocpay.create_link(request)

# Share this URL with your customer
print("Payment URL:", response.payment_url)

# Save this reference for tracking
print("Payment Reference:", response.payment_ref)

3. Vérifier le statut du paiement

from ocpay import OCPay

ocpay = OCPay("your-api-key")

status = ocpay.check_payment("OCPL-A1B2C3-D4E5")

if status.is_confirmed():
    print("Payment confirmed!")
    if status.transaction_details:
        print(f"Amount: {status.transaction_details.amount} DZD")
elif status.is_pending():
    print("Payment still pending...")
elif status.is_failed():
    print(f"Payment failed: {status.message}")

Exemple e-commerce complet

Flux e-commerce complet

from ocpay import (
    OCPay,
    FeeMode,
    ValidationException,
    ApiException,
)
from ocpay.types import ProductInfo, CreateLinkRequest

# Initialize SDK
ocpay = OCPay("your-api-key")

# Step 1: Create payment link for your order
order_id = "ORD-12345"
response = ocpay.create_link(CreateLinkRequest(
    product_info=ProductInfo(
        title=f"Order #{order_id}",
        amount=8000,
        description=f"Payment for order #{order_id}",
    ),
    fee_mode=FeeMode.NO_FEE,
    success_message=f"Thank you! Your order #{order_id} is being processed.",
    redirect_url=f"https://yourstore.com/orders/{order_id}/success",
))

# Step 2: Save payment reference to your database
print(f"Payment URL: {response.payment_url}")
print(f"Payment Ref: {response.payment_ref}")

# Step 3: Check payment status (in webhook or polling job)
status = ocpay.check_payment(response.payment_ref)

if status.is_confirmed():
    print("✅ Payment confirmed - fulfilling order")
elif status.is_failed():
    print("❌ Payment failed")
else:
    print("⏳ Payment is pending")

Référence API

Classe OCPay

Point d’entrée principal du SDK.

Constructeur

OCPay(access_token: str, options: ClientOptions = None)

access_token

string

requis

Votre token d’accès API OneClickDz.

options

ClientOptions

Configuration optionnelle du client.

Afficher Propriétés de ClientOptions

timeout

int

Délai de la requête en secondes. Défaut : 30.

base_url

string

URL de base personnalisée, principalement utilisée pour les tests.

headers

dict

En-têtes supplémentaires à inclure dans chaque requête.

Exemple :

from ocpay import OCPay, ClientOptions

ocpay = OCPay("your-api-key", options=ClientOptions(timeout=60))

`create_link(request)`

Crée un nouveau lien de paiement.

request

CreateLinkRequest

requis

Requête de création de lien de paiement.

Afficher Propriétés de CreateLinkRequest

product_info

ProductInfo

requis

Informations sur le produit.

Afficher Propriétés de ProductInfo

title

string

requis

Nom du produit ou service (1–200 caractères).

amount

int

requis

Montant en DZD (500–500 000). Doit être un nombre entier.

description

string

Description optionnelle du produit (max 1000 caractères).

fee_mode

FeeMode

Qui paie les frais de transaction. Défaut : FeeMode.NO_FEE.

success_message

string

Message optionnel affiché au client après le paiement (max 500 caractères).

redirect_url

string

URL optionnelle pour rediriger le client après le paiement.

Retourne :

payment_url

string

L’URL de la page de paiement à partager avec votre client.

payment_ref

string

Code de référence de paiement unique (ex. OCPL-A1B2C3-D4E5). Sauvegardez-le pour suivre le statut du paiement.

Lève : ValidationException (400), UnauthorizedException (403), ApiException

`check_payment(payment_ref)`

Vérifie le statut d’un paiement.

payment_ref

string

requis

Code de référence de paiement retourné par create_link (ex. "OCPL-A1B2C3-D4E5").

Retourne :

status

PaymentStatus

Statut actuel du paiement : PENDING, CONFIRMED ou FAILED.

message

string

Message de statut lisible par l’humain.

transaction_details

TransactionDetails

Détails de la transaction confirmée. Présent uniquement quand status est CONFIRMED.

Lève : NotFoundException (404), PaymentExpiredException (410), ApiException

Enums

FeeMode

Valeur	Description
`FeeMode.NO_FEE`	Le marchand paie tous les frais (défaut)
`FeeMode.SPLIT_FEE`	Frais partagés 50/50 entre marchand et client
`FeeMode.CUSTOMER_FEE`	Le client paie tous les frais

PaymentStatus

Valeur	Description
`PaymentStatus.PENDING`	Le paiement est en cours
`PaymentStatus.CONFIRMED`	Le paiement s’est terminé avec succès
`PaymentStatus.FAILED`	Le paiement a été refusé, expiré ou annulé

Classes d’exception

ValidationException - HTTP 400

Levée quand les données de la requête sont invalides (ex. montant hors limites, champs requis manquants).Propriétés : message, status_code, request_id, error_data

UnauthorizedException - HTTP 403

Levée quand l’authentification échoue. Vérifiez que votre clé API est valide et active.Propriétés : message, status_code, request_id, error_data

NotFoundException - HTTP 404

Levée quand la référence de paiement n’existe pas.Propriétés : message, status_code, request_id, error_data

PaymentExpiredException - HTTP 410

Levée quand le lien de paiement a expiré. Les liens expirent 20 minutes après la création.Propriétés : message, status_code, request_id, error_data

ApiException - divers

Exception de base pour toutes les autres erreurs API. Capturez-la comme fallback.Propriétés : message, status_code, request_id, error_data

Gestion des erreurs

from ocpay import (
    OCPay,
    ApiException,
    ValidationException,
    UnauthorizedException,
    NotFoundException,
    PaymentExpiredException,
)

ocpay = OCPay("your-api-key")

try:
    response = ocpay.create_link(request)
except ValidationException as e:
    print(f"Validation error: {e.message}")
    print(f"Request ID: {e.request_id}")
except UnauthorizedException as e:
    print("Authentication failed. Check your API key.")
except NotFoundException as e:
    print(f"Not found: {e.message}")
except PaymentExpiredException as e:
    print(f"Payment expired: {e.message}")
except ApiException as e:
    print(f"API error: {e.message} (status {e.status_code})")
    print(f"Request ID: {e.request_id}")

Intégration avec les frameworks

Flask
Django
FastAPI

from flask import Flask, jsonify, request
from ocpay import OCPay, FeeMode
from ocpay.types import CreateLinkRequest, ProductInfo

app = Flask(__name__)
ocpay = OCPay("your-api-key")

@app.route("/api/payment", methods=["POST"])
def create_payment():
    data = request.json
    response = ocpay.create_link(CreateLinkRequest(
        product_info=ProductInfo(
            title=data["title"],
            amount=data["amount"],
        ),
        fee_mode=FeeMode.NO_FEE,
    ))
    return jsonify({
        "payment_url": response.payment_url,
        "payment_ref": response.payment_ref,
    })

from ocpay import OCPay, FeeMode
from ocpay.types import CreateLinkRequest, ProductInfo

ocpay = OCPay(settings.OCPAY_API_KEY)

def create_order_payment(order):
    response = ocpay.create_link(CreateLinkRequest(
        product_info=ProductInfo(
            title=f"Order #{order.id}",
            amount=order.total,
        ),
        fee_mode=FeeMode.NO_FEE,
        redirect_url=f"https://yourstore.com/orders/{order.id}/success",
    ))
    order.payment_ref = response.payment_ref
    order.save()
    return response.payment_url

from fastapi import FastAPI
from ocpay import OCPay, FeeMode
from ocpay.types import CreateLinkRequest, ProductInfo

app = FastAPI()
ocpay = OCPay("your-api-key")

@app.post("/api/payment")
async def create_payment(title: str, amount: int):
    response = ocpay.create_link(CreateLinkRequest(
        product_info=ProductInfo(title=title, amount=amount),
        fee_mode=FeeMode.NO_FEE,
    ))
    return {
        "payment_url": response.payment_url,
        "payment_ref": response.payment_ref,
    }

Notes importantes

Validation du marchand requise - Complétez la validation du marchand sur app.oneclickdz.com/profile avant d’utiliser l’API.

Limites de montant - Minimum 500 DZD, maximum 500 000 DZD. Doit être un nombre entier (pas de décimales).

Expiration du lien - Les liens de paiement expirent 20 minutes après leur création. Après expiration, le statut devient FAILED.

Tests en Sandbox - Utilisez votre clé API sandbox pour les tests. Vérifiez response.payment_link.is_sandbox pour confirmer le mode test.

Référence API

Voir les endpoints API Navio

Support

Contacter notre équipe de support

GitHub

Voir le code source sur GitHub

Intégration Navio

Documentation Index

​Vue d’ensemble

API Pythonique

Type Safe

Validation des entrées

Dépendances minimales

​Prérequis

​Installation

​Démarrage rapide

​1. Initialiser le SDK

​2. Créer un lien de paiement

​3. Vérifier le statut du paiement

​Exemple e-commerce complet

​Référence API

​Classe OCPay

​Constructeur

​create_link(request)

​check_payment(payment_ref)

​Enums

​FeeMode

​PaymentStatus

​Classes d’exception

​Gestion des erreurs

​Intégration avec les frameworks

​Notes importantes

Référence API

Support

GitHub

Vue d’ensemble

Prérequis

Installation

Démarrage rapide

1. Initialiser le SDK

2. Créer un lien de paiement

3. Vérifier le statut du paiement

Exemple e-commerce complet

Référence API

Classe OCPay

Constructeur

`create_link(request)`

`check_payment(payment_ref)`

Enums

FeeMode

PaymentStatus

Classes d’exception

Gestion des erreurs

Intégration avec les frameworks

Notes importantes