{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"React Native SDK Integration | xMoney Documentation","description":"Integrate xMoney Payment Sheet, Payment Element, Apple Pay, and Google Pay in React Native apps.","llmstxt":{"hide":false,"title":"xMoney Documentation","description":"Guides and API references for integrating xMoney card and crypto payments.","sections":[{"title":"Guides","description":"Integration guides for card payments, crypto, checkout, and dashboard.","includeFiles":["guides/**/*.md"]},{"title":"Card API","description":"REST API reference and concepts for xMoney card payments.","includeFiles":["api/**/*.md","api/**/*.yaml"]},{"title":"Crypto API","description":"REST API reference and concepts for xMoney crypto payments.","includeFiles":["crypto_api/**/*.md","crypto_api/**/*.yaml"]},{"title":"Card Issuing API","description":"Guides and API reference for xMoney whitelabel card issuing partners.","includeFiles":["card_issuing_api/**/*.md","card_issuing_api/**/*.yaml"]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"react-native-sdk-integration","__idx":0},"children":["React Native SDK Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The xMoney React Native SDK exposes native Payment Sheet, Payment Element, Apple Pay, and Google Pay controls through one TypeScript API. Card fields remain inside native SDK views; PAN and CVV do not cross the JavaScript bridge."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Current release: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1.0.0"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements","__idx":1},"children":["Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["React Native 0.76 or later"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["React Native New Architecture"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["iOS 15 or later"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Android ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minSdk"]}," 23"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A publishable xMoney key and a backend that signs orders"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Expo is supported through the config plugin and a native development or production build. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Expo Go is not supported."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Do not ship a secret key"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Store the xMoney private key on your backend. The app should receive only the publishable key, order payload, and checksum."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-install-the-sdk","__idx":2},"children":["1. Install the SDK"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"npm install @xmoney/react-native@1.0.0\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Install iOS pods, then rebuild the app:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"cd ios\npod install\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Android autolinking registers the native module. Rebuild the Android app after installation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the package has been installed without rebuilding the native app, the SDK throws ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["XMoneyPaymentError"]}," with code ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_LINKED"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"expo-configuration","__idx":3},"children":["Expo configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the config plugin to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app.json"]},", then create a new native build:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"plugins\": [\n    [\n      \"@xmoney/react-native\",\n      {\n        \"merchantIdentifier\": \"merchant.com.example\",\n        \"enableGooglePay\": true\n      }\n    ]\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantIdentifier"]}," configures the iOS Apple Pay capability. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableGooglePay"]}," configures the Android application metadata."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-create-a-paymentintent","__idx":4},"children":["2. Create a PaymentIntent"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your backend creates and signs the order. Build an intent from the returned values:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"const intent = {\n  orderPayload: payloadFromYourServer,\n  orderChecksum: checksumFromYourServer,\n};\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/inline-checkout/web-integration#3-create-the-order-on-your-backend"},"children":["Create the order on your backend"]}," for the shared server responsibilities."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-choose-a-payment-surface","__idx":5},"children":["3. Choose a payment surface"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-sheet","__idx":6},"children":["Payment Sheet"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payment Sheet owns the complete checkout UI and Pay button."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":"import { usePaymentSheet } from '@xmoney/react-native';\n\nfunction CheckoutButton() {\n  const { init, present, loading } = usePaymentSheet();\n\n  const pay = async () => {\n    await init({\n      publicKey: 'pk_test_...',\n      paymentMethods: {\n        applePay: { enabled: true },\n        googlePay: { enabled: true },\n      },\n      card: {\n        savedCards: { enabled: true },\n      },\n    });\n\n    const result = await present(intent, (event) => {\n      if (event.type === 'ready') {\n        hideCheckoutLoader();\n      }\n    });\n\n    handlePaymentResult(result);\n  };\n\n  return <Button title=\"Pay\" onPress={pay} disabled={loading} />;\n}\n","lang":"tsx"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Idle close, drag, or scrim dismissal returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ status: 'canceled' }"]}," without consuming the order. Once payment or 3DS starts, terminal results consume the signed order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"payment-element","__idx":7},"children":["Payment Element"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payment Element places the native payment form inside your React Native layout."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":"import { PaymentElement } from '@xmoney/react-native';\n\n<PaymentElement\n  configuration={{\n    publicKey: 'pk_test_...',\n    paymentMethods: {\n      applePay: { enabled: true },\n      googlePay: { enabled: true },\n    },\n  }}\n  intent={intent}\n  onEvent={(event) => {\n    if (event.type === 'ready') {\n      hideCheckoutLoader();\n    }\n  }}\n  onResult={handlePaymentResult}\n/>;\n","lang":"tsx"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payment Element adds no outer page padding or background. Keep it mounted while it binds an order, and provide the surrounding layout in your app."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use your own Pay button, hide the SDK button and call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirm()"]}," after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ready"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":"import {\n  PaymentElement,\n  type PaymentElementRef,\n} from '@xmoney/react-native';\n\nconst elementRef = useRef<PaymentElementRef>(null);\n\n<PaymentElement\n  ref={elementRef}\n  configuration={{\n    publicKey: 'pk_test_...',\n    card: {\n      submitButton: { visible: false },\n    },\n  }}\n  intent={intent}\n  onResult={handlePaymentResult}\n/>;\n\n<Button\n  title=\"Pay\"\n  onPress={() => elementRef.current?.confirm()}\n/>;\n","lang":"tsx"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availability"]}," event's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isInteractionEnabled"]}," value to disable the merchant button while the order updates or payment is processing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"standalone-wallets","__idx":8},"children":["Standalone wallets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Apple Pay is available only on iOS; Google Pay is available only on Android. Unsupported wallet button components render nothing."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":"import {\n  ApplePayButton,\n  GooglePayButton,\n} from '@xmoney/react-native';\n\n<ApplePayButton\n  configuration={{ publicKey: 'pk_test_...' }}\n  intent={intent}\n  appearance={{ color: 'black', type: 'buy' }}\n  onResult={handlePaymentResult}\n/>;\n\n<GooglePayButton\n  configuration={{ publicKey: 'pk_test_...' }}\n  intent={intent}\n  appearance={{ color: 'black', type: 'buy' }}\n  onResult={handlePaymentResult}\n/>;\n","lang":"tsx"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For imperative flows, use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplePay.init"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["getState"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["present"]},", or the corresponding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GooglePay"]}," methods. Check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isAvailable"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isReady"]}," before showing custom wallet UI."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A wallet dismissal before authorization returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]}," and does not consume the intent."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payments/payment-methods/apple-pay"},"children":["Apple Pay"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payments/payment-methods/google-pay"},"children":["Google Pay"]}," for activation requirements."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handle-paymentresult","__idx":9},"children":["Handle PaymentResult"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"function handlePaymentResult(result: PaymentResult) {\n  switch (result.status) {\n    case 'complete':\n      confirmOrderOnBackend(result.transaction);\n      break;\n    case 'failed':\n      showPaymentError(result.error.message);\n      break;\n    case 'canceled':\n      showCheckout();\n      break;\n  }\n}\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the result to update the app, then confirm final payment status on your backend before fulfillment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"update-a-mounted-payment-element","__idx":10},"children":["Update a mounted Payment Element"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the amount, currency, or cart changes, request a new signed order and rebind the mounted element:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":"await elementRef.current?.updateOrder(nextIntent);\n","lang":"tsx"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Changing the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intent"]}," prop also updates the order. Keep the component mounted; use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isInteractionEnabled"]}," for loading and button state."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For live styling changes, call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateAppearance"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateStyle"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateLocale"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateWalletAppearance"]}," on the ref. Changing core configuration may remount the native view."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":11},"children":["Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PaymentConfig"]}," controls saved cards, card validation, field grouping, submit-button intent, locale, light/dark style, colors, and radii."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"const configuration = {\n  publicKey: 'pk_test_...',\n  card: {\n    savedCards: {\n      enabled: true,\n      optInVisible: true,\n    },\n    validationMode: 'onTouched',\n    inputs: {\n      grouping: 'condensed',\n    },\n  },\n  options: {\n    locale: 'en-US',\n    style: 'automatic',\n  },\n};\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported UI languages are English (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en"]},"), Greek (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["el"]},"), Romanian (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ro"]},"), Bulgarian (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bg"]},"), Hungarian (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hu"]},"), and Polish (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pl"]},"). Region tags such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pl-PL"]}," are supported."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For cardholder name verification, provide a callback in the card configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"card: {\n  cardHolderVerification: {\n    name: {\n      firstName: 'John',\n      lastName: 'Doe',\n    },\n    onCardHolderVerification: (result) =>\n      result.status === 'Matched',\n  },\n},\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The site must have cardholder name verification enabled."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":12},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Review the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/checkout/native-sdks"},"children":["native SDK shared model"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/payments/testing"},"children":["test cards"]}," in the test environment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Explore the complete ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/xMoney-Payments/xmoney-react-native/tree/main/example"},"children":["React Native SDK samples"]},"."]}]}]},"headings":[{"value":"React Native SDK Integration","id":"react-native-sdk-integration","depth":1},{"value":"Requirements","id":"requirements","depth":2},{"value":"1. Install the SDK","id":"1-install-the-sdk","depth":2},{"value":"Expo configuration","id":"expo-configuration","depth":3},{"value":"2. Create a PaymentIntent","id":"2-create-a-paymentintent","depth":2},{"value":"3. Choose a payment surface","id":"3-choose-a-payment-surface","depth":2},{"value":"Payment Sheet","id":"payment-sheet","depth":3},{"value":"Payment Element","id":"payment-element","depth":3},{"value":"Standalone wallets","id":"standalone-wallets","depth":3},{"value":"Handle PaymentResult","id":"handle-paymentresult","depth":2},{"value":"Update a mounted Payment Element","id":"update-a-mounted-payment-element","depth":2},{"value":"Configuration","id":"configuration","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"React Native SDK Integration | xMoney Documentation","description":"Integrate xMoney Payment Sheet, Payment Element, Apple Pay, and Google Pay in React Native apps."}},"lastModified":"2026-09-10T09:47:36.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/checkout/native-sdks/react-native","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}