On-ramp widget vs API: which integration fits your product?

An on-ramp widget is a hosted page the provider runs inside your app. It shows quotes, collects KYC, and owns most screens, so you launch fast with little control. An API-first on-ramp gives you endpoints and webhooks: you build the screens, own the user experience and data flow, and take on more engineering work.

Both convert fiat into stablecoins. The difference is who owns each step between "user taps buy" and "USDC lands in a wallet." That split decides your launch date, your conversion rate, and what your compliance team signs.

Key takeaways

• Widgets trade control for speed. The provider owns the screens, the copy, and usually the KYC flow.
• APIs trade speed for control. You own the UX, the quote display, and the data, and you build more.
• KYC is the deciding factor. If you already verify users in your onboarding, an API avoids asking twice.
• Businesses funding by bank transfer lean API-first. Consumer card purchases lean widget.
• Hybrids are normal: an API for the money flow plus one hosted step the provider must own.

New to the stack? What is stablecoin infrastructure maps the layers, and this page zooms into how the on-ramp layer plugs into your product.

What is a hosted on-ramp widget?

A hosted on-ramp widget is a provider-built purchase flow embedded in your product through an iframe, a redirect, or an SDK that opens a modal. Your app passes a few parameters (amount, currency, destination wallet) and the provider handles the rest.

Inside the widget, the provider typically:

1. Shows a quote with the price, fees, and network.
2. Collects identity data, ID photos, and a selfie.
3. Takes payment, often by card or a local method.
4. Sends stablecoins to the wallet address you passed in.
5. Redirects the user back, sometimes with a status callback.

Widgets were built for consumer wallets: one person buying a small amount, often by card. Business vs consumer on-ramps covers why that market looks so different from company funding flows.

One technical note. If the widget loads in an iframe, the provider controls which sites may frame it through the Content-Security-Policy frame-ancestors directive (MDN reference). Expect an allowlisting step, and expect some providers to force a redirect or popup instead.

What is an API-first on-ramp?

An API-first on-ramp exposes the conversion as REST endpoints plus webhooks. Your product creates the customer, requests a quote, creates the deposit, shows the payment instructions in your own UI, and listens for status events.

The typical call sequence:

1. Create a customer and submit KYC or KYB data.
2. Register the destination wallet.
3. Request a quote for amount, currency, and rail.
4. Create the payin and render the deposit instructions (bank details, a Pix code, a CLABE).
5. Receive webhooks as the deposit arrives and the stablecoins are delivered.

The full walkthrough, with edge cases and testing, is in how to integrate a crypto on-ramp API.

What changes between a widget and an API?

Almost everything except the conversion itself. The table below compares the two on the decisions that matter after launch.

Two rows deserve a closer look.

Quote display. A widget usually shows one all-in price. An API returns the pieces: rate, fees, amount received, and how long the quote stays valid. If your treasury team needs to explain every basis point, you need those fields. Live quotes and slippage explains why the expiry window matters.

Reconciliation. Widgets are built around a session. APIs are built around objects with IDs. If deposits need to match invoices or customer accounts, object IDs win.

Who owns KYC and compliance in each model?

The ramp provider always makes the verification decision. The question is who collects the data and who owns the customer relationship.

With a widget, the provider usually collects documents in its own screens and treats the user as its own customer. That's simpler for your compliance team. It's also friction for a user who already passed your onboarding and now sees a second ID check.

With an API, you collect the data once and submit it. Your compliance team now has to think about data handling and about which party screens what. On-ramp compliance: who owns what breaks down that split line by line.

Business customers raise the bar. Under FinCEN's customer due diligence rule, covered US financial institutions identify beneficial owners of legal entity customers (31 CFR 1010.230). Expect a business on-ramp to ask for owners and control persons, whichever integration you pick.

The money transmission question doesn't disappear with a widget either. FinCEN's 2019 guidance on convertible virtual currency business models (FIN-2019-G001) looks at what each party actually does with the value, not at whose screen it happens on. This article is for information only and is not legal advice.

Which integration fits which product?

Pick by funding method, by who the user is, and by whether you already run KYC. The table gives a starting point.

How do you decide, step by step?

Use these steps in order. Most teams have their answer by step 4.

1. Name the funding method. Card buys point to a widget. Bank transfers point to an API.
2. Check your onboarding. If users already pass KYC or KYB with you, an API saves them a second check.
3. Decide who the user should see. If the brand on the payment screen must be yours, you need an API.
4. List what finance needs. Fee breakdowns, quote IDs, and deposit references require API data.
5. Count your engineering weeks. If you can't staff webhooks, retries, and UI states this quarter, start with a widget.
6. Ask about hosted steps. Even API-first providers may host one step, such as terms acceptance. Know which ones.
7. Plan the exit. If you start on a widget, confirm you can move to the provider's API later without re-verifying every user.

Whichever you pick, document it for your bank partners. US bank regulators' 2023 interagency guidance on third-party relationships (OCC Bulletin 2023-17) expects banks to understand the vendors in a flow, and your ramp is one of them.

What are the limits of each approach?

Neither model is free of trade-offs, and each has cases where it is the wrong pick.

Widget limitations:

• Your users see a different company's name at the moment they pay.
• You often can't show the fee breakdown or control the quote expiry.
• Iframe embedding can break on strict mobile webviews or framing rules.
• Data access is limited to what the provider sends back.
• Conversion depends on screens you can't A/B test.

API limitations:

• More engineering, before and after launch.
• You own every UI state, including errors and holds.
• Your compliance team owns data collection and its handling.
• Bank-transfer funding is slower than a card buy, so it suits planned deposits more than impulse purchases.

How does BlindPay fit?

BlindPay is an API-first on-ramp for businesses. There's no consumer card widget. Your product creates customers, quotes, and payins through the API, renders the deposit instructions itself, and follows each deposit through webhooks.

One step is hosted on purpose: terms of service acceptance. Each customer accepts BlindPay's terms on a page at app.blindpay.com that shows your instance's logo, name, and accent color, then returns to your redirect_url with a tos_id you pass when creating the customer. Everything else stays in your UI.

What the API gives you:

• KYC and KYB through the API. You submit customer data and documents; BlindPay runs the review. KYC requirements lists the fields per level.
• Quotes as data. A payin quote locks the payment method, amount, and fees for 5 minutes, so you can show exact numbers before the user commits.
• Deposit instructions as fields. ACH and wire return bank details and a memo code, Pix returns a pix_code, SPEI returns a CLABE. Customers with an approved virtual account get dedicated US bank details instead.
• Webhooks for every step. payin.new, payin.update, and payin.complete, plus tos.accept and customer updates.
• Delivery to any supported chain. USDC or USDT to Ethereum, Polygon, Base, Arbitrum, Tempo, Arc, Stellar, Solana, or Tron, depending on token.

If your users never see a wallet address, the Abstracted docs flavor treats payins as plain deposits. Payouts run the other direction over Pix, SPEI, ACH, RTP, SEPA, and SWIFT (POBO/COBO).

What to do next

Write down your funding method and whether you already run KYC. If the answers are "bank transfer" and "yes," start with the payin quickstart on a free development instance and render your first deposit instructions today.