React Native SDK

It wraps the native iOS and Android SDKs. The SDK does not render card input or carry card data; capture happens on the provider’s own surface.

Install

npm install @meldcrypto/react-native-sdk

The wrapper autolinks. The native SDK it depends on is not an RN module, so wire it per platform.

iOS

The wrapper needs iOS 15 or later, and its pod pulls in MeldSDK from CocoaPods trunk. For Stripe orders, pin MeldSDK to 0.9.1 or a later 0.9 release. Nothing checks the version at run time: a build that resolved 0.8.x or 0.9.0 still mounts Stripe orders, without the Stripe fixes in 0.9.1. Bare React Native. Add the pin to your app target in ios/Podfile:

pod 'MeldSDK', '~> 0.9.1'

Then install with static frameworks, since the native SDK is a Swift pod:

cd ios && USE_FRAMEWORKS=static pod install

If Podfile.lock already holds an older MeldSDK, run pod update MeldSDK as well. Expo. Install expo-build-properties with npx expo install expo-build-properties, then pin the pod in your app config. The pin applies from the next native build (EAS Build, or npx expo prebuild --clean):

"plugins": [
  ["expo-build-properties", { "ios": { "extraPods": [{ "name": "MeldSDK", "version": "~> 0.9.1" }] } }]
]

After you build, check that Podfile.lock lists MeldSDK (0.9.1) or later. Native support comes only with a new app build; an over-the-air JavaScript update cannot add it.

Android

Nothing beyond autolinking. The wrapper’s Gradle module pulls the native Android SDK from Maven Central. Requires minSdk 24. The library declares INTERNET and CAMERA; camera is used for KYC capture inside a provider’s surface and merges into your manifest automatically.

iOS permissions

Declare NSCameraUsageDescription in your iOS Info.plist, with a string that explains the document and selfie capture. Providers that run KYC inside their surface need it, and so does Stripe’s identity check, which the SDK refuses without it. In Expo, set it under ios.infoPlist. The Meld config plugin does not add it.

"ios": {
  "infoPlist": {
    "NSCameraUsageDescription": "Used to capture your ID and a selfie for identity verification."
  }
}

Create the order on your backend

The order comes from your server. Your API key never ships in the app binary. See Cards or Apple Pay for the request. Return the response to the app unchanged: the SDK reads what it needs from it.

Mount the order

import { Meld, MeldWidget } from '@meldcrypto/react-native-sdk';

Meld.configure('sandbox'); // or 'production'

const { surface } = await Meld.capabilities(order);
if (surface === 'unsupported') return offerAnotherMethod();

<MeldWidget
  order={order}
  onReady={() => hideSpinner()}
  onStatusChange={(s) => track(s)}
  onPaymentSubmitted={() => showProcessing()}
  onCancel={() => backToCheckout()}
  onError={(e) => showError(e.message)}
/>

Call Meld.configure once, before you check or mount an order, with the environment your backend created the order in. See Environments. To check a quote before you create the order, pass its paymentMethodType and headlessPresentation to Meld.presentationCapabilities, then check the order itself again before you mount it. This works on iOS only. On Android it reports unsupported for every quote, so don’t use it to hide methods there. Keep the component mounted until a terminal callback. Unmounting tears the surface down and delivers no callback. On onPaymentSubmitted, navigating away is how you unmount it. Apple Pay and Stripe orders draw nothing in the component, so a zero-size component is enough for them.

Apple Pay

Same component, plus an applePay prop carrying what the order does not:

if (await Meld.canPresentApplePay()) {
  <MeldWidget
    order={order}
    applePay={{
      amount: '100.00',              // must match the order
      currencyCode: 'USD',           // must match the order
      summaryItemLabel: 'Acme — Buy USDC',
    }}
    onPaymentSubmitted={() => showProcessing()}
    onCancel={() => backToCheckout()}
    onError={(e) => showError(e.message)}
  />
}

Pass applePay for any Apple Pay order without checking which provider it routed to: choosing the surface is the SDK’s job. A malformed prop reports INVALID_APPLE_PAY_REQUEST. Add walletAddress and clientIpAddress, with the values the order was created with, in two cases: the order’s response has neither headlessPresentation nor paymentActions, or an over-the-air update can deliver your JavaScript to a binary built with React Native SDK 0.7 or older. canPresentApplePay() is true only when Wallet holds a card. It is always false on Android, which does not present Apple Pay. Mount from the customer’s tap on your Apple Pay button.

Expo config plugin

Mercuryo, Banxa and Stripe present the sheet under your merchant identifier, so your app needs the Apple Pay entitlement. Register the identifiers and certificates first, as in Apple Developer setup.

"plugins": [
  ["@meldcrypto/react-native-sdk/plugin", { "merchantIds": [
    "merchant.com.yourcompany.app",
    "merchant.com.yourcompany.app.stripe",
    "merchant.com.yourcompany.app.stripe.sandbox"
  ]}]
]

List every identifier an order can carry, including both your sandbox and your live Stripe identifier. The plugin writes only the Apple Pay entitlement, and merges these identifiers with any that other plugins add. Bare React Native projects add the same entitlement in Xcode. Coinbase needs none of this.

Provider notes

The same <MeldWidget> presents every provider’s order, with the requirements in iOS → Provider notes. On React Native:

Stripe needs iOS, in a native build with React Native SDK 0.8.0 or later and the MeldSDK version in Install. On an Apple Pay order, an applePay you pass must carry the order’s amount and currencyCode: 'USD', or the component reports MOUNT_FAILED.
Coinbase needs iOS 16 or later.

On Android, and in a binary built with React Native SDK 0.7 or older, Meld.capabilities(order) reports unsupported for both, so leave them out.

Events

Event	Meaning
`onReady`	The surface has loaded, or the Apple Pay sheet is opening
`onStatusChange`	Carries a normalized status: `pending`, `completed`, `failed` or `cancelled`
`onPaymentSubmitted`	The user finished paying. Unmount and show processing. Not settlement
`onCancel`	The user backed out, or dismissed the Apple Pay sheet. Nothing will settle
`onError`	Carries a `code`, a `message`, `recoverable` and `detail`

The five events covers what each one means, how onCancel and onError relate to the status, and the one-terminal-callback rule.

Error codes

On iOS, onError uses the iOS SDK’s codes. This SDK has no attemptMayExist, so decide by code: no payment exists for any code in that table except PAYMENT_OUTCOME_UNKNOWN, or for this SDK’s own codes below. Treat any other non-recoverable code as a payment that may exist. This SDK’s own codes are raised before anything is mounted: INVALID_ORDER, INVALID_APPLE_PAY_REQUEST, MOUNT_FAILED and UNSUPPORTED_NATIVE_PROTOCOL. Fix the input, or offer another method.

Settlement

Settlement is your webhook, never an SDK event. On onPaymentSubmitted, unmount and show a pending state. See Configure webhooks.

Welcome

AI Toolkit

Meld API

Stablecoins & Digital Assets

Bank Linking

React Native SDK

Install

iOS

Android

iOS permissions

Create the order on your backend

Mount the order

Apple Pay

Expo config plugin

Provider notes

Events

Error codes

Settlement

​Install

​iOS

​Android

​iOS permissions

​Create the order on your backend

​Mount the order

​Apple Pay

​Expo config plugin

​Provider notes

​Events

​Error codes

​Settlement

Install

iOS

Android

iOS permissions

Create the order on your backend

Mount the order

Apple Pay

Expo config plugin

Provider notes

Events

Error codes

Settlement