Python SDK Integration - OneClickDz Flexy API

Overview

The Navio Python SDK provides a clean, idiomatic interface for integrating Navio payments into your Python applications. Built with Python 3.8+ type hints and dataclasses for the best developer experience.

Pythonic API

Clean interface with full type hints and dataclasses

Type safe

Full type annotations with dataclasses and enums

Input validation

Client-side validation for fast error feedback

Minimal dependencies

Only requires the requests package

Requirements

Python 3.8 or higher
pip

Installation

Install via pip:

pip install ocpay-python-sdk

Or install from source:

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

Quick start

1. Initialize the SDK

from ocpay import OCPay

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

Store your API key in environment variables, never hardcoded in source code.

2. Create a payment link

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. Check payment status

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}")

Complete e-commerce example

Full e-commerce order flow

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")

API reference

OCPay class

Main entry point for the SDK.

Constructor

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

string

required

Your OneClickDz API access token.

ClientOptions

Optional client configuration.

Show ClientOptions properties

int

Request timeout in seconds. Default: 30.

string

Custom base URL, mainly used for testing.

dict

Additional headers to include in every request.

Example:

from ocpay import OCPay, ClientOptions

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

`create_link(request)`

Creates a new payment link.

CreateLinkRequest

required

Payment link creation request.

Show CreateLinkRequest properties

ProductInfo

required

Product information.

Show ProductInfo properties

string

required

Product or service name (1–200 characters).

int

required

Amount in DZD (500–500,000). Must be a whole number.

string

Optional product description (max 1000 characters).

FeeMode

Who pays transaction fees. Default: FeeMode.NO_FEE.

string

Optional message shown to the customer after payment (max 500 characters).

string

Optional URL to redirect the customer after payment completes.

Returns:

string

The payment page URL to share with your customer.

string

Unique payment reference code (e.g., OCPL-A1B2C3-D4E5). Save this to track payment status.

Raises: ValidationException (400), UnauthorizedException (403), ApiException

`check_payment(payment_ref)`

Checks the status of a payment.

string

required

Payment reference code returned by create_link (e.g., "OCPL-A1B2C3-D4E5").

Returns:

PaymentStatus

Current payment status: PENDING, CONFIRMED, or FAILED.

string

Human-readable status message.

TransactionDetails

Confirmed transaction details. Only present when status is CONFIRMED.

Raises: NotFoundException (404), PaymentExpiredException (410), ApiException

Enums

FeeMode

Value	Description
`FeeMode.NO_FEE`	Merchant pays all fees (default)
`FeeMode.SPLIT_FEE`	Fees split 50/50 between merchant and customer
`FeeMode.CUSTOMER_FEE`	Customer pays all fees

PaymentStatus

Value	Description
`PaymentStatus.PENDING`	Payment is in progress
`PaymentStatus.CONFIRMED`	Payment completed successfully
`PaymentStatus.FAILED`	Payment was declined, expired, or cancelled

Exception classes

ValidationException - HTTP 400

Raised when the request data is invalid (e.g., amount out of range, missing required fields).Properties: message, status_code, request_id, error_data

UnauthorizedException - HTTP 403

Raised when authentication fails. Check that your API key is valid and active.Properties: message, status_code, request_id, error_data

NotFoundException - HTTP 404

Raised when the payment reference does not exist.Properties: message, status_code, request_id, error_data

PaymentExpiredException - HTTP 410

Raised when the payment link has expired. Links expire 20 minutes after creation.Properties: message, status_code, request_id, error_data

ApiException - various

Base exception for all other API errors. Catch this as a fallback.Properties: message, status_code, request_id, error_data

Error handling

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}")

Framework integration

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,
    }

Important notes

Merchant validation required - Complete merchant validation at app.oneclickdz.com/profile before using the API.

Amount limits - Minimum 500 DZD, maximum 500,000 DZD. Must be whole numbers (no decimals).

Link expiration - Payment links expire 20 minutes after creation. After expiration the status becomes FAILED.

Sandbox testing - Use your sandbox API key for testing. Check response.payment_link.is_sandbox to confirm test mode.

API reference

View the Navio API endpoints

Support

Contact our support team

GitHub

View the source on GitHub