paybridge 0.1.0

Unified payment gateway integration for Python

PayBridge Documentation

Unified payment gateway integration for Python developers.

PayBridge provides a single interface for integrating multiple payment gateways without rewriting payment logic for every provider.

---

Features

• Unified payment API
• Multiple gateway support
• Easy provider switching
• Fallback gateway handling
• Payment verification
• Refund support
• Webhook handling
• Scalable architecture
• Developer-friendly API
• FastAPI support

---

Supported Providers

• Paystack
• Flutterwave
• Stripe
• More coming soon

---

Installation

Install PayBridge using pip:

pip install paybridge

Upgrade to the latest version:

pip install --upgrade paybridge

---

Quick Start

Import PayBridge

from paybridge import PayBridge

---

Initialize a Provider

Paystack Example

paybridge = PayBridge(
    provider="paystack",
    secret_key="sk_test_xxxxxxxxx"
)

---

Initialize Payment

response = paybridge.initialize_payment(
    amount=5000,
    email="[e-mail]",
    currency="NGN",
    reference="TXN_001"
)

print(response)

---

Verify Payment

Always verify payments server-side after payment completion.

verification = paybridge.verify_payment(
    reference="TXN_001"
)

print(verification)

---

Charge a Customer

response = paybridge.charge(
    amount=10000,
    email="[e-mail]"
)

print(response)

---

Refund a Payment

refund = paybridge.refund(
    reference="TXN_001",
    amount=5000
)

print(refund)

---

Webhook Handling

Webhooks allow your application to receive real-time payment events.

Flask Example

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    payload = request.json

    print(payload)

    return {"status": "success"}

---

Using Multiple Gateways

One of PayBridge’s most powerful features is multi-gateway support.

This allows developers to:

• Create fallback systems
• Reduce downtime
• Route payments dynamically
• Improve reliability
• Avoid vendor lock-in

---

Initialize Multiple Providers

from paybridge import PayBridge

paystack = PayBridge(
    provider="paystack",
    secret_key="PAYSTACK_SECRET_KEY"
)

flutterwave = PayBridge(
    provider="flutterwave",
    secret_key="FLUTTERWAVE_SECRET_KEY"
)

---

Gateway Fallback Example

If one provider fails, automatically switch to another.

try:
    response = paystack.initialize_payment(
        amount=5000,
        email="[e-mail]"
    )

except Exception:
    response = flutterwave.initialize_payment(
        amount=5000,
        email="[e-mail]"
    )

print(response)

---

Dynamic Provider Selection

def get_provider(currency):
    if currency == "NGN":
        return paystack

    return flutterwave


provider = get_provider("NGN")

response = provider.initialize_payment(
    amount=10000,
    email="[e-mail]"
)

print(response)

---

Provider Configuration System

providers = {
    "paystack": PayBridge(
        provider="paystack",
        secret_key="PAYSTACK_SECRET"
    ),

    "flutterwave": PayBridge(
        provider="flutterwave",
        secret_key="FLUTTERWAVE_SECRET"
    )
}

Using a provider dynamically:

selected_provider = providers["paystack"]

response = selected_provider.initialize_payment(
    amount=5000,
    email="[e-mail]"
)

---

Smart Routing Example

def route_payment(amount):
    if amount > 100000:
        return flutterwave

    return paystack


provider = route_payment(5000)

response = provider.initialize_payment(
    amount=5000,
    email="[e-mail]"
)

---

Retry Logic Example

providers = [paystack, flutterwave]

for provider in providers:
    try:
        response = provider.initialize_payment(
            amount=5000,
            email="[e-mail]"
        )

        print("Payment initialized successfully")
        break

    except Exception as e:
        print(f"Provider failed: {e}")

---

FastAPI Integration

This section shows how to integrate PayBridge into a FastAPI application.

---

Install FastAPI Dependencies

pip install fastapi uvicorn

---

Basic FastAPI Integration

from fastapi import FastAPI
from paybridge import PayBridge

app = FastAPI()

paybridge = PayBridge(
    provider="paystack",
    secret_key="sk_test_xxxxxxxxx"
)


@app.get("/")
async def home():
    return {"message": "PayBridge API Running"}


@app.post("/initialize-payment")
async def initialize_payment():

    response = paybridge.initialize_payment(
        amount=5000,
        email="[e-mail]",
        currency="NGN",
        reference="TXN_001"
    )

    return response

