Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coinvoyage.io/llms.txt

Use this file to discover all available pages before exploring further.

useOrderStatusWS subscribes to PayOrder status events over the CoinVoyage backend WebSocket from inside a React component. Use it when you need live payment state outside the default PayButton lifecycle callbacks, such as a custom checkout page, payment status panel, or embedded dashboard view.
useOrderStatusWS must run inside PayKitProvider because it uses the configured backend API client from context.

​
Import

import { useOrderStatusWS } from "@coin-voyage/paykit";

​
Basic usage

"use client";

import { useState } from "react";
import { useOrderStatusWS } from "@coin-voyage/paykit";

export function OrderStatusPanel({ orderId }: { orderId?: string }) {
  const [connected, setConnected] = useState(false);

  useOrderStatusWS({
    orderId,
    enabled: Boolean(orderId),
    onConnectedChange: setConnected,
    onEvent: (event) => {
      console.log("PayOrder event:", event);
    },
    onError: (error) => {
      console.error("Order status stream failed:", error);
    },
  });

  return <p>{connected ? "Connected" : "Connecting"}</p>;
}

​
Options

​
orderId
string
PayOrder ID to subscribe to. The hook does not connect until orderId is available.
​
enabled
boolean
default:"true"
Controls whether the WebSocket should be active. Set this to false to pause the subscription without unmounting the component.
​
onEvent
(event: PayOrderEvent) => void
Called for each PayOrder event delivered by the backend WebSocket.
​
onError
(error: unknown) => void
Called when the WebSocket errors, authentication times out, or the backend returns an error message.
​
onConnectedChange
(connected: boolean) => void
Called when the connection becomes authenticated or disconnects.

​
Behavior

  • Connects only when enabled is true and orderId is present.
  • Subscribes to the specified PayOrder after the WebSocket opens.
  • Waits for backend authentication before reporting connected: true.
  • Reconnects with exponential backoff after close, error, or authentication timeout.
  • Cleans up timers and closes the socket when the component unmounts or dependencies change.
Use this hook for UI responsiveness only. Fulfillment should still be driven by verified webhooks on your server.