Widget Integration Guide

iBuyVoi Widget Integration

Integrate VOI purchases directly into your website with our embeddable widget. Support for iframe embedding and redirect flows with secure postMessage communication.

Quick Start

1. Basic Iframe Embedding

The simplest way to add VOI purchases to your site. Just replace VOI_WALLET_ADDRESS with your destination wallet. The widget enforces a $2 minimum purchase by default, or use the minimum parameter to set a custom amount.

<!-- Basic Widget Embedding -->
<iframe
  src="https://ibuyvoi.com/widget?destination=VOI_WALLET_ADDRESS&theme=light"
  width="480"
  height="600"
  frameborder="0"
  style="border-radius: 16px;"
  title="VOI Purchase Widget">
</iframe>

<!-- Widget with Custom Minimum Amount -->
<iframe
  src="https://ibuyvoi.com/widget?destination=VOI_WALLET_ADDRESS&minimum=10"
  width="480"
  height="600"
  frameborder="0"
  style="border-radius: 16px;"
  title="VOI Purchase Widget">
</iframe>

2. Redirect Mode

For mobile-first experiences or when iframes aren't suitable. Users are redirected to complete the purchase and returned with transaction results. Use the siteName parameter to show a branded return message after completion.

Perfect for:

• Mobile checkout flows
• Payment buttons in product pages
• Situations where iframe security is restricted

URL Parameters

/* Widget URL Parameters */

// Required Parameters
destination: string      // VOI wallet address (58 characters)

// Optional Parameters
mode: 'popup' | 'redirect'        // Payment mode (default: 'popup')
theme: 'light' | 'dark' | 'auto'  // Widget theme (default: 'light')
redirectUrl: string               // Custom redirect URL (redirect mode only)
siteName: string                  // Site name for redirect completion display
allowedOrigin: string             // Allowed origin for postMessage security
minimum: number                   // Minimum purchase amount in USD (default: 2)

/* Example URLs */

// Basic widget
https://ibuyvoi.com/widget?destination=H7W63MIQJMYBOEYPM5NJEGX3P54H54RZIV2G3OQ2255AULG6U74BE5KFC4

// Dark theme widget
https://ibuyvoi.com/widget?destination=ADDRESS&theme=dark

// Widget with $10 minimum purchase
https://ibuyvoi.com/widget?destination=ADDRESS&minimum=10

// Redirect mode with custom return URL and site name
https://ibuyvoi.com/widget?destination=ADDRESS&mode=redirect&redirectUrl=https://mysite.com/success&siteName=MyApp

// Auto theme with allowed origin and $5 minimum
https://ibuyvoi.com/widget?destination=ADDRESS&theme=auto&allowedOrigin=https://mysite.com&minimum=5

🔒 Security Best Practices

• Always validate the destination wallet address
• Use allowedOrigin parameter for iframe communication security
• Redirect URLs are automatically validated to match your site's origin
• All postMessage communications include origin validation