Session 4: CLI Tool, Hosted Checkout, and API Documentation

zerofee --help

Usage: zerofee [OPTIONS] COMMAND [ARGS]...

  0fee.dev CLI - Payment orchestration from the terminal.

Commands:
  login              Authenticate with your API key
  logout             Clear stored credentials
  status             Check API connection status
  listen             Forward webhooks to your local server
  payments create    Create a test payment
  payments list      List recent payments
  payments get       Get payment details by ID
  payments cancel    Cancel a pending payment
  logs tail          Stream real-time event logs
  config show        Show current configuration
  config set         Update a configuration value
  trigger            Trigger a test webhook event

bash$ zerofee login
Enter your API key: sk_test_abc123...

Authenticating... Done.
Environment: sandbox
Connected to: api.0fee.dev
API version: v1

Your credentials have been saved to ~/.zerofee/config.json

bash$ zerofee payments create \
    --amount 5000 \
    --method PAYIN_ORANGE_CI \
    --phone +2250709757296

Creating payment...

Payment Created
+------------------+---------------------------+
| Field            | Value                     |
+------------------+---------------------------+
| ID               | txn_749b8b1afbd846eaba95  |
| Status           | pending                   |
| Amount           | 5,000 XOF                |
| Provider         | paiementpro               |
| Payment Method   | PAYIN_ORANGE_CI           |
| Customer Phone   | +2250709757296            |
| Created          | 2025-12-10 14:32:08 UTC   |
+------------------+---------------------------+

Waiting for status update... (Ctrl+C to stop)
[14:32:10] Status: pending
[14:32:15] Status: pending
[14:32:20] Status: completed

Payment completed successfully.

bash$ zerofee listen --forward-to http://localhost:3000/webhooks

Listening for webhook events on your 0fee.dev account...
Ready! Forwarding to http://localhost:3000/webhooks

[14:35:02] payment.created    txn_749b... -> 200 OK (42ms)
[14:35:08] payment.completed  txn_749b... -> 200 OK (38ms)
[14:36:15] checkout.completed cs_abc1... -> 200 OK (51ms)

python# cli/zerofee_cli/main.py (simplified)
import typer
import httpx
from rich.console import Console
from rich.table import Table

app = typer.Typer(help="0fee.dev CLI")
console = Console()

@app.command()
def listen(
    forward_to: str = typer.Option(
        "http://localhost:3000/webhooks",
        "--forward-to", "-f",
        help="Local URL to forward webhooks to"
    )
):
    """Forward webhooks to your local development server."""
    config = load_config()
    api_key = config.get("api_key")

    if not api_key:
        console.print("[red]Not authenticated. Run 'zerofee login' first.[/red]")
        raise typer.Exit(1)

    console.print(f"Listening for webhook events...")
    console.print(f"Ready! Forwarding to [cyan]{forward_to}[/cyan]\n")

    try:
        # Try WebSocket first
        asyncio.run(listen_websocket(api_key, forward_to))
    except Exception:
        # Fall back to polling
        console.print("[yellow]WebSocket unavailable, using polling...[/yellow]")
        asyncio.run(listen_polling(api_key, forward_to))

bash$ zerofee logs tail --limit 20

Streaming events (most recent first)...

[14:36:15] checkout.completed  cs_abc123   amount=10000 XOF
[14:35:08] payment.completed   txn_749b8b  provider=paiementpro
[14:35:02] payment.created     txn_749b8b  method=PAYIN_ORANGE_CI
[14:30:45] payment.failed      txn_663a2c  error=timeout

bash$ zerofee config show

Configuration (~/.zerofee/config.json)
+------------------+---------------------------+
| Key              | Value                     |
+------------------+---------------------------+
| api_key          | sk_test_****abc           |
| environment      | sandbox                   |
| api_url          | https://api.0fee.dev      |
| output_format    | table                     |
+------------------+---------------------------+

$ zerofee config set output_format json
Updated output_format = json

cli/
├── pyproject.toml            # Package config, entry point
├── README.md                 # CLI documentation
└── zerofee_cli/
    ├── __init__.py
    ├── config.py             # Config file management
    ├── api.py                # HTTP client wrapper
    └── main.py               # All CLI commands

python# backend/routes/checkout_hosted.py
from fastapi import APIRouter, Request
from fastapi.responses import HTMLResponse
from fastapi.templating import Jinja2Templates

router = APIRouter()
templates = Jinja2Templates(directory="backend/templates")

