Docs/Widget Integration

Widget Integration

The fastest way to accept payments. No backend required.

Overview

The Fivo widget is a drop-in payment solution that handles everything: wallet connection, chain selection, transaction signing, and cross-chain bridging. Simply add a script tag to your site and you're ready to accept payments.

Fixed Amount Mode

For products, services, subscriptions. The price is locked and customers can only pay the exact amount.

Variable Amount Mode

For donations, tips, custom payments. Customers enter their desired amount before paying.

Fixed Amount Mode

Use fixed amount mode when you want customers to pay an exact price. This is ideal for e-commerce, SaaS subscriptions, or any product with a set price.

Fixed Amount Example

<!-- Product: $49.99 USDC -->
<div id="fivo-widget-root"></div>
<script
  src="https://widget.fivo.finance/widget.js"
  data-merchant-id="YOUR_MERCHANT_ID"
  data-amount="49.99"
  data-currency="USDC">
</script>

Amount Validation

The widget validates that the customer has sufficient balance before allowing them to proceed. If they don't have enough on any chain, the payment option will show as "Insufficient".

Use Cases

E-commerce product checkout
SaaS subscription payments
Digital product purchases
Service invoices
Event tickets

Variable Amount Mode

Remove the data-amount attribute to let customers enter their own amount. The widget will show an input field where they can type how much they want to pay.

Variable Amount Example

<!-- Donation/Tip - Customer chooses amount -->
<div id="fivo-widget-root"></div>
<script
  src="https://widget.fivo.finance/widget.js"
  data-merchant-id="YOUR_MERCHANT_ID"
  data-currency="USDC">
</script>

How it looks

In variable mode, customers see an input field to enter their amount:

Amount to pay (USDC)

USDC

Use Cases

Donations and fundraising
Tips for content creators
Pay-what-you-want pricing
Custom invoices
Crowdfunding contributions

Amount Limits

Variable amounts are validated between 0.01 and 1,000,000. Amounts outside this range will show an error message.

Configuration Options

The widget is configured through data attributes on the script tag.

Script Attributes

Name	Type	Required	Description
`data-merchant-id`	string	Required	Your unique Merchant ID from the Fivo dashboard
`data-amount`	string	Optional	Fixed payment amount. Omit for variable amount mode.
`data-currency`	string	Optional	Payment currency: "USDC" or "EURC". Defaults to "USDC".

Alternative: JavaScript Configuration

You can also configure the widget programmatically using window.FIVO_CONFIG:

JavaScript Configuration

// Set configuration before loading the widget
window.FIVO_CONFIG = {
  merchantId: 'YOUR_MERCHANT_ID',
  amount: '49.99',        // Optional: omit for variable mode
  currency: 'USDC'        // Optional: defaults to 'USDC'
};

// Then load the widget script
const script = document.createElement('script');
script.src = 'https://widget.fivo.finance/widget.js';
document.body.appendChild(script);

Dynamic Amounts

For shopping carts or checkout flows where the amount changes, use JavaScript configuration to set the amount dynamically:

E-commerce Cart Example

// Your cart calculation
const cartTotal = calculateCartTotal(); // e.g., 149.99

// Configure Fivo with cart total
window.FIVO_CONFIG = {
  merchantId: 'YOUR_MERCHANT_ID',
  amount: cartTotal.toString(),
  currency: 'USDC'
};

// Load the widget when ready
function loadFivoWidget() {
  const container = document.getElementById('fivo-widget-root');
  if (container) {
    const script = document.createElement('script');
    script.src = 'https://widget.fivo.finance/widget.js';
    document.body.appendChild(script);
  }
}

// Call when user clicks "Checkout"
document.getElementById('checkout-btn').addEventListener('click', loadFivoWidget);

Supported Currencies

Currency	Code	Description
USD Coin	`USDC`	Stablecoin pegged to US Dollar
Euro Coin	`EURC`	Stablecoin pegged to Euro

Styling

The widget uses its own encapsulated styles to ensure consistent appearance across all sites. The payment button adapts to fit within your layout.

Custom styling options (colors, fonts, button styles) are planned for a future release. The widget currently uses Fivo's default dark theme.

What Happens After Payment

Transaction Confirmed

The widget shows a success message with the transaction hash.

Payment Recorded

The payment appears in your Fivo dashboard under Transactions.

Email Notification

You receive an email with payment details (amount, sender, tx hash).

Funds in Wallet

The USDC/EURC is now in your merchant wallet. You can view and withdraw from the dashboard.

Need more control?

For custom checkout flows, webhooks, or programmatic payment creation, check out our API integration guide.

API Integration Guide