Integrate the Embedded Components onrampPrivate preview

Step 1: Install the Stripe React Native SDK

Follow the installation instructions in the README to install the Stripe React Native SDK.

Step 2: Add the onramp dependency Client-side

By default, the onramp dependency isn’t included in the Stripe React Native SDK to reduce bundle size. Include it as follows, depending on your platform.

# android/gradle.properties
StripeSdk_includeOnramp=true

# ios/Podfile – add pod
pod 'stripe-react-native/Onramp', path: '../node_modules/@stripe/stripe-react-native'

Step 3: Use StripeProvider Client-side

Wrap your app with StripeProvider at a high level so Stripe functionality is available throughout your component tree. Key properties:

• publishableKey – Your Stripe publishable key.
• merchantIdentifier – Your Apple Merchant ID (required for Apple Pay).
• urlScheme – Required for return URLs in authentication flows.

This component is essential for initializing the Stripe SDK in your React Native application before using payment-related features.

import { StripeProvider } from '@stripe/stripe-react-native';

function App() {
  return (
    <StripeProvider
      publishableKey="pk_test_..."
      merchantIdentifier="merchant.identifier"
      urlScheme="your-url-scheme"
    >
      {/* Your app components */}
    </StripeProvider>
  );
}

Step 4: Configure the onramp SDK Client-side

Before any onramp APIs can be called successfully, you’ll need to configure the SDK using the configure method. It’s provided by the useOnramp() hook. configure takes an instance of Onramp.Configuration to customize your business display name and lightly customize elements in Stripe-provided interfaces, such as the user’s wallet, one-time passcode authorization, and identity verification UI.

import { useOnramp } from '@stripe/stripe-react-native';

function OnrampComponent() {
  const { configure } = useOnramp();

  const setupOnramp = useCallback(async () => {
    const result = await configure({
      merchantDisplayName: 'My Crypto App',
      appearance: {
        lightColors: {
          primary: '#2d22a1',
          contentOnPrimary: '#ffffff',
          borderSelected: '#07b8b8'
        },
        darkColors: {
          primary: '#800080',
          contentOnPrimary: '#ffffff',
          borderSelected: '#526f3e'
        },
        style: 'ALWAYS_DARK',
        primaryButton: { cornerRadius: 8, height: 48 }
      }
    });

    if (result.error) {
      console.error('Configuration failed:', result.error.message);
    }
  }, []);

  React.useEffect(() => {
    setupOnramp();
  }, []);

  return null;
}

Step 1: Check for a Link account Client-side

The user must have a Link account to use the onramp APIs. Use hasLinkAccount to determine if the user’s email is associated with an existing Link account. See the HasLinkAccountResult for the return type and the OnrampError for the error type.

• If they have an account, proceed to Authorize.
• If they don’t, use Register a new Link user, then proceed to Authorize.

const { hasLinkAccount, registerLinkUser, authorize } = useOnramp();

const linkResult = await hasLinkAccount('user@example.com');
if (linkResult.error) return;

if (linkResult.hasLinkAccount) {
  // Proceed to authorization.
} else {
  // Register the user first (see next step).
}

function AuthComponent() {
  const { hasLinkAccount, registerLinkUser } = useOnramp();

  const handleAuth = useCallback(async () => {
    const linkResult = await hasLinkAccount('user@example.com');

    if (linkResult.error) return;

    if (linkResult.hasLinkAccount) {
      // Proceed to authorization.
    } else {
      const userInfo = {
        email: 'user@example.com',
        phone: '+12125551234',
        country: 'US',
        fullName: 'John Smith',
      };

      const registerResult = await registerLinkUser(userInfo);

      if (registerResult.error) {
      } else if (registerResult.customerId) {
        // Proceed to authorization.
      }
    }
  }, []);

  return <Button title="Authenticate" onPress={handleAuth} />;
}

Step 2: Register a new Link user (if needed) Client-side

If the user doesn’t have a Link account, use registerLinkUser to create one with user information collected from your UI. Upon successful account creation, proceed to Authorize. See the RegisterLinkUserResult for the return type and the OnrampError for the error type.

