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)

access_token

string

required

Your OneClickDz API access token.

options

ClientOptions

Optional client configuration.

Show ClientOptions properties

timeout

int

Request timeout in seconds. Default: 30.

base_url

string

Custom base URL, mainly used for testing.

headers

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.

request

CreateLinkRequest

required

Payment link creation request.

Show CreateLinkRequest properties

product_info

ProductInfo

required

Product information.

Show ProductInfo properties

title

string

required

Product or service name (1–200 characters).

amount

int

required

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

description

string

Optional product description (max 1000 characters).

fee_mode

FeeMode

Who pays transaction fees. Default: FeeMode.NO_FEE.

success_message

string

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

redirect_url

string

Optional URL to redirect the customer after payment completes.

Returns:

payment_url

string

The payment page URL to share with your customer.

payment_ref

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.

payment_ref

string

required

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

Returns:

status

PaymentStatus

Current payment status: PENDING, CONFIRMED, or FAILED.

message

string

Human-readable status message.

transaction_details

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

Navio Integration

Documentation Index

​Overview

Pythonic API

Type safe

Input validation

Minimal dependencies

​Requirements

​Installation

​Quick start

​1. Initialize the SDK

​2. Create a payment link

​3. Check payment status

​Complete e-commerce example

​API reference

​OCPay class

​Constructor

​create_link(request)

​check_payment(payment_ref)

​Enums

​FeeMode

​PaymentStatus

​Exception classes

​Error handling

​Framework integration

​Important notes

API reference

Support

GitHub

Overview

Requirements

Installation

Quick start

1. Initialize the SDK

2. Create a payment link

3. Check payment status

Complete e-commerce example

API reference

OCPay class

Constructor

`create_link(request)`

`check_payment(payment_ref)`

Enums

FeeMode

PaymentStatus

Exception classes

Error handling

Framework integration

Important notes