> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypermid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fiat On-Ramp

> Enable users to buy crypto with fiat currency via RampNow

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

<Steps>
  <Step title="Get Configuration">
    Fetch supported fiat currencies and payment methods via `GET /v1/onramp/config`.
  </Step>

  <Step title="Get Available Assets">
    Fetch purchasable crypto assets via `GET /v1/onramp/assets`.
  </Step>

  <Step title="Get a Quote">
    Get pricing for the fiat-to-crypto conversion via `POST /v1/onramp/quote`.
  </Step>

  <Step title="Create Checkout">
    Create a checkout session and get a redirect URL via `POST /v1/onramp/checkout`.
  </Step>

  <Step title="Redirect User">
    Send the user to the checkout URL to complete payment.
  </Step>

  <Step title="Track Status">
    Poll the order status via `GET /v1/onramp/status` until completion.
  </Step>
</Steps>

## Step 1: Get Configuration

Fetch the available fiat currencies and payment methods:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const config = await client.getOnrampConfig();

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

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

  ```bash cURL theme={"system"}
  curl https://api.hypermid.io/v1/onramp/config \
    -H "X-API-Key: your-api-key"
  ```
</CodeGroup>

## Step 2: Get Available Assets

Fetch the list of crypto assets available for purchase:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const assets = await client.getOnrampAssets();

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

  ```bash cURL theme={"system"}
  curl https://api.hypermid.io/v1/onramp/assets \
    -H "X-API-Key: your-api-key"
  ```
</CodeGroup>

## Step 3: Get a Quote

Request a quote for the fiat-to-crypto conversion:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  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.cryptoAmount, "ETH");
  console.log("Exchange rate:", quote.exchangeRate);
  console.log("Fees:", quote.fees);
  console.log("Total charge:", quote.totalFiatAmount, quote.fiatCurrency);
  ```

  ```bash cURL theme={"system"}
  curl -X POST "https://api.hypermid.io/v1/onramp/quote" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: your-api-key" \
    -d '{
      "fiatCurrency": "USD",
      "cryptoAsset": "ETH",
      "chainId": 1,
      "fiatAmount": 100,
      "paymentMethod": "credit_card",
      "walletAddress": "0xYourWalletAddress"
    }'
  ```
</CodeGroup>

## Step 4: Create Checkout Session

Create a checkout session to get a payment URL:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  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.checkoutUrl);
  console.log("Order UID:", checkout.orderUid);

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

  ```bash cURL theme={"system"}
  curl -X POST "https://api.hypermid.io/v1/onramp/checkout" \
    -H "Content-Type: application/json" \
    -H "X-API-Key: your-api-key" \
    -d '{
      "fiatCurrency": "USD",
      "cryptoAsset": "ETH",
      "chainId": 1,
      "fiatAmount": 100,
      "paymentMethod": "credit_card",
      "walletAddress": "0xYourWalletAddress",
      "redirectUrl": "https://yourapp.com/onramp/callback"
    }'
  ```
</CodeGroup>

## Step 5: Track Order Status

After the user completes payment, poll the order status:

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  async function pollOnrampStatus(orderUid: string) {
    while (true) {
      const status = await client.getOnrampStatus({ orderUid });

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

      switch (status.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.txHash);
          break;
        case "COMPLETED":
          console.log("Order complete!");
          return status;
        case "FAILED":
          console.error("Order failed:", status.failureReason);
          throw new Error(status.failureReason);
        case "REFUNDED":
          console.log("Payment was refunded");
          return status;
      }

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

  ```bash cURL theme={"system"}
  curl "https://api.hypermid.io/v1/onramp/status?orderUid=ord_abc123" \
    -H "X-API-Key: your-api-key"
  ```
</CodeGroup>

## Complete Example

```typescript theme={"system"}
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.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.cryptoAmount} ETH`);
  console.log(`Fees: $${quote.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.checkoutUrl,
    orderUid: checkout.orderUid,
  };
}
```

## Best Practices

<Note>
  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.
</Note>

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](/guides/webhooks) 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.