Full Integration Guide

Integrating the Meld Checkout widget is incredible easy, in fact, if you've completed the Quickstart, you've already done almost all the work! This section has additional information on embedding and customization.

Step 1: Get Users to the Meld Checkout widget

Now that you have your Meld Checkout widget url (see Step 1 here if not), here are some code examples of how you can embed the url in your application or redirect users to the user.

Redirection Examples

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'
  );
}

Iframe Embedding Examples

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 2: Customization with URL 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 3: 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 4: 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.