osuvox Payments API

{
  "data": {
    "BTC": 43250.25,
    "LTC": 72.45,
    "DOGE": 0.078
  },
  "currency": "USD",
  "timestamp": 1705152000000
}

{
  "id": "pay_abc123def456",
  "status": "confirmed",
  "coin": "BTC",
  "amount_requested": "0.00100000",
  "amount_received": "0.00100000",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "txid": "a1b2c3d4e5f6789012345678901234567890abcdef",
  "external_id": "order_12345",
  "description": "Premium subscription",
  "confirmations_required": 3,
  "confirmations": 6,
  "metadata": { "customer_id": "cust_abc" },
  "payment_url": "https://www.osuvox.net/pay/pay_abc123def456",
  "qr_code_url": "https://www.osuvox.net/api/qr/pay_abc123def456",
  "expires_at": "2026-01-11T22:30:00Z",
  "created_at": "2026-01-11T21:30:00Z",
  "detected_at": "2026-01-11T21:45:00Z",
  "confirmed_at": "2026-01-11T22:15:00Z",
  "completed_at": null
}

{
  "data": [
    {
      "id": "pay_abc123def456",
      "status": "confirmed",
      "coin": "BTC",
      "amount_requested": "0.00100000",
      "amount_received": "0.00100000",
      "external_id": "order_12345",
      "created_at": "2026-01-11T21:30:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

{
  "id": "evt_ghi789",
  "type": "payment.completed",
  "created_at": "2026-01-11T22:20:00Z",
  "data": {
    "payment": {
      "id": "pay_abc123",
      "status": "completed"
    },
    "payouts": [
      {
        "address": "bc1q_vendor...",
        "amount": "0.00085000",
        "txid": "payout_tx_1...",
        "label": "Vendor",
        "percentage": 85
      },
      {
        "address": "bc1q_platform...",
        "amount": "0.00015000",
        "txid": "payout_tx_2...",
        "label": "Platform Fee",
        "percentage": 15
      }
    ]
  }
}

import hmac
import hashlib
import time

def verify_webhook_signature(payload: str, signature_header: str, secret: str) -> bool:
    parts = dict(p.split('=', 1) for p in signature_header.split(','))
    timestamp = int(parts['t'])
    provided_sig = parts['v1']
    
    # Check timestamp (5 minute tolerance)
    if abs(time.time() - timestamp) > 300:
        return False
    
    # Compute signature
    signed_payload = f"{timestamp}.{payload}"
    expected_sig = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected_sig, provided_sig)

# Flask handler
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Osuvox-Signature')
    payload = request.get_data(as_text=True)
    
    if not verify_webhook_signature(payload, signature, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    
    event = request.json
    
    if event['type'] == 'payment.confirmed':
        fulfill_order(event['data']['payment']['external_id'])
    
    return 'OK', 200

// osuvox-types.ts

export type OsuvoxCoin = 'BTC' | 'LTC' | 'DOGE';

export type PaymentStatus = 
  | 'pending' 
  | 'detecting' 
  | 'confirming' 
  | 'confirmed' 
  | 'completed' 
  | 'expired' 
  | 'failed';

export type WebhookEventType = 
  | 'payment.detected'
  | 'payment.confirmed'
  | 'payment.completed'
  | 'payment.expired'
  | 'payment.failed';

export interface CreatePaymentParams {
  amount: string | number;
  coin: OsuvoxCoin;
  external_id?: string;
  description?: string;
  metadata?: Record<string, unknown>;
  webhook_url?: string;
  expires_in?: number;
  confirmations?: number;
  success_url?: string;  // Hosted checkout: redirect after payment confirmed
  cancel_url?: string;   // Hosted checkout: redirect if cancelled/expired
}

export interface GetPricesResponse {
  data: Record<OsuvoxCoin, number>;
  currency: 'USD';
  timestamp: number;
}

export interface OsuvoxPayment {
  id: string;
  status: PaymentStatus;
  coin: OsuvoxCoin;
  amount_requested: string;
  amount_received: string;
  address: string;
  txid: string | null;
  external_id: string | null;
  description: string | null;
  confirmations: number;
  confirmations_required: number;
  metadata: Record<string, unknown> | null;
  payment_url: string;
  qr_code_url: string;
  expires_at: string | null;
  created_at: string;
  detected_at: string | null;
  confirmed_at: string | null;
  completed_at: string | null;
}

export interface OsuvoxWebhookEvent {
  id: string;
  type: WebhookEventType;
  created_at: string;
  data: {
    payment: OsuvoxPayment;
    payouts?: Array<{
      address: string;
      amount: string;
      txid: string | null;
      label: string;
      percentage: number;
    }>;
  };
}

export interface OsuvoxError {
  error: {
    code: string;
    message: string;
    param?: string;
  };
}