Payment Events (Webhooks)

For asynchronous payment flows (like QR Codes or Manual Crypto Transfers), the user doesn't leave your website. They simply scan the QR code on their phone, and your backend processes the payment in the background.

To update the frontend UI instantly when this happens, the SDK includes a Webhook Event Emitter.

Listening for Payment Updates

After you call initiateDeposit() and display a QR code, you should subscribe to payment updates. The SDK will listen for the backend webhook and fire this event.

// 1. Subscribe to payment updates
const unsubscribe = sdk.wallet.onPaymentUpdate((event) => {
  console.log(`Transaction ${event.transactionId} status: ${event.status}`);
  
  if (event.status === 'COMPLETED') {
    // Stop loading spinner
    // Show success message
    // Redirect to wallet or game lobby
    alert(`Deposit of $${event.amount} successful!`);
  } else if (event.status === 'FAILED') {
    alert('Payment failed or expired.');
  }
});

// 2. Initiate the deposit (e.g., UPI QR)
const intent = await sdk.wallet.initiateDeposit({
  methodId: 'upi_qr',
  amount: 20.00,
  currency: 'INR'
});

if (intent.status === 'REQUIRES_QR_SCAN') {
  showQRCodeOnScreen(intent.qrCode);
}

// 3. Cleanup (Important for React/Vue components)
// Call this function when the component unmounts to prevent memory leaks
// unsubscribe();

Payment Event Interface

interface PaymentEvent {
  transactionId: string;
  status: 'COMPLETED' | 'FAILED' | 'PENDING_VERIFICATION';
  amount: number;
  currency: string;
}

Best Practices

1. Always Subscribe First: Set up the onPaymentUpdate listener before calling initiateDeposit() to ensure you don't miss the event.
2. Cleanup: The onPaymentUpdate function returns an unsubscribe function. Make sure to call it when your component unmounts (e.g., in React's useEffect cleanup) to prevent duplicate listeners and memory leaks.
3. Balance Refresh: When a COMPLETED event fires, you may want to call sdk.wallet.getBalances() to fetch the absolute latest balance from the backend for UI accuracy.