Widget Integration Implementation

Ready to implement Widget Integration? This guide walks you through the complete setup process, from getting your Public Key URL to going live with your integration.

Prerequisites

Before you begin, ensure you have:

• ✅ Meld Dashboard Access - Check your email for the invitation
• ✅ Crypto Provider Setup - Complete provider configuration in the Integrations tab
• ✅ Webhook Endpoint (Optional) - For transaction notifications

Step 1: Get Your Public Key URL

1. Log into the Meld Dashboard
2. Navigate to Developer tab
3. Copy your complete Public Crypto Widget URL

⚠️ Important: The dashboard provides a complete, ready-to-use URL. Keep this URL secure - it identifies your application to Meld's system.

Step 2: Basic Implementation

HTML Link Integration

The simplest integration - redirect users to the widget:

<a href="meldcrypto.com/?publicKey=your_public_key" target="_blank">
  Buy Crypto
</a>

JavaScript Redirect

For programmatic control:

function launchCryptoWidget() {
  window.location.href = 'meldcrypto.com/?publicKey=your_public_key';
}

// Usage
document.getElementById('buy-crypto-btn').addEventListener('click', launchCryptoWidget);

New Tab/Window Opening

Open widget in a new window:

function openCryptoWidget() {
  window.open(
    'meldcrypto.com/?publicKey=your_public_key',
    'meld-widget',
    'width=450,height=790,scrollbars=yes,resizable=yes'
  );
}

Step 3: Iframe Embedding

For embedded experience within your application:

<iframe 
  src="meldcrypto.com/?publicKey=your_public_key"
  width="450" 
  height="790"
  frameborder="0"
  allow="camera; microphone; payment">
</iframe>

Iframe Best Practices:

• Minimum width: 450px for optimal display
• Minimum height: 790px to prevent UI overlap
• Allow permissions: Include camera, microphone, payment for KYC and transactions
• Responsive design: Consider dynamic sizing for mobile

Step 4: Essential Parameters

Add optional parameters to your Meld Widget URL for customization:

// Your complete Meld Widget URL with optional parameters
const dashboardUrl = 'meldcrypto.com/?publicKey=your_public_key'; // From Meld Dashboard Developer tab
const customizedUrl = `${dashboardUrl}&sourceAmount=100&destinationCurrencyCode=BTC&countryCode=US`;

window.location.href = customizedUrl;

Key Parameters:

• sourceAmount - Pre-fill purchase amount (e.g., 100)
• destinationCurrencyCode - Pre-select cryptocurrency (e.g., BTC, ETH_ETHEREUM)
• walletAddress - Pre-fill destination wallet if known
• countryCode - Override auto-detected country (rarely needed)

➡️ Complete Parameter Reference

Step 5: Testing Your Integration

Sandbox Testing

Always test in sandbox environment first:

// Use your sandbox Meld Widget URL (from Developer tab in sandbox environment)
const sandboxUrl = 'meldcrypto.com/?publicKey=your_public_key';

Test Workflow:

1. Redirect to sandbox widget with your parameters
2. Complete test transaction using testing credentials
3. Verify webhook reception (if implemented)
4. Test all user flows (buy/sell as applicable)

Step 6: Mobile Implementation

React Native Example:

import { Linking } from 'react-native';

const openMeldWidget = () => {
  const widgetUrl = `meldcrypto.com/?publicKey=your_public_key&redirectUrl=myapp://crypto-complete`;
  Linking.openURL(widgetUrl);
};

Deep Link Return:

// Handle return from widget
const handleDeepLink = (url) => {
  if (url.includes('crypto-complete')) {
    // User completed transaction, update UI
    navigateToCryptoSuccess();
  }
};

Mobile Considerations:

• Use redirectUrl with deep links to return users to your app
• Consider theme parameter to match your app's appearance
• Test on both iOS and Android for compatibility

Step 7: Go Live

Production Checklist:

• ✅ Use production Meld Widget URL (from Developer tab in production environment)
• ✅ Test with small real transaction
• ✅ Verify webhook endpoints are working
• ✅ Monitor first transactions for issues

Production URL:

const productionUrl = 'meldcrypto.com/?publicKey=your_public_key';

Troubleshooting Common Issues

Widget Won't Load

• ✅ Verify Meld Widget URL is correct and from the right environment
• ✅ Check for browser popup blockers
• ✅ Ensure iframe permissions are set correctly

Parameters Not Working

• ✅ URL encode parameter values
• ✅ Check parameter spelling and case sensitivity
• ✅ Verify parameter combinations are valid

Mobile Issues

• ✅ Test deep link return flow
• ✅ Verify redirectUrl format is correct
• ✅ Check mobile browser compatibility

Error Handling

JavaScript Error Handling:

try {
  window.location.href = widgetUrl;
} catch (error) {
  console.error('Failed to open widget:', error);
  // Fallback: show error message to user
  alert('Unable to open crypto purchase. Please try again.');
}

Iframe Error Handling:

const iframe = document.getElementById('meld-widget');
iframe.onerror = () => {
  console.error('Widget failed to load');
  // Show error message or fallback content
};

Next Steps

Optimize Your Integration:

• URL Parameters - Complete parameter reference
• Customization - Styling and advanced options

Monitor and Improve:

• Webhook Events - Real-time notifications
• Transaction Statuses - Understanding transaction states
• Dashboard Data - Analytics and reporting

Your Widget Integration is now live! Users can purchase crypto directly through your application with Meld's secure, compliant widget.