WebSocket API

Real-time invoice status updates via WebSocket connection

Overview

BOSPay provides WebSocket support for real-time invoice status updates. Connect to receive instant notifications when invoice statuses change without polling.

WebSocket URL: wss://bospay-api-platform.azurewebsites.net/ws?apiKey=YOUR_API_KEY

Events

`invoice-status`

Emitted when an invoice status changes (pending → payment_detected → confirmed)

{
  "type": "invoice-status",
  "invoiceId": "string",
  "data": {
    "status": "pending | payment_detected | confirmed",
    "confirmed": "boolean",
    "txHash": "string",
    "tokenSymbol": "string",
    "cryptoAmount": "number",
    "fiatAmount": "number",
    "fiatCurrency": "string"
  }
}

Code Examples

Basic Connection

const ws = new WebSocket('wss://bospay-api-platform.azurewebsites.net/ws?apiKey=YOUR_API_KEY');

ws.onopen = () => {
  console.log('Connected to BOSPay WebSocket');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Subscribe to Invoice

// Subscribe to invoice updates
ws.send(JSON.stringify({
  type: 'subscribe',
  invoiceId: 'a360e938-e687-47c1-a4af-b3a336f9ec05'
}));

Event Example

{
  "type": "invoice-status",
  "invoiceId": "a360e938-e687-47c1-a4af-b3a336f9ec05",
  "data": {
    "status": "payment_detected",
    "confirmed": false,
    "txHash": "0x123...",
    "tokenSymbol": "USDT",
    "cryptoAmount": 8.75049,
    "fiatAmount": 150.75,
    "fiatCurrency": "ZAR"
  }
}

Using the Client Helper

import { BOSPayWebSocket } from '@bospay/api-client/lib/websocket';

const ws = new BOSPayWebSocket('your-api-key');

ws.on('invoice-status', (event) => {
  console.log('Invoice updated:', event);
});

await ws.connect();
ws.subscribe('invoice-id-123');

Methods

Subscribe to Invoice

Subscribe to receive real-time updates for a specific invoice.

{
  "type": "subscribe",
  "invoiceId": "string"
}

UNSUBSCRIBE

Unsubscribe from Invoice

Stop receiving updates for a specific invoice.

{
  "type": "unsubscribe",
  "invoiceId": "string"
}