Embedded Offramp Reference

CrossmintEmbeddedOfframp renders the Crossmint offramp in your app for one offramp session. The React and React Native components take the same props and emit the same events. Render the component inside CrossmintProvider, which takes your client-side API key.

Packages

Platform	Package	Renders the offramp in
React	`@crossmint/client-sdk-react-ui`	An iframe
React Native	`@crossmint/client-sdk-react-native-ui`	A WebView

Both packages export:

Export	Kind	Description
`CrossmintEmbeddedOfframp`	Component	The offramp
`createCrossmintWalletSigner(wallet)`	Function	Returns an `EmbeddedOfframpPayer` for a Crossmint EVM or Solana wallet
`OfframpSignatureRejectedError`	Class	The error a custom payer throws when the user declines the transaction
`CrossmintEmbeddedOfframpProps`, `EmbeddedOfframpCredentials`, `EmbeddedOfframpPayer`, `OfframpStatus`, `OfframpErrorReason`	Types	The types on this page

Props

Prop	Type	Required	Description
`credentials`	`{ sessionId: string; clientSecret: string }`	Yes	The `sessionId` and `clientSecret` returned by Create Offramp Session.
`payer`	`EmbeddedOfframpPayer`	Yes	Signs and sends the deposit. Pass `createCrossmintWalletSigner(wallet)` for a Crossmint wallet, or your own object for an external wallet. See Payer.
`appearance`	`EmbeddedCheckoutV3Appearance`	No	Fonts, colors and component styles. It takes the same object as the embedded checkout’s `appearance`, described in UI Customization. The identity verification step uses it too.
`locale`	`Locale`	No	The language of the screens, such as `en-US` or `es-ES`. Defaults to the browser or device language when it is supported, otherwise `en-US`.
`fill`	`boolean`	No	Fills the container’s height instead of sizing to the content. Defaults to `false`. See Sizing.
`onReady`	`() => void`	No	See Events.
`onStatusChange`	`(event: { status: OfframpStatus; orderId?: string }) => void`	No	See Events.
`onComplete`	`(event: { orderId: string; txId: string }) => void`	No	See Events.
`onCancel`	`() => void`	No	See Events. Without it, the Cancel, Continue and Close buttons do nothing.
`onError`	`(error: { reason: OfframpErrorReason; retriable: boolean; message: string }) => void`	No	See Events.

The component reloads the offramp when the value of credentials, appearance, locale or fill changes. payer and the callbacks can change without a reload.

Payer

EmbeddedOfframpPayer has one method, which the component calls when the user confirms the withdrawal:

signAndSendTransaction(tx: { serializedTransaction: string; chain: string; payerAddress: string }): Promise<string>;

Field	Description
`serializedTransaction`	The deposit to sign and broadcast: a serialized transaction on EVM chains, or a base58 legacy transaction with `feePayer` and `recentBlockhash` set on Solana.
`chain`	The chain the deposit was prepared for.
`payerAddress`	The wallet the deposit was prepared for. Your payer must not send the deposit from another wallet. See Refuse a mismatched wallet.

Your method	What the component does
Resolves with the transaction ID	Waits for the deposit to confirm (`confirming-deposit`).
Throws `OfframpSignatureRejectedError`	Treats it as a decline: reports `wallet-rejected` through `onError` (`retriable` is `true`) and creates a new order with a fresh rate, so the user can confirm again.
Throws any other error, or resolves with no transaction ID	Cannot tell whether the deposit was broadcast, so it moves to the confirming screen (`confirming-deposit`) and keeps checking the order, every few seconds and about once a minute after 20 minutes. It does not call `onError` then, and the screen has no button. If no deposit has been recorded when the session’s 24-hour status window ends, `onError` reports `invalid-credentials`, the status becomes `failed`, and the screen shows This session has expired with a Close button. Until then the user waits there, even when nothing was sent, unless your app closes the component with its own control.
Has not settled after 2 minutes	Waits for the deposit on the confirming screen, and still takes the transaction ID if the method resolves later.

Throw OfframpSignatureRejectedError only when the user declined and nothing was broadcast.

Refuse a mismatched wallet

