React Quickstart

Let users withdraw stablecoins to their bank account from your React app

In this guide, you will add a withdrawal flow to a Next.js app with the CrossmintEmbeddedOfframp component and run a withdrawal in the Staging environment. You will:

• Create an offramp session on your server for the user and the wallet they withdraw from
• Render CrossmintEmbeddedOfframp with the session and the user’s Crossmint wallet
• Handle the component’s events
• Test a withdrawal on staging

The component runs the whole withdrawal inside your app: the user picks, adds, renames or removes a bank account, enters an amount, verifies their identity if the order needs it, reviews the quote and approves the deposit from their wallet.

​

Prerequisites

• Server: one server endpoint that creates the session, such as the Next.js server action in this guide.
• API keys: a server-side API key with the orders.create and payment-methods.create scopes, and a client-side API key for the component, both from the staging console.
• Project setup: KYC configured for your project and, for production, Offramp and bank account payment methods enabled on it. Crossmint sets these up per project; contact Crossmint to enable them. You can test the embedded offramp on staging before they are enabled for production.
• Crossmint wallet: an EVM or Solana wallet owned by userId:<USER_ID>, where the user ID is the sub of your JWT. Set up your authentication and the Crossmint providers as in Use Your Own Auth Provider, with base-sepolia as the chain. The session takes only userId: locators, so email and phone locators do not work.
• USDC: testnet USDC in the wallet, from the Circle faucet.

Install the Crossmint client SDK, version 4.13.1 or later:

npm

npm i @crossmint/client-sdk-react-ui

Add your API keys to .env.local. Pass the client-side key to CrossmintProvider as apiKey={process.env.NEXT_PUBLIC_CROSSMINT_API_KEY}:

.env.local

NEXT_PUBLIC_CROSSMINT_API_KEY="_YOUR_CLIENT_API_KEY_"
CROSSMINT_SERVER_SIDE_API_KEY="_YOUR_SERVER_API_KEY_"

1. Create the session on your server

   A session lets one user make one withdrawal from one wallet. Your server makes one call, Create Offramp Session, and the component runs every other step with Crossmint:

   

   Make the call from a server action. Anyone can read a key that ships to the browser, and with your server API key they could open withdrawal sessions for any of your users:

   app/actions/createOfframpSession.ts

   "use server";
   
   interface CreateOfframpSessionParams {
       userId: string;
       receiptEmail: string;
       walletAddress: string;
       chain: string;
   }
   
   export async function createOfframpSession({ userId, receiptEmail, walletAddress, chain }: CreateOfframpSessionParams) {
       const serverApiKey = process.env.CROSSMINT_SERVER_SIDE_API_KEY;
       if (serverApiKey == null) {
           throw new Error("CROSSMINT_SERVER_SIDE_API_KEY is not set");
       }
   
       const response = await fetch("https://staging.crossmint.com/api/unstable/offramp-sessions", {
           method: "POST",
           headers: {
               "Content-Type": "application/json",
               "X-API-KEY": serverApiKey,
           },
           body: JSON.stringify({
               userLocator: `userId:${userId}`,
               payer: { address: walletAddress, chain },
               receiptEmail,
           }),
       });
   
       if (!response.ok) {
           const { code, message } = await response.json().catch(() => ({}));
           throw new Error(`Create Offramp Session failed (${response.status}, ${code ?? "no code"}): ${message ?? response.statusText}`);
       }
   
       const { sessionId, clientSecret } = await response.json();
       return { sessionId, clientSecret };
   }
   

   • userLocator is the user who withdraws, as userId:<USER_ID>.
   • payer is the wallet the deposit is sent from: its address, and its chain (base, base-sepolia, polygon, polygon-amoy or solana). It must be owned by or linked to the user.
   • receiptEmail is where the withdrawal receipt is sent.

   The response carries sessionId and clientSecret, which the component takes as its credentials, and expiresAt, when the session stops accepting new withdrawals (one hour after it is created). The component keeps showing the withdrawal's status for 24 hours. Calling the endpoint again for the same user and wallet returns the same open session until it is used or expires, and that session keeps the receiptEmail it was created with: the one in the new request is ignored.

   Example response (201)

   {
     "sessionId": "ofs_6d0b2c8e-4f1a-4b7e-9c3d-2a5e8f7b1c40",
     "clientSecret": "<CLIENT_SECRET>",
     "expiresAt": "2026-10-26T18:30:00.000Z"
   }
   

   This example takes the user from the caller to stay short. In your app, read the signed-in user’s ID and email from your own server-side session, so no one can open a session for another user.