@router.get("/v1/checkout/pay/{session_id}", response_class=HTMLResponse)
async def render_checkout(request: Request, session_id: str):
    """Render the hosted checkout page."""
    session = await get_checkout_session(session_id)

    if not session:
        return templates.TemplateResponse(
            "checkout_error.html",
            {"request": request, "error": "Session not found"},
            status_code=404
        )

    if session["status"] in ("completed", "expired"):
        return templates.TemplateResponse(
            "checkout_error.html",
            {
                "request": request,
                "error": f"This checkout session has {session['status']}."
            }
        )

    # Detect language from Accept-Language header
    accept_lang = request.headers.get("accept-language", "en")
    lang = "fr" if "fr" in accept_lang else "en"

    # Get payment methods for the session's country
    methods = await get_payment_methods_for_country(
        session.get("country", "CI")
    )

    return templates.TemplateResponse(
        "checkout.html",
        {
            "request": request,
            "session": session,
            "methods": methods,
            "lang": lang,
        }
    )

@router.post("/v1/checkout/{session_id}/pay")
async def process_checkout_payment(session_id: str, data: dict):
    """Process a payment from the hosted checkout page."""
    session = await get_checkout_session(session_id)

    payment = await initiate_payment(
        app_id=session["app_id"],
        amount=session["amount"],
        currency=session["currency"],
        payment_method=data["payment_method"],
        customer=data["customer"],
    )

    return {"payment_id": payment["id"], "status": payment["status"]}

@router.get("/v1/checkout/{session_id}/status")
async def poll_checkout_status(session_id: str):
    """Poll for payment status (used by the checkout page JS)."""
    session = await get_checkout_session(session_id)
    return {"status": session["status"]}

html<!-- Simplified structure of checkout.html -->
<!DOCTYPE html>
<html lang="{{ lang }}" data-theme="light">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ i18n.checkout_title }} - 0fee.dev</title>
    <style>
        /* Embedded Tailwind-like utility CSS + custom checkout styles */
        /* Dark mode support via data-theme attribute */
    </style>
</head>
<body>
    <div id="checkout-container">
        <!-- Step 1: Payment Method Selection -->
        <div id="step-methods" class="checkout-step active">
            <h2>{{ i18n.select_method }}</h2>
            <div class="method-grid">
                {% for method in methods %}
                <button class="method-card" data-method="{{ method.code }}">
                    <span class="method-name">{{ method.name }}</span>
                </button>
                {% endfor %}
            </div>
        </div>

        <!-- Step 2: Phone Number -->
        <div id="step-phone" class="checkout-step">
            <h2>{{ i18n.enter_phone }}</h2>
            <input type="tel" id="phone-input"
                   placeholder="{{ i18n.phone_placeholder }}" />
            <button onclick="submitPhone()">{{ i18n.continue }}</button>
        </div>

        <!-- Step 3: OTP (if required) -->
        <div id="step-otp" class="checkout-step">
            <h2>{{ i18n.enter_otp }}</h2>
            <input type="text" id="otp-input" maxlength="6" />
            <button onclick="submitOtp()">{{ i18n.verify }}</button>
        </div>

        <!-- Step 4: Processing -->
        <div id="step-processing" class="checkout-step">
            <div class="spinner"></div>
            <p>{{ i18n.processing }}</p>
        </div>

        <!-- Step 5: Result -->
        <div id="step-result" class="checkout-step"></div>
    </div>

    <script>
        const SESSION_ID = "{{ session.id }}";
        const API_URL = "/v1/checkout";

        // Multi-step flow logic
        // Payment polling
        // OTP handling
        // ... (embedded JavaScript)
    </script>
</body>
</html>

pythonTRANSLATIONS = {
    "en": {
        "checkout_title": "Checkout",
        "select_method": "Select payment method",
        "enter_phone": "Enter your phone number",
        "phone_placeholder": "+225 07 09 75 72 96",
        "enter_otp": "Enter the code sent to your phone",
        "continue": "Continue",
        "verify": "Verify",
        "processing": "Processing your payment...",
        "success": "Payment successful!",
        "failed": "Payment failed. Please try again.",
    },
    "fr": {
        "checkout_title": "Paiement",
        "select_method": "Choisissez votre moyen de paiement",
        "enter_phone": "Entrez votre numero de telephone",
        "phone_placeholder": "+225 07 09 75 72 96",
        "enter_otp": "Entrez le code recu par SMS",
        "continue": "Continuer",
        "verify": "Verifier",
        "processing": "Traitement de votre paiement...",
        "success": "Paiement reussi !",
        "failed": "Le paiement a echoue. Veuillez reessayer.",
    },
}

python# Python verification example
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

javascript// Node.js verification example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(`sha256=${expected}`),
        Buffer.from(signature)
    );
}