You can view API request and response examples for each of the key endpoints in the Quickstart. This section goes over the end to end flow and includes details not found in the Quickstart.

⚠️
CRITICAL: API Changes & Compatibility
Non-Breaking Changes (No Versioning):

New fields may be added to API responses at any time

Your system MUST handle unexpected fields gracefully

Avoid strict JSON validation that rejects unknown properties

Breaking Changes (Versioned):

Field modifications or deletions will be versioned

Released approximately with advance notice

Required Actions:

✅ Use flexible JSON parsing (ignore unknown fields)

✅ Implement defensive coding practices

✅ Test with mock responses containing extra fields

How White-Label API Virtual Account Integration Works

High-Level Flow:

Since this flow can be used by individuals or businesses, the steps will say user / business to denote that.

Manual Meld will KYC / KYB the user / business with the onramp.
Your UI: Collect user preferences (amount, crypto, payment method)
Meld API: Get real-time quotes from multiple providers
Your UI: Display quotes and let user choose
Meld API: Create a Meld subAccount for your user / business (1 time per user / business per onramp)
Meld API: Create an order, and fetch the virtual bank account details from the onramp
User's Bank App: User completes payment to the virtual bank account the onramp set up
Webhooks: Receive real-time transaction updates

Technical Architecture:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐   
│   Your UI   │───►│  Meld APIs  │───►│ Provider API│
│             │◄───│             │◄───│             │
├─────────────┤    ├─────────────┤    ├─────────────┤
│ • Quotes    │    │ • Pricing   │    │ • VA Info   │
│ • Selection │    │ • VA Info   │    │ • Status    │  
│ • Launch    │    │ • Webhooks  │    │ • Tracking  │
└─────────────┘    └─────────────┘    └─────────────┘

Prerequisites:

API Key from Meld Dashboard
Webhook endpoint for transaction updates
Domain whitelisting for redirect URLs (some providers require this)

White-Label API Integration Steps

The virtual account flow will happen completely via your UI.

Here is a common integration approach using this three-step process:

1. Create Complete User Journey

Build your own custom UI to collect user preferences:

Amount they want to spend/receive
Fiat currency selection
Cryptocurrency selection
Bank transfer type preference (for example ACH vs Wire in the US)
Wallet address for receiving crypto
Country (can be auto-detected from user's device/browser instead of prompting)

2. Fetch Quotes

Call Meld's Quote API to get real-time quotes from multiple onramp/offramp providers:

Send user preferences to Meld quote API
Receive quotes from available service providers
Display quotes in your custom interface for user selection

Key Response Fields Explained:

sourceAmount: This is the amount of money the user will spend. For onramp this is in fiat, for offramp this is in terms of crypto.
destinationAmount: This is the amount of money the user will receive. For onramp this is in crypto, for offramp this is in terms of fiat.
totalFee: The total fee the user will pay, in terms of the fiat currency they are using.
serviceProvider: The onramp whose quote you are viewing.
customerScore, institutionName, lowKyc: These fields can be ignored as they are not relevant to the virtual account flow.

3. Create Meld subAccount for the user

Call Meld's Create SubAccount API with the onramp's id for the user to create a meld subAccount for that user. You will receive the onramp's id for the user manually from Meld.

This only needs to be done 1 time per user per provider. If you it more than once, the Meld API will return an error indicating that the subAccount has already been created with Meld.

4. Initiate a Transaction

For the buy flow:

Call Meld's Create Buy Order API with the user's wallet address and subAccountId to receive the virtual bank account details for the user.
Have the user send money to the virtual bank account from their banking app.
When the onramp receives the payment, they will send crypto to the user's wallet.

For the sell flow:

Call Meld's Create Sell Order API with the user's wallet address, bank account information, and subAccountId to receive the wallet address for the user to send crypto to.
Have the user send crypto from their wallet to the wallet address returned in the previous step.
When the onramp receives the crypto, they will send payment to the user's bank account.

5. Track Transaction

Process webhooks and display transaction information to users:

Set up webhook endpoints to receive transaction status updates
Fetch detailed transaction data from Meld's Transactions API when webhooks arrive
Display transaction progress, completion status, and details in your UI

You will receive webhooks from Meld every time a transaction is created or updated. To learn more about the various Meld webhook events as well as see examples, click here.

Webhook Integration:

// Sample Code: Webhook endpoint receives transaction updates
app.post('/webhook/meld', (req, res) => {
  const { transactionId, status, externalCustomerId } = req.body;
  
  // Use webhook as trigger to fetch full transaction details
  const transactionDetails = await fetchTransactionDetails(transactionId);
  
  // Update user's transaction in your database
  updateTransaction(transactionId, transactionDetails);
  
  // Notify user via websockets, push notifications, etc.
  notifyUser(externalCustomerId, {
    transactionId,
    status,
    message: getStatusMessage(status)
  });
  
  res.status(200).send('OK');
});

// Sample Code: Fetch transaction details when webhook arrives
async function fetchTransactionDetails(transactionId) {
  const response = await fetch(
    `/payments/transactions/${transactionId}`,
    {
      headers: {
        'Authorization': `BASIC ${apiKey}`,
        'Meld-Version': '2025-03-04'
      }
    }
  );
  return await response.json();
}

Transaction Status Display:

// Sample Code: Display user-friendly status messages
function getStatusMessage(status) {
  const statusMessages = {
    'PENDING': 'Processing your transaction...',
    'SETTLING': 'Finalizing crypto transfer...',
    'SETTLED': 'Complete! Crypto sent to your wallet.',
    'FAILED': 'Transaction failed. Please try again.',
    'CANCELLED': 'Transaction was cancelled.'
  };
  
  return statusMessages[status] || 'Transaction status updated.';
}

📋
Status Reference: See Transaction Statuses for complete status definitions.

Best Practices & Tips

Error Handling:

async function handleAPIError(error, endpoint) {
  const errorMap = {
    401: 'Invalid API key or authentication failed',
    403: 'Access forbidden - check account permissions', 
    429: 'Rate limit exceeded - please wait and retry',
    500: 'Server error - please try again later'
  };
  
  const message = errorMap[error.status] || 'Unknown error occurred';
  
  // Log for debugging
  console.error(`API Error (${endpoint}):`, error);
  
  // Show user-friendly message
  showErrorToUser(message);
}

Security Considerations:

Never expose API keys in frontend code
Validate all user inputs before API calls
Use HTTPS only for API communications
Implement rate limiting to prevent abuse

Next Steps

Testing Your Implementation:

Testing Credentials - Comprehensive testing strategies

Advanced Features:

Webhook Events - Real-time updates
Dashboard Data - Track performance

Production Deployment:

Network Partner Setup - Configure additional onramps

Support & Resources

Complete API Reference - All endpoints documented
Postman Collection - Test APIs directly
FAQ - Common questions answered

This guide provides everything needed to build a production-ready crypto interface. Most teams complete their custom UI integration within 1-2 weeks using this approach.

Full Integration Guide

CRITICAL: API Changes & Compatibility

How White-Label API Virtual Account Integration Works

High-Level Flow:

Technical Architecture:

Prerequisites:

White-Label API Integration Steps

1. Create Complete User Journey

2. Fetch Quotes

Key Response Fields Explained:

3. Create Meld subAccount for the user

4. Initiate a Transaction

5. Track Transaction

Webhook Integration:

Transaction Status Display:

Status Reference: See Transaction Statuses for complete status definitions.

Best Practices & Tips

Error Handling:

Security Considerations:

Next Steps

Testing Your Implementation:

Advanced Features:

Production Deployment:

Support & Resources