2. Render the offramp

   Create a client component that creates the session and renders CrossmintEmbeddedOfframp. createCrossmintWalletSigner turns the user’s Crossmint wallet into the payer that signs and sends the deposit:

   app/components/Withdraw.tsx

   "use client";
   
   import { useState } from "react";
   import {
       CrossmintEmbeddedOfframp,
       createCrossmintWalletSigner,
       useWallet,
       type EmbeddedOfframpCredentials,
   } from "@crossmint/client-sdk-react-ui";
   import { createOfframpSession } from "../actions/createOfframpSession";
   
   export default function Withdraw({ userId, email }: { userId: string; email: string }) {
       const { wallet } = useWallet();
       const [credentials, setCredentials] = useState<EmbeddedOfframpCredentials | null>(null);
       const [isLoading, setIsLoading] = useState(false);
   
       if (wallet == null) {
           return <p>Sign in to load your wallet.</p>;
       }
   
       const startWithdrawal = async () => {
           setIsLoading(true);
           try {
               setCredentials(
                   await createOfframpSession({
                       userId,
                       receiptEmail: email,
                       walletAddress: wallet.address,
                       chain: wallet.chain,
                   })
               );
           } catch (error) {
               console.error("Failed to create the offramp session:", error);
           } finally {
               setIsLoading(false);
           }
       };
   
       if (credentials == null) {
           return (
               <button onClick={startWithdrawal} disabled={isLoading}>
                   {isLoading ? "Starting..." : "Withdraw to bank"}
               </button>
           );
       }
   
       const close = () => setCredentials(null);
   
       return (
           <div className="max-w-[450px] w-full mx-auto">
               <button onClick={close}>Close</button>
               <CrossmintEmbeddedOfframp
                   credentials={credentials}
                   payer={createCrossmintWalletSigner(wallet)}
                   onStatusChange={({ status, orderId }) => console.log("Offramp status:", status, orderId)}
                   onComplete={({ orderId, txId }) => console.log("Withdrawal sent:", orderId, txId)}
                   onCancel={close}
                   onError={({ reason, retriable, message }) => console.error("Offramp error:", reason, retriable, message)}
               />
           </div>
       );
   }
   

   Render <Withdraw /> inside the Crossmint providers, with the user ID from your JWT and the user’s email:

   app/page.tsx

   import { Providers } from "./providers";
   import Withdraw from "./components/Withdraw";
   
   export default function Home() {
       return (
           <Providers>
               <main className="min-h-screen flex items-center justify-center">
                   <Withdraw userId="<USER_ID>" email="[e-mail]" />
               </main>
           </Providers>
       );
   }
   

   The component takes the width of its container. It is at least 650px tall plus padding, and grows when a screen needs more. To give it a fixed area instead, pass fill and give the container a definite height. See Sizing.

3. Handle the events

   The component shows its own screens for every step and every error, so the events are for your app's state and your logs:

   • onComplete fires with the orderId and the deposit's txId once the deposit is confirmed and the payout to the bank is on its way. It can fire again for the same order when the user reopens a completed withdrawal, so dedupe by orderId. The payout can still fail afterwards, so confirm the payout on your server.
   • onCancel fires when 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. Unmount the component there. Without onCancel, those buttons do nothing. 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.
   • onError reports a reason, whether it is retriable, and a message for your logs. When retriable is false, the session cannot continue, so unmount the component. When the component shows a failure screen, its Close button calls onCancel. For invalid-credentials, create a new session to start over.
   • onStatusChange reports each step of the flow with the current orderId. The orderId can change within one withdrawal, for example after identity verification or when the user takes a new rate, so keep the latest one. The failed status always ends the session, whatever retriable says.

   Only those three buttons call onCancel. No other screen has a Cancel button, so give the user your own way to close the component, like the Close button in the example above.

   Handle Offramp Events and Errors lists every status and error reason.