No thrown error refuses a deposit cleanly. OfframpSignatureRejectedError offers a new rate for the same wallet, so a mismatch fails again on the next attempt. Any other error leaves the user on the confirming screen for a deposit that was never sent. The component sends the deposit for the payer wallet you passed when you created the session, so check before you render it: mount CrossmintEmbeddedOfframp only while your connected wallet has the same address and chain as that payer, and otherwise ask the user to switch wallets. createCrossmintWalletSigner throws a plain error for a mismatch, so it has the same effect. Apply the same check before you mount the component when you use it. createCrossmintWalletSigner(wallet) takes a Crossmint wallet, such as the one useWallet() returns. It supports EVM and Solana wallets, and refuses a deposit prepared for another chain or another wallet.

Events

Callback	Payload	Fires when
`onReady`	None	The offramp has loaded the session and shows its first screen. It fires once per load, also when the session fails to load, in which case `onError` reports why. It does not fire when the offramp page cannot load or its props are invalid.
`onStatusChange`	`{ status: OfframpStatus; orderId?: string }`	The flow moves to another step. See Statuses.
`onComplete`	`{ orderId: string; txId: string }`	The deposit for an order is confirmed and the payout to the bank account is in progress or complete. `txId` is the deposit’s transaction ID. It fires once per order and load, so it fires again when the user reopens a completed withdrawal: dedupe by `orderId`. The payout can still fail afterwards: `onStatusChange` reports `payout-failed` and `onError` reports `payout-failed` for the same `orderId`. Confirm the payout on your server with Manage Orders or webhooks.
`onCancel`	None	The user closes the flow: Continue on the Withdrawal sent screen, Close on a failure screen, or Cancel when the order’s bank account cannot be loaded. Only those three buttons call `onCancel`. No other screen has a Cancel button, so your app must provide its own close control. Closing the view while the deposit is confirming does not stop the deposit or the payout. Keep the latest `orderId` from `onStatusChange` and follow it with Manage Orders or webhooks. After Continue on Withdrawal sent, `onComplete` has already fired. Unmounting the component does not cancel a wallet request that was already sent, so keep the payer’s wallet available until it settles.
`onError`	`{ reason: OfframpErrorReason; retriable: boolean; message: string }`	Something went wrong. See Error Reasons. `message` is for your logs, not for display.

Statuses

onStatusChange reports one of these statuses:

Status	Meaning
`loading`	The offramp is loading the session or an order.
`entering-amount`	The user enters the amount to withdraw.
`selecting-bank`	The user picks, renames or removes one of their saved bank accounts.
`adding-bank`	The user adds a bank account.
`verifying-identity`	The order needs identity verification, and the user is completing it.
`identity-in-review`	The user finished identity verification, and it is in review.
`reviewing`	The user reviews the quote, the fees and the bank account before withdrawing. It is also reported while the order is being prepared or needs a new rate.
`awaiting-signature`	The component asked the payer to sign and send the deposit, and waits for the wallet.
`confirming-deposit`	The deposit was sent, or may have been sent, and the offramp waits for it to confirm.
`completed`	The deposit is confirmed and the payout to the bank account is in progress. `onComplete` fires.
`payout-completed`	The payout to the bank account is complete. `onComplete` fires if it has not already fired for this order.
`payout-failed`	The payout to the bank account failed. `onError` reports `payout-failed`.
`failed`	The withdrawal cannot continue. `onError` reports why.

orderId is present while an order is on screen, and absent on the amount and bank account screens and when an error ends the session.

One withdrawal can span several orders. After identity verification passes, after the wallet declines the deposit, or when the user takes a new rate, the component creates a new order, so orderId changes. Keep the latest orderId.

Error Reasons

onError reports one of these reasons. When retriable is false, the session cannot continue: unmount the component. When the component shows a failure screen, its Close button calls onCancel. When retriable is true, the same step can succeed on a retry, and in most cases the component shows the problem and lets the user try again. The failed status always ends the session, whatever retriable says.

