Authorization: BASIC {apiKey}
Accept: application/json
Content-Type: application/json   # on requests with a body
Meld-Version: 2026-02-03

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Your UI   │◄──►│  Meld APIs  │◄──►│ Provider UI │───►│   Your UI   │
│             │    │             │    │  (Widget)   │    │             │
├─────────────┤    ├─────────────┤    ├─────────────┤    ├─────────────┤
│ • Discovery │    │ • Routing   │    │ • Payment   │    │ • Status    │
│ • Quotes    │    │ • Pricing   │    │ • KYC       │    │ • Results   │
│ • Selection │    │ • Sessions  │    │ • Compliance│    │ • Tracking  │
│ • Launch    │    │ • Webhooks  │    │ • Payout    │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

GET /network-partner/supported/countries?category={CATEGORY}

GET /service-providers/properties/defaults/by-country?countries={c}&categories={CATEGORY}

GET /network-partner/supported/currencies?category={CATEGORY}&country={c}&type={FIAT|CRYPTO}

GET /network-partner/supported/payment-methods?category={CATEGORY}&country={c}&currencyCode={f}

GET /network-partner/supported/routes/{category}/{countryCode}/{sourceCurrencyCode}/{destinationCurrencyCode}

Route = { partner, source, destination, paymentMethods: RoutePaymentMethod[], kycLimits?: [] }

RoutePaymentMethod = {
  paymentType,        // broad bucket: CARD, MOBILE_WALLET, BANK_TRANSFER
  name,               // canonical method id — SAME value as `method` from /supported/payment-methods (send as paymentMethodType)
  partnerMethodName,  // provider-specific label (informational only)
  limits: { currencyCode, min, max } | null,   // replaces the legacy limits endpoint
  logo?: { dark, light },
  headlessSupported?  // true = rail supports headless checkout
}

// Sort by Meld's recommended ranking for best results
function rankQuotesByMeldScore(quotes) {
  return quotes.sort((a, b) => {
    const aScore = a.rampIntelligence?.rampScore ?? 0;
    const bScore = b.rampIntelligence?.rampScore ?? 0;
    if (aScore !== bScore) return bScore - aScore;       // higher rampScore first
    return b.destinationAmount - a.destinationAmount;     // tie-break: more received
  });
}

// Webhook endpoint receives transaction updates
app.post('/webhook/meld', async (req, res) => {
  // The transaction id is nested under `payload` on the webhook event.
  const { paymentTransactionId, externalCustomerId } = req.body.payload;
  const tx = await fetchTransaction(paymentTransactionId);
  updateTransaction(paymentTransactionId, tx);
  notifyUser(externalCustomerId, { transactionId: paymentTransactionId, status: tx.status });
  res.status(200).send('OK');
});

// Fetch transaction details (unchanged endpoint)
async function fetchTransaction(transactionId) {
  const res = await fetch(
    `https://api-sb.meld.io/payments/transactions/${transactionId}`,
    { headers: { 'Authorization': `BASIC ${apiKey}`, 'Meld-Version': '2026-02-03' } }
  );
  const body = await res.json();
  return body.transaction; // response is wrapped in { transaction: {...} }
}

{
  "transaction": {
    "id": "WePLapZetkn1hfeKFScf3T",
    "transactionType": "CRYPTO_PURCHASE",
    "status": "SETTLED",
    "sourceAmount": 200,
    "sourceCurrencyCode": "USD",
    "destinationAmount": 199.83,
    "destinationCurrencyCode": "USDC",
    "paymentMethodType": "CREDIT_DEBIT_CARD",
    "serviceProvider": "TRANSAK",
    "externalSessionId": "session_456",
    "cryptoDetails": {
      "walletAddress": "0xfCFAa8059080D01b27ccA2B1fA086df0853397E6",
      "offrampDestinationWalletAddress": null,
      "blockchainTransactionId": "0xabc...def",
      "chainId": "1",
      "networkFeeInUsd": 0.17,
      "transactionFeeInUsd": 2,
      "partnerFeeInUsd": 2,
      "totalFeeInUsd": 4.17
    }
  }
}

function getStatusMessage(status) {
  return {
    PENDING: 'Processing your transaction…',
    SETTLING: 'Finalizing transfer…',
    SETTLED: 'Complete!',
    FAILED: 'Transaction failed. Please try again.',
    CANCELLED: 'Transaction was cancelled.'
  }[status] || 'Transaction status updated.';
}

class MeldDiscoveryCache {
  constructor() { this.cache = new Map(); }

  async get(key, ttlMs, fetcher) {
    const hit = this.cache.get(key);
    if (hit && Date.now() - hit.timestamp < ttlMs) return hit.data;
    const data = await fetcher();
    this.cache.set(key, { data, timestamp: Date.now() });
    return data;
  }
}

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'
  };
  console.error(`API Error (${endpoint}):`, error);
  showErrorToUser(errorMap[error.status] || 'Unknown error occurred');
}