4. Test on staging

   1. Fund the wallet with testnet USDC from the Circle faucet.
   2. Click Withdraw to bank, add a US bank account, and enter an amount. Use a bank account number that is unique to your integration.
   3. If the user is not verified yet, verify their identity when the component asks.
   4. Review the quote and confirm with Hold to confirm. The wallet signs and sends the deposit, and the status moves through confirming-deposit to completed, when onComplete fires.

   On staging every payout is simulated and succeeds. To see a failed payout, add the US test bank account from Test a Failed Payout in the component. The SEPA one appears only when SEPA is offered (see SEPA in the Embedded Component).

​

Use an External Wallet

To withdraw from a wallet that Crossmint did not create, link it to the user with Link External Wallet to User before you create the session, and pass your own payer. The component calls its signAndSendTransaction with the deposit to send:

• serializedTransaction: a serialized transaction on EVM chains, or a base58 legacy transaction with feePayer and recentBlockhash set on Solana.
• chain and payerAddress: the chain and wallet the deposit was prepared for. Do not send from a wallet that does not match: check it before you render the component. See Refuse a mismatched wallet.

Sign and broadcast the transaction, then resolve with its transaction ID. Throw OfframpSignatureRejectedError only when the user declines, so the component can offer the withdrawal again with a new rate:

payer.ts

import { OfframpSignatureRejectedError, type EmbeddedOfframpPayer } from "@crossmint/client-sdk-react-ui";

// Your wallet code: sign and broadcast the transaction, and resolve with its transaction ID.
declare function sendWithYourWallet(tx: { serializedTransaction: string; chain: string; payerAddress: string }): Promise<string>;
// Your wallet code: true when the user declined the request in their wallet.
declare function isUserRejection(error: unknown): boolean;

export const payer: EmbeddedOfframpPayer = {
    async signAndSendTransaction(tx) {
        try {
            return await sendWithYourWallet(tx);
        } catch (error) {
            if (isUserRejection(error)) {
                throw new OfframpSignatureRejectedError("The user declined the transaction");
            }
            throw error;
        }
    },
};

If an order needs proof that the user owns the wallet, the component stops with the wallet-ownership-required error. Link the wallet again with an ownership proof, then create a new session. For Solana deposits, see Offramp Orders on Solana.

​

Troubleshooting

The session request fails

Create Offramp Session returns a code that names the problem:

• invalid-user-locator (400): the locator is not userId:<USER_ID>.
• chain-not-supported (400): the chain is not supported, or the address is not valid on it.
• payer-not-linked (400): the wallet is not owned by or linked to this user.
• user-not-found (404): no user with this locator exists in your project. Create the session for the user ID (sub) in your own JWT.
• kyc-not-configured (403): KYC is not configured for your project. Contact Crossmint to set it up.
• addon-required (403): Offramp or bank account payment methods are not enabled for your production project. Contact Crossmint to enable it.
• No code (403): the API key is missing or invalid, is not a server key, or lacks the orders.create or payment-methods.create scope. Create the session from your backend with a server API key that has both scopes. The message names the missing scopes.
• No code (429): your project sent too many requests in a minute. Wait and retry.

Cancel, Continue or Close does nothing

Those buttons call onCancel. Pass an onCancel handler that closes the component.

The session has expired

A session accepts new withdrawals for one hour after it is created. A withdrawal whose deposit was never recorded also ends on this screen when the session's 24-hour status window closes. Create a new session and pass its credentials to the component.

​

Launching in Production

1. Ask Crossmint to enable Offramp and bank account payment methods for your production project (contact Crossmint).
2. Create production API keys with the same scopes in the production console, and replace your staging keys.
3. Create sessions at https://www.crossmint.com/api/unstable/offramp-sessions.
4. Follow Launch in Production for the remaining go-live steps.

​

Learn More

React SDK Reference

Props and types of CrossmintEmbeddedOfframp

Handle Offramp Events and Errors

What each status and error reason means