const userInfo = {
  email: 'user@example.com',
  phone: '+12125551234',
  country: 'US',
  fullName: 'John Smith',
};
const registerResult = await registerLinkUser(userInfo);
if (registerResult.error) return;
if (registerResult.customerId) {
  // Proceed to authorization.
}

Step 3: Authorize Client-side Server-side

The primary method of authentication is via two-factor authorization.

3a. Create a LinkAuthIntent

A LinkAuthIntent tracks scopes of the OAuth requests and the status of user consent. Your backend calls the Create a LinkAuthIntent API with the onramp OAuth scopes, get authIntentId, and send it to the client.

OAuth scopes used when creating a LinkAuthIntent:

// createAuthIntent is a client-side function you must implement.
// Call your back end to create a LinkAuthIntent using the API.
const authIntentResponse = await createAuthIntent(
  email,
  // This is your OAUTH_CLIENT_ID, which identifies your application in the Link OAuth flow.
  authToken,
  'kyc.status:read,crypto:ramp'
);
const authIntentId = authIntentResponse.data.authIntentId;

3b. User consents

The client calls authorize with the authIntentId to complete consent. The authorize SDK looks up and verifies the user’s Link session, shows them what your app is requesting (the OAuth scopes) on a consent screen or inline on the OTP screen, and collects their approval.

The SDK then sends that consent to Stripe so your backend can exchange the intent for an access token and finish the flow. The result includes a customerId that must be used for all subsequent onramp API calls. See the AuthorizeResult for the return type and the OnrampError for the error type.

const result = await authorize(authIntentId);

if (result?.error) {
  // An error occurred. Stop here.
} else if (result?.status === 'Consented' && result.customerId) {
  // Authorization successful; exchange for access token.
} else if (result?.status === 'Denied') {
  // The user denied authorization. Stop here.
} else {
  // The user canceled authorization. Stop here.
}

3c. Request access tokens

If the result is Consented, your backend calls the Retrieve Access Tokens API to request access tokens. Store the access token and use it on all subsequent onramp API requests (for example, in the Stripe-OAuth-Token header).

# Request
curl -X POST https://login.link.com/v1/link_auth_intent/{authIntentId}/tokens \
  -H "Authorization: Bearer $STRIPE_SECRET_KEY"

# Response
{
  "access_token": "liwltoken_xxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh": {
    "refresh_token": "liwlrefresh_xxx",
    "expires_in": 7776000
  }
}

Step 1: Check if KYC collection is needed Server-side

Your backend calls the Retrieve a CryptoCustomer API with the customerId. Inspect the response verifications array. If it includes an entry with type kyc_verified and status not_started, proceed to Collect KYC.

curl https://api.stripe.com/v1/crypto/customers/{customerId} \
  -H "Authorization: Bearer $STRIPE_SECRET_KEY" \
  -H "Stripe-OAuth-Token: $ACCESS_TOKEN"