---

Run FastAPI Server

uvicorn main:app --reload

---

FastAPI Verify Payment Example

@app.get("/verify-payment/{reference}")
async def verify_payment(reference: str):

    verification = paybridge.verify_payment(
        reference=reference
    )

    return verification

---

FastAPI Request Body Example

from pydantic import BaseModel


class PaymentRequest(BaseModel):
    amount: int
    email: str
    currency: str = "NGN"


@app.post("/pay")
async def pay(data: PaymentRequest):

    response = paybridge.initialize_payment(
        amount=data.amount,
        email=data.email,
        currency=data.currency
    )

    return response

---

FastAPI Multi-Gateway Example

from fastapi import FastAPI
from paybridge import PayBridge

app = FastAPI()

paystack = PayBridge(
    provider="paystack",
    secret_key="PAYSTACK_SECRET"
)

flutterwave = PayBridge(
    provider="flutterwave",
    secret_key="FLUTTERWAVE_SECRET"
)


@app.post("/payment")
async def payment():

    try:
        response = paystack.initialize_payment(
            amount=5000,
            email="[e-mail]"
        )

    except Exception:

        response = flutterwave.initialize_payment(
            amount=5000,
            email="[e-mail]"
        )

    return response

---

FastAPI Dynamic Routing Example

def get_provider(currency: str):

    if currency == "NGN":
        return paystack

    return flutterwave


@app.post("/dynamic-payment")
async def dynamic_payment(data: PaymentRequest):

    provider = get_provider(data.currency)

    response = provider.initialize_payment(
        amount=data.amount,
        email=data.email,
        currency=data.currency
    )

    return response

---

FastAPI Webhook Example

from fastapi import Request


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

    payload = await request.json()

    print(payload)

    return {
        "status": "success"
    }

---

FastAPI Refund Example

@app.post("/refund/{reference}")
async def refund(reference: str):

    response = paybridge.refund(
        reference=reference,
        amount=5000
    )

    return response

---

Environment Variables

Never hardcode secret keys in production.

Example .env

PAYSTACK_SECRET_KEY=sk_test_xxxxx
FLUTTERWAVE_SECRET_KEY=FLWSECK_TEST_xxxxx

---

Using python-dotenv

from dotenv import load_dotenv
import os

load_dotenv()

secret_key = os.getenv("PAYSTACK_SECRET_KEY")

---

Full Integration Example

from paybridge import PayBridge

paybridge = PayBridge(
    provider="paystack",
    secret_key="sk_test_xxxxx"
)

payment = paybridge.initialize_payment(
    amount=5000,
    email="[e-mail]",
    currency="NGN",
    reference="TXN_001"
)

print(payment)

---

Recommended Architecture

Client Request
      ↓
FastAPI Routes
      ↓
Payment Service
      ↓
Provider Router
      ↓
Paystack / Flutterwave / Stripe

This architecture provides:

• Scalability
• Reliability
• Easier maintenance
• Better failover handling

---

Error Handling

Always handle payment failures properly.

try:
    response = paybridge.initialize_payment(
        amount=5000,
        email="[e-mail]"
    )

    print(response)

except Exception as e:
    print(f"Payment failed: {e}")

---

FastAPI Error Handling

from fastapi import HTTPException


@app.post("/safe-payment")
async def safe_payment():

    try:

        response = paybridge.initialize_payment(
            amount=5000,
            email="[e-mail]"
        )

        return response

    except Exception as e:

        raise HTTPException(
            status_code=400,
            detail=str(e)
        )

---

Best Practices

• Always verify payments server-side
• Use environment variables for secret keys
• Implement webhook verification
• Add retry mechanisms
• Log failed transactions
• Monitor provider downtime
• Use fallback gateways
• Track transaction success rates
• Separate payment logic into services

---

Why PayBridge?

PayBridge helps developers:

• Reduce integration complexity
• Switch providers easily
• Build scalable fintech systems faster
• Avoid vendor lock-in
• Maintain cleaner codebases

---

Contributing

Contributions are welcome.

Steps

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to your fork
5. Open a pull request

---

License

MIT License

---

Support

GitHub Repository:

https://github.com/zinsu-moni/paybridge

Issues:

https://github.com/zinsu-moni/paybridge/issues