Create an onramp checkout

Create a signed Swapped checkout URL for a registered account, then show Swapped’s hosted UI in your app. Headless means you do not use the Rhinestone widget; it does not remove the provider’s checkout UI.

How it works

Your backend requests a signed checkout URL for the user’s account.
Your app shows the URL in an iframe or in-app browser.
The user completes payment and any required KYC with Swapped.
Swapped sends provider-order updates as the payment progresses.
Swapped sends the purchased crypto, currently USDC on Base, to the account; the standard deposit pipeline then routes it to the account’s target.

Prerequisites

The account is registered. Minting a checkout URL for an account that is not registered to your project returns 403 Unauthorized.
A webhook URL is configured if you want order updates pushed rather than polled.
Calls are made from your backend. The endpoints require your API key, which never ships in client-side code.

Mint a checkout URL

const DEPOSIT_SERVICE_URL =
    "https://v1.orchestrator.rhinestone.dev/deposit-processor";
const API_KEY = "YOUR_RHINESTONE_API_KEY";

const response = await fetch(`${DEPOSIT_SERVICE_URL}/onramp/swapped/widget-url`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
    body: JSON.stringify({
        smartAccount: "0xUSER_ACCOUNT_ADDRESS",
        baseCurrencyCode: "EUR",
        baseCurrencyAmount: 100,
        method: "apple-pay", // optional — omit to let Swapped choose the best method
    }),
});

const { url, externalCustomerId, expiresAt } = await response.json();

Only smartAccount is required — every other field, including method, is optional and simply prefills the widget. If you omit method, Swapped auto-selects the best payment method for the user based on their location and other signals:

Field	Type	Description
`smartAccount`	`string`	The registered account that receives the crypto
`email`	`string`	Prefills the user’s email
`baseCountry`	`string`	User’s country (ISO 3166-1 alpha-2, e.g. `"DE"`)
`baseCurrencyCode`	`string`	Fiat currency to charge in (e.g. `"EUR"`)
`baseCurrencyAmount`	`number`	Prefilled purchase amount in the fiat currency
`locale`	`string`	Widget language
`method`	`string`	Optional. Preselects a payment method — accepts any method Swapped supports (see the list below). Omit it to let Swapped auto-select the best method for the user.

method takes a Swapped payment group. Swapped offers 40+ methods and the set available depends on the user’s region — common values include "creditcard", "apple-pay", "bank-transfer", "skrill", "pix", and "sepa-bank-transfer". Pass a method’s payment_group; the authoritative, up-to-date list for your account is Swapped’s Get Payment Methods endpoint. A value Swapped doesn’t support for the user is ignored rather than rejected — the widget falls back to the best available method, so an unrecognized method never blocks checkout. The response carries the signed URL:

Field	Type	Description
`url`	`string`	The checkout URL to embed
`currencyCode`	`string`	Asset the purchase settles in, as `ASSET_NETWORK` (currently `"USDC_BASE"`)
`sandbox`	`boolean`	`true` when the service runs against Swapped’s sandbox
`externalCustomerId`	`string`	`<account>:<orderUuid>` — correlates the checkout with its webhooks
`expiresAt`	`string`	End of the order-tracking window (ISO 8601)

The URL is signed by the service, so its parameters — destination wallet and asset — can’t be modified client-side. Mint a fresh URL for each checkout session. The purchase always settles in the asset reported by currencyCode; when the account’s target differs, the bridge hop happens automatically. Full request and response schemas: POST /onramp/swapped/widget-url.

Show the hosted checkout

Embed the URL in an iframe with payment and camera permissions — Apple Pay and camera-based KYC need them:

<iframe src={url} allow="payment; camera; microphone; clipboard-write" />

In a mobile app, open the URL in an in-app browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android) rather than a plain WebView — Apple Pay and camera access are restricted in bare WebViews. The URL carries no redirect or callback parameter. Detect completion through the onramp-order webhook or by polling order status, then dismiss the hosted checkout from your own UI.

A user who abandons checkout produces no terminal event — the order simply never progresses. Apply your own timeout when waiting on an order.

KYC, identity verification, and purchase limits are handled by Swapped inside the hosted UI. Track provider progress and final deposit settlement separately in Track onramp and exchange orders.

Setup

Funding

Processing and tracking

Fees

Create an onramp checkout

How it works

Prerequisites

Mint a checkout URL

Show the hosted checkout

​How it works

​Prerequisites

​Mint a checkout URL

​Show the hosted checkout

How it works

Prerequisites

Mint a checkout URL

Show the hosted checkout