async function getCryptoCustomer(req, res) {
  const { id } = req.params;
  const oauthToken = req.headers['stripe-oauth-token'];

  const response = await fetch(
    `https://api.stripe.com/v1/crypto/customers/${id}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
        'Stripe-OAuth-Token': oauthToken ?? '',
      },
    }
  );

  const customer = await response.json();

  const verifications = customer.verifications ?? [];
  const kycVerified = verifications.find((v) => v.name === 'kyc_verified');
  const idDocVerified = verifications.find(
    (v) => v.name === 'id_document_verified'
  );

  res.json({
    customerId: customer.id,
    providedFields: customer.provided_fields ?? [],
    kycStatus: kycVerified?.status ?? 'not_started',
    idDocStatus: idDocVerified?.status ?? 'not_started',
  });
}

Step 2: Collect KYC (if needed) Client-side

If the customer needs KYC verification, your client calls attachKycInfo to collect and submit user KYC data. Present your own interface to the user to collect this KYC information. See the KycInfo for the return type and the OnrampError for the error type.

import { useOnramp } from '@stripe/stripe-react-native';

function AttachKYCComponent() {
  const { attachKycInfo } = useOnramp();

  const handleAttachKycInfo = useCallback(async () => {
    const kycInfo = {
      firstName: "FirstName",
      lastName:"LastName",
      idNumber: '000000000',
      dateOfBirth: { day: 1, month: 1, year: 1990, },
      address: {
        line1: '123 Main St',
        line2: 'Apt 4B',
        city: 'San Francisco',
        state: 'CA',
        postalCode: '94111',
        country: 'US',
      },
    };

    const result = await attachKycInfo(kycInfo)

    if (result?.error) {
      // KYC information failed to attach.
    } else {
      // KYC information attached successfully.
    }
  }, []);

  return <Button title="Attach KYC" onPress={handleAttachKycInfo} />;
}

Step 3: Verify KYC (if needed) Client-side

When a user already has KYC information, use presentKycInfoVerification so the SDK can present a screen with the user’s existing KYC information for verification. Currently, we only support users updating their address. See the VerifyKycResult for the return type and the OnrampError for the error type.

import { useOnramp } from '@stripe/stripe-react-native';

function VerifyKYCComponent() {
  const { presentKycInfoVerification } = useOnramp();

  const handlePresentKycVerification = useCallback(
    async (updatedAddress: Address | null) => {
      const result = await presentKycInfoVerification(updatedAddress);

      if (result?.error) {
        if (result.error.code === 'Canceled') {
          // KYC Verification was canceled by the user.
        } else {
          // An error occurred during verification.
        }
      } else if (result?.status === 'Confirmed') {
          // KYC information was verified by the user.
      } else if (result?.status === 'UpdateAddress') {
        // User indicated that their address needs to be updated.
      } else {
        // KYC Verification was canceled by the user.
      }
  }, []);

  return <Button title="Verify KYC" onPress={handlePresentKycVerification} />;
}

Step 4: Verify identity (if needed) Client-side

Some users must verify their identity before continuing with checkout. When required, use the verifyIdentity method. It presents a Stripe-hosted flow where the user uploads an identity document and a selfie.

Verification is asynchronous. After the user completes the flow, your backend can call the Retrieve a CryptoCustomer API and inspect the verifications array to see the results.

import { useOnramp } from '@stripe/stripe-react-native';

function VerifyIdentityComponent() {
  const { verifyIdentity } = useOnramp();

  const handleVerifyIdentity = useCallback(async () => {
    const result = await verifyIdentity();

    if (result?.error) {
      if (result.error.code === 'Canceled') {
        // Identity verification was cancelled.
      } else {
        // Error occurred during verification.
      }
    } else {
        // Identity verification was completed.
    }
  }, []);

  return <Button title="Verify Identity" onPress={handleVerifyIdentity} />;
}

Step 1: Register a crypto wallet Client-side Server-side

A ConsumerWallet must be registered before you can create a PaymentToken. This validates that the address is valid for the given network. Your backend can call the List ConsumerWallets API to see whether the user already has wallets on file.

If the list is empty or the user wants to add another address, have the client call registerWalletAddress with the user’s chosen address and network. Replace the address and network with user-provided values. A previously registered wallet can be reused in future sessions.

curl "https://api.stripe.com/v1/crypto/customers/{customerId}/crypto_consumer_wallets" \
  -H "Authorization: Bearer $STRIPE_SECRET_KEY" \
  -H "Stripe-OAuth-Token: $ACCESS_TOKEN"

Step 2: Collect a payment method Client-side Server-side

A payment method must first be collected before a transaction can occur. Your backend can call the List PaymentTokens API to see which payment methods the user already has. If the list is empty or the user wants to use a different method, have the client call collectPaymentMethod.

Card, Bank Account, and Apple Pay are supported. For Card and Bank Account, collectPaymentMethod presents Stripe’s wallet user interface, which lists existing stored payment methods, allows the user to add new ones, and select one. Upon successful payment method selection, it returns an instance of CollectPaymentMethodResult, which includes a displayData property (icon, label, sublabel) that you can use in your UI to show the selected payment method.

curl https://api.stripe.com/v1/crypto/customers/{customerId}/payment_tokens \
  -H "Authorization: Bearer $STRIPE_SECRET_KEY" \
  -H "Stripe-OAuth-Token: $ACCESS_TOKEN"

To collect Apple Pay, first check isPlatformPaySupported in useStripe(). See Apple Pay on React Native. If the user chooses Apple Pay, pass an instance of PlatformPay.PaymentMethodParams into collectPaymentMethod.

Step 3: Create a payment token Client-side

Create a PaymentToken by calling createCryptoPaymentToken. Use the returned token when creating the CryptoOnrampSession.

import { useOnramp } from '@stripe/stripe-react-native';

function CreatePaymentTokenComponent() {
  const { createCryptoPaymentToken } = useOnramp();

  const handleCreateCryptoPaymentToken = useCallback(async () => {
    const result = await createCryptoPaymentToken();
    if (result?.error) {
      // An error occurred while creating a crypto payment token.
    } else {
      // Use result.cryptoPaymentToken in your payment session.
    }
  }, []);

  return <Button title="Create Payment Token" onPress={handleCreateCryptoPaymentToken} />;
}

Step 4: Create a crypto onramp session Server-side

From your UI, determine the amount, source currency (for example, usd), destination currency (for example, usdc), and network. Your backend calls the Create a CryptoOnrampSession API to create a CryptoOnrampSession. The Stripe React Native SDK doesn’t provide APIs for creating a crypto onramp session. It happens on your backend. The example below shows how a client application might call your backend. Adapt it to your use case.

When the user is paying with ACH, you can optionally pass settlement_speed on create session (private feature; contact us if you need this).

function CreateOnrampSessionComponent() {
  const handleCreateOnrampSession = useCallback(async () => {
    // createOnrampSession is a client-side function you must implement.
    // Call your back end to create a CryptoOnrampSession using the API.
    const result = await createOnrampSession(
      "headless",
      cryptoCustomerId,
      cryptoPaymentToken,
      100.0,
      "usd",
      "usdc",
      walletAddress,
      Onramp.CryptoNetwork.bitcoin
    );

    if (result.success) {
        const sessionId = result.data.id;
    } else {
        // An error occurred.
    }
  }, []);

  return <Button title="Create onramp Session" onPress={handleCreateOnrampSession} />;
}

Step 5: Perform checkout Client-side Server-side

Call performCheckout to run the checkout flow for a crypto onramp session. It presents a UI for any required actions such as 3DS.

You must implement the client-side callback fetchClientSecretFromBackend, which the SDK invokes to retrieve the checkout client secret. Have it call your back end, which calls the onramp session checkout endpoint with the session ID. The response includes the client_secret, which your callback can then return to the SDK.

For ACH, the API may indicate that mandate_data is missing. Collect acceptance and send it on a later checkout call if required.

import { useOnramp } from '@stripe/stripe-react-native';

function CheckoutComponent() {
  const { performCheckout } = useOnramp();

  const handleCheckout = useCallback(async () => {
    const result = await performCheckout(sessionId, async () => {
      // fetchClientSecretFromBackend is a client-side function you must implement.
      // It calls your back end, which calls the onramp session checkout endpoint with the session ID
      // and returns the client_secret from the response.
      // Return the client secret on success, or throw an Error on failure.
      const clientSecret = await fetchClientSecretFromBackend(sessionId);
      return clientSecret;
    });

    if (result.error) {
      if (result.error.code === 'Canceled') {
        // The checkout process was canceled by the user.
      } else {
        // An error occurred while checking out.
      }
    } else {
      // Checkout was completed successfully.
    }
  }, []);

  return <Button title="Complete Purchase" onPress={handleCheckout} />;
}

When the API returns 200 or 202 but the purchase isn’t done, the response body includes the CryptoOnrampSession object with transaction_details.last_error set. Use that value to decide the next step: