Skip to main content
Hypermid integrates with RampNow to provide a fiat-to-crypto on-ramp. Users can purchase crypto using credit cards, debit cards, and bank transfers, and receive tokens directly on their preferred blockchain.

​
Flow Overview

1

Get Configuration

Fetch supported fiat currencies and payment methods via GET /v1/onramp/config.
2

Get Available Assets

Fetch purchasable crypto assets via GET /v1/onramp/assets.
3

Get a Quote

Get pricing for the fiat-to-crypto conversion via POST /v1/onramp/quote.
4

Create Checkout

Create a checkout session and get a redirect URL via POST /v1/onramp/checkout.
5

Redirect User

Send the user to the checkout URL to complete payment.
6

Track Status

Poll the order status via GET /v1/onramp/status until completion.

​
Step 1: Get Configuration

Fetch the available fiat currencies and payment methods: 
const config = await client.getOnrampConfig();

console.log("Supported currencies:", config.data.currencies);
// ["USD", "EUR", "GBP", ...]

console.log("Payment methods:", config.data.paymentMethods);
// ["credit_card", "debit_card", "bank_transfer", ...]

​
Step 2: Get Available Assets

Fetch the list of crypto assets available for purchase: 
const assets = await client.getOnrampAssets();

for (const asset of assets.data.assets) {
  console.log(`${asset.symbol} on chain ${asset.chainId}: min ${asset.minAmount}, max ${asset.maxAmount}`);
}

​
Step 3: Get a Quote

Request a quote for the fiat-to-crypto conversion: 
const quote = await client.getOnrampQuote({
  fiatCurrency: "USD",
  cryptoAsset: "ETH",
  chainId: 1,
  fiatAmount: 100,            // $100 USD
  paymentMethod: "credit_card",
  walletAddress: "0xYourWalletAddress",
});

console.log("You'll receive:", quote.data.cryptoAmount, "ETH");
console.log("Exchange rate:", quote.data.exchangeRate);
console.log("Fees:", quote.data.fees);
console.log("Total charge:", quote.data.totalFiatAmount, quote.data.fiatCurrency);

​
Step 4: Create Checkout Session

Create a checkout session to get a payment URL: 
const checkout = await client.createOnrampCheckout({
  fiatCurrency: "USD",
  cryptoAsset: "ETH",
  chainId: 1,
  fiatAmount: 100,
  paymentMethod: "credit_card",
  walletAddress: "0xYourWalletAddress",
  redirectUrl: "https://yourapp.com/onramp/callback",
});

console.log("Checkout URL:", checkout.data.checkoutUrl);
console.log("Order UID:", checkout.data.orderUid);

// Redirect user to the checkout URL
window.location.href = checkout.data.checkoutUrl;

​
Step 5: Track Order Status

After the user completes payment, poll the order status: 
async function pollOnrampStatus(orderUid: string) {
  while (true) {
    const status = await client.getOnrampStatus({ orderUid });

    console.log("Status:", status.data.status);

    switch (status.data.status) {
      case "PENDING":
        console.log("Waiting for payment...");
        break;
      case "PAYMENT_RECEIVED":
        console.log("Payment received, processing...");
        break;
      case "CRYPTO_SENT":
        console.log("Crypto sent to wallet!");
        console.log("Tx hash:", status.data.txHash);
        break;
      case "COMPLETED":
        console.log("Order complete!");
        return status.data;
      case "FAILED":
        console.error("Order failed:", status.data.failureReason);
        throw new Error(status.data.failureReason);
      case "REFUNDED":
        console.log("Payment was refunded");
        return status.data;
    }

    await new Promise((r) => setTimeout(r, 10000));
  }
}

​
Complete Example

import { Hypermid } from "@hypermid/sdk";

const client = new Hypermid({ apiKey: process.env.HYPERMID_API_KEY });

async function buyEthWithUsd(walletAddress: string, usdAmount: number) {
  // 1. Check available assets
  const assets = await client.getOnrampAssets();
  const ethAsset = assets.data.assets.find(
    (a) => a.symbol === "ETH" && a.chainId === 1
  );

  if (!ethAsset) throw new Error("ETH not available for purchase");

  // 2. Get a quote
  const quote = await client.getOnrampQuote({
    fiatCurrency: "USD",
    cryptoAsset: "ETH",
    chainId: 1,
    fiatAmount: usdAmount,
    paymentMethod: "credit_card",
    walletAddress,
  });

  console.log(`$${usdAmount} USD = ${quote.data.cryptoAmount} ETH`);
  console.log(`Fees: $${quote.data.fees.totalFee} USD`);

  // 3. Create checkout
  const checkout = await client.createOnrampCheckout({
    fiatCurrency: "USD",
    cryptoAsset: "ETH",
    chainId: 1,
    fiatAmount: usdAmount,
    paymentMethod: "credit_card",
    walletAddress,
    redirectUrl: "https://yourapp.com/onramp/complete",
  });

  // 4. Return checkout URL for the frontend to redirect
  return {
    checkoutUrl: checkout.data.checkoutUrl,
    orderUid: checkout.data.orderUid,
  };
}

​
Best Practices

The fiat on-ramp involves real money. Always show users a clear summary of fees, exchange rates, and the expected crypto amount before redirecting to checkout.
  1. Show fees transparently — Display the breakdown of network fees, processing fees, and exchange rate before the user proceeds.
  2. Use webhooks for production — Instead of polling, configure a webhook to receive order status updates automatically.
  3. Handle KYC requirements — Some jurisdictions and amounts may require additional KYC verification. The checkout flow handles this automatically, but inform users they may need to verify their identity.
  4. Set appropriate redirect URLs — The redirectUrl should point to a page in your app that shows the order status and provides a good user experience.
  5. Respect minimum/maximum amounts — Check the asset’s minAmount and maxAmount from the assets endpoint before requesting a quote.