Reason	Retriable	Meaning	What to do
`invalid-credentials`	No	The session was rejected or can no longer act: its token is not valid, or its one-hour window for new withdrawals has ended.	Create a new session and pass its credentials.
`invalid-configuration`	No	The component is misconfigured, for example its props cannot be read, or the identity verification step failed in a way a retry cannot fix. On React Native, also an HTTP 4xx when loading the offramp. When the props cannot be read, the offramp shows no screen.	Unmount the component and fix the integration, starting with the props and the API key passed to `CrossmintProvider`.
`session-spent`	No	The session cannot start this withdrawal: it was already used, or an earlier withdrawal from this wallet is still being confirmed.	Wait for the earlier withdrawal to settle, then create a new session.
`identity-verification-required`	No	The user must be verified before withdrawing, and the component cannot run the verification, for example because your project collects KYC through the API.	Submit the user’s KYC data (Import User KYC Data), then create a new session.
`identity-verification-failed`	No	The user did not pass identity verification.	Do not start another withdrawal for this user. Failure Reasons lists why verification can fail.
`wallet-ownership-required`	No	The order needs proof that the user owns the payer wallet.	Link the wallet with an ownership `proof` (Link External Wallet to User), then create a new session.
`bank-not-supported`	Yes	The bank account cannot receive this withdrawal, for example from the payer wallet’s chain.	None. The user picks or adds another bank account.
`bank-not-verified`	Yes	The bank account is not verified yet.	None. The component waits for the verification, or the user picks another bank account.
`bank-holder-mismatch`	Yes	The bank account holder’s name does not match the user’s verified identity.	None. The user adds an account in their own name.
`amount-too-low`	Yes	The amount is below the minimum for this bank account.	None. The component shows it on the amount screen.
`amount-too-high`	Yes	The amount is above the user’s current limit.	None. The component shows it on the amount screen.
`exact-payout-unsupported`	Yes	The bank account takes an amount to send, not an amount to receive.	None. The amount screen switches to the amount to send.
`insufficient-funds`	Yes	The wallet does not hold enough stablecoin, or enough gas, for this withdrawal.	Fund the wallet, then the user can try again.
`wallet-rejected`	Yes	The payer threw `OfframpSignatureRejectedError`. The component creates a new order with a fresh rate.	None. The user can confirm again.
`payout-failed`	No	The payout to the bank account failed. When the deposit is refunded, the screen tells the user that their funds are being returned to their wallet.	Look up the order by `orderId` to follow it (Manage Orders).
`provider-error`	Yes	Crossmint could not complete a step, such as a quote, the deposit or identity verification. On React Native, also a connection failure or an HTTP 5xx when loading the offramp.	Let the user try again, and log `message` if it repeats. If the status is `failed`, the withdrawal has ended: follow the order by `orderId` (Manage Orders). On React Native, remount the component, for example by changing its `key`, to retry a page that did not load.
`unknown`	Yes	An unexpected error.	Log `message`.

Sizing

Mode	Height	Container
Content height (default)	The component is at least 650px tall plus padding on every screen, and grows when a screen needs more.	Sets the width. On React Native, put the component in a `ScrollView` if the screen can be shorter than the component.
`fill`	The component fills the container’s height. Content taller than the container scrolls inside the offramp.	On the web, give the container a definite height, such as `100vh` or a fixed height. On React Native, give the parent `flex: 1` or a height; the component uses `flex: 1`.

In both modes the component takes the container’s full width. Changing fill reloads the offramp.

Supported Markets

SEPA bank accounts appear in the component only when the payer wallet’s chain has EURC and your project has euro payouts set up. In a consumer (B2C) project, the user’s verified country of residence must also be in SEPA. Otherwise Add a bank account does not offer SEPA, and a SEPA account the user already saved is shown greyed out as unavailable.

Bank accounts in the Philippines, Indonesia, Thailand, Vietnam and Nigeria are listed in Add a bank account and can be saved, but withdrawals to them fail after identity verification for now. See Countries and Rails for the markets Offramp supports.

Saved Bank Accounts

Users can rename and remove their saved bank accounts in the component. Removing one deletes it from the user’s saved payment methods, so it also disappears from the bank accounts API. The component refuses a removal once the session’s withdrawal was sent, and while another withdrawal from the same wallet is still being confirmed.

Introduction

Quickstarts ⚡

Concepts

Guides

API Reference

Embedded Offramp Reference

Packages

Props

Payer

Refuse a mismatched wallet

Events

Statuses

Error Reasons

Sizing

Supported Markets

Saved Bank Accounts

See Also

​Packages

​Props

​Payer

​Refuse a mismatched wallet

​Events

​Statuses

​Error Reasons

​Sizing

​Supported Markets

​Saved Bank Accounts

​See Also

Packages

Props

Payer

Refuse a mismatched wallet

Events

Statuses

Error Reasons

Sizing

Supported Markets

Saved Bank Accounts

See Also