React Native · Solana / USDC

// Generic Node.js handler — adapt signature to your platformasync function createMoneyGramSession(req, res) {  // CORS — restrict to your own origins  const origin = req.headers.origin  const allowedOrigins = ['https://yourapi.com']  if (allowedOrigins.includes(origin)) {    res.setHeader('Access-Control-Allow-Origin', origin)    res.setHeader('Vary', 'Origin')  }  res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS')  res.setHeader('Access-Control-Allow-Headers', 'Content-Type')  if (req.method === 'OPTIONS') return res.status(204).end()  if (req.method !== 'POST') return res.status(405).end()   const secretKey = process.env.MONEYGRAM_SK  // ramps_sk_sbox_... — never in the app binary  if (!secretKey) return res.status(500).json({ error: 'Secret key not configured' })   const { walletAddress } = req.body ?? {}   const mgiRes = await fetch('https://playground.xramps.moneygram.com/api/v1/sessions', {    method:  'POST',    headers: { 'Content-Type': 'application/json', 'x-api-key': secretKey },    body: JSON.stringify({      walletAddress, // end-user Solana address      chain: 'solana',    }),  })   const data = await mgiRes.json()  if (!mgiRes.ok) return res.status(mgiRes.status).json(data)   return res.status(200).json({    sessionToken: data.sessionToken,  // JWT — used in RAMPS_CONFIG    sessionId:    data.sessionId,    widgetUrl:    data.widgetUrl,     // widget URL — provided by MoneyGram, do not hardcode  })}

{  "sessionToken": "eyJhbGci...",  "sessionId":    "b4641a16-2b96-4afe-acb6-b71682305d08",  "widgetUrl":    "https://playground.xramps.moneygram.com/widget.html?mode=off-ramp"}

npm install react-native-webview @solana/web3.js @solana/spl-token @react-native-async-storage/async-storage # iOS — install native podsnpx pod-install

<uses-permission android:name="android.permission.INTERNET" />

// ─── Status and error enums ────────────────────────────────────────────────── export const TransactionStatus = {  QuotePending:    'quote_pending',  KycPending:      'kyc_pending',  AwaitingFunds:   'awaiting_funds',  FundsReceived:   'funds_received',  Completed:       'completed',  RefundRequested: 'refund_requested',  Refunded:        'refunded',} as constexport type TransactionStatus = typeof TransactionStatus[keyof typeof TransactionStatus] // ─── Customer / session types ───────────────────────────────────────────────── export interface CustomerProfile {  // Personal  firstName?:                string  middleName?:               string  lastName?:                 string  secondLastName?:           string  dateOfBirth?:              string   // YYYY-MM-DD   // Contact  email?:                    string  phone?:                    string   // National number, no country prefix  phoneCountryDialCode?:     string   // Dial code for phone, leading "+", e.g. "+33"   // Address  addressLine1?:             string  city?:                     string  postalCode?:               string  countryCode?:              string   // ISO 3166-1 alpha-3 e.g. USA — defaults to USA  countrySubdivisionCode?:   string   // ISO 3166-2 e.g. US-TX — required for USA/MEX/CAN senders   // Nationality (optional)  birthCountryCode?:         string   // ISO 3166-1 alpha-3  citizenshipCountryCode?:   string   // ISO 3166-1 alpha-3   // Identity  idType?:                   'PAS' | 'DRV' | 'STA' | 'GOV'  idNumber?:                 string  idIssueCountry?:           string   // ISO 3166-1 alpha-3  idCountrySubdivisionCode?: string   // ISO 3166-2 — required for DRV/STA issued in USA or Canada} export interface MgiRecord {  id:              string              // Ramps transactionId — needed to reopen in view mode  referenceNumber: string              // Shown to recipient at MoneyGram agent location  amount:          string              // USDC amount sent on-chain  asset:           'USDC'  status:          TransactionStatus  createdAt:       number              // unix ms} interface Session {  sessionToken: string  sessionId:    string  widgetUrl:    string}

import {  Connection, PublicKey, Transaction, ComputeBudgetProgram,  type SendTransactionOptions, type TransactionSignature,} from '@solana/web3.js'import {  getAssociatedTokenAddress,  createAssociatedTokenAccountIdempotentInstruction,  createTransferInstruction,} from '@solana/spl-token' // Use the standard SPL USDC mint only.// Token 2022 / token-extensions USDC is not supported by Ramps.const USDC_MINT_MAINNET = new PublicKey('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v')const USDC_MINT_DEVNET  = new PublicKey('4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU') async function sendUsdc(  wallet:     { publicKey: PublicKey; sendTransaction: (tx: Transaction, conn: Connection, opts?: SendTransactionOptions) => Promise<TransactionSignature> },  connection: Connection,  to:         string,  amount:     string,   // exact string from RAMPS_SIGN_TRANSACTION — do not round  mint:       PublicKey = USDC_MINT_MAINNET,): Promise<string> {  const toKey   = new PublicKey(to)  const fromATA = await getAssociatedTokenAddress(mint, wallet.publicKey)  const toATA   = await getAssociatedTokenAddress(mint, toKey, true)   const tx = new Transaction()   // Priority fee — prevents transactions being dropped during mainnet congestion.  // Adjust microLamports based on current network conditions; 50_000 is a safe default.  // Use Helius or Triton priority fee APIs for dynamic estimates in production.  tx.add(ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 50_000 }))  tx.add(ComputeBudgetProgram.setComputeUnitLimit({ units: 100_000 }))   // Creates the recipient's token account if it doesn't exist yet.  // The idempotent version is a no-op if the account already exists.  tx.add(createAssociatedTokenAccountIdempotentInstruction(    wallet.publicKey, toATA, toKey, mint,  ))   // USDC uses 6 decimal places. Avoid float arithmetic on financial amounts —  // parseFloat can produce IEEE 754 drift (e.g. 0.1 + 0.2 !== 0.3).  // Split on the decimal point and construct the BigInt from integer parts.  const [whole, frac = ''] = amount.split('.')  const lamports = BigInt(whole) * 1_000_000n + BigInt(frac.padEnd(6, '0').slice(0, 6))   tx.add(createTransferInstruction(    fromATA, toATA, wallet.publicKey, lamports,  ))   // Fetch the blockhash as late as possible — after building the transaction but  // before simulating. The blockhash expires in ~90 seconds (~150 slots). Fetching  // early (e.g. before user confirmation UI) wastes that window on mobile.  const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash()  tx.recentBlockhash = blockhash  tx.feePayer        = wallet.publicKey   // Simulate before signing — catches bad addresses and insufficient balance  // before an irreversible on-chain error.  const simulation = await connection.simulateTransaction(tx)  if (simulation.value.err) {    throw new Error(`Transaction simulation failed: ${JSON.stringify(simulation.value.err)}`)  }   const sig = await wallet.sendTransaction(tx, connection)   // Confirm using blockhash expiry rather than polling on the signature alone.  // This throws TransactionExpiredBlockheightExceededError if the transaction is  // dropped before confirmation — surface this to the user instead of hanging.  await connection.confirmTransaction(    { signature: sig, blockhash, lastValidBlockHeight },    'confirmed',  )  return sig}

case 'RAMPS_CHECK_BALANCE': {  const [usdcBalance, solLamports] = await Promise.all([    getUsdcBalance(walletAddress, connection),           // your existing helper    connection.getBalance(new PublicKey(walletAddress)),  ])  // ~0.003 SOL covers ATA creation + priority fees with headroom  const SOL_FEE_BUFFER = 0.003 * 1e9   // lamports  const hasSolForFees  = solLamports >= SOL_FEE_BUFFER   post('RAMPS_BALANCE_RESULT', {    walletAddress,    balance:    usdcBalance,    asset:      'USDC',    sufficient: usdcBalance >= ((payload?.amount as number) ?? 0) && hasSolForFees,  })  // If !hasSolForFees, show a warning in your UI before the user starts the flow  break}

import { useEffect, useRef, useState } from 'react'import {  View, ActivityIndicator, StyleSheet, Text, TouchableOpacity, Linking,} from 'react-native'import AsyncStorage from '@react-native-async-storage/async-storage'import { WebView, type WebViewMessageEvent } from 'react-native-webview' interface Props {  walletAddress:           string  balance:                 number   // USDC balance  onClose:                 () => void  onTransactionSaved?:     (record: MgiRecord) => void  /** 'off-ramp' (default) or 'on-ramp' — sets widget URL mode and RAMPS_CONFIG transaction type */  rampMode?:               'off-ramp' | 'on-ramp'  // Optional pre-fill  sendAmount?:             number   // Amount to pre-fill  destinationCountry?:     string   // ISO 3166-1 alpha-3 — cash-out only; skips country picker  destinationSubdivision?: string   // ISO 3166-2 e.g. US-CO  customer?:               CustomerProfile  // View mode — show status of an existing transaction  viewTransactionId?:      string} // Set via your environment config — Expo: process.env.EXPO_PUBLIC_SESSION_URL// Bare RN: a constants file or react-native-config.const SESSION_URL = process.env.EXPO_PUBLIC_SESSION_URL ?? 'https://yourapi.com/api/moneygram-session' async function fetchSession(walletAddress: string): Promise<Session> {  const res = await fetch(SESSION_URL, {    method:  'POST',    headers: { 'Content-Type': 'application/json' },    body:    JSON.stringify({ walletAddress }),  })  if (!res.ok) throw new Error(`Session creation failed: ${res.status}`)  return res.json()} // Only forward non-empty values — never send empty strings to the widgetfunction buildCustomer(p: CustomerProfile): Record<string, string> {  const c: Record<string, string> = {}  const add = (k: string, v?: string) => { if (v?.trim()) c[k] = v.trim() }  add('firstName',                p.firstName)  add('middleName',               p.middleName)  add('lastName',                 p.lastName)  add('secondLastName',           p.secondLastName)  add('dateOfBirth',              p.dateOfBirth)  add('email',                    p.email)  add('phone',                    p.phone)  add('phoneCountryDialCode',     p.phoneCountryDialCode)  add('addressLine1',             p.addressLine1)  add('city',                     p.city)  add('postalCode',               p.postalCode)  add('countryCode',              p.countryCode ?? (p.addressLine1 ? 'USA' : undefined))  add('countrySubdivisionCode',   p.countrySubdivisionCode)  add('birthCountryCode',         p.birthCountryCode)  add('citizenshipCountryCode',   p.citizenshipCountryCode)  add('idType',                   p.idType)  add('idNumber',                 p.idNumber)  add('idIssueCountry',           p.idIssueCountry)  add('idCountrySubdivisionCode', p.idCountrySubdivisionCode)  return c} // The MoneyGram widget domain — used to validate inbound postMessage events.const WIDGET_ORIGIN = 'https://playground.xramps.moneygram.com'  // update for production export function MoneyGramWidget({  walletAddress, balance, onClose, onTransactionSaved,  rampMode = 'off-ramp',  sendAmount, destinationCountry, destinationSubdivision,  customer, viewTransactionId,}: Props) {  // Source your wallet and connection from your Solana wallet adapter.  // If using @solana/wallet-adapter-react, call these hooks here:  //   const { publicKey, sendTransaction } = useWallet()  //   const { connection } = useConnection()  // Or pass them as props if your wallet state lives higher in the tree.  const wallet     = /* your wallet adapter */ undefined as any  const connection = /* your Connection    */ undefined as any   const webViewRef       = useRef<WebView>(null)  const sessionRef       = useRef<Session | null>(null)  const pendingAmountRef = useRef<string>('')  const isViewMode       = Boolean(viewTransactionId)   const [widgetUrl, setWidgetUrl] = useState<string | null>(null)  const [loading,   setLoading]   = useState(true)  const [error,     setError]     = useState<string | null>(null)  const [signing,   setSigning]   = useState(false)   // ── 1. Create session and build widget URL ──────────────────────────────────  useEffect(() => {    fetchSession(walletAddress)      .then((session) => {        sessionRef.current = session        const url = new URL(session.widgetUrl)        url.searchParams.set('mode', rampMode)        url.searchParams.set('_t', String(Date.now()))   // cache-bust        if (isViewMode && viewTransactionId) {          url.searchParams.set('transactionId', viewTransactionId)        }        setWidgetUrl(url.toString())      })      .catch((err) => {        setError(err.message)        setLoading(false)      })  }, [walletAddress, isViewMode, viewTransactionId])   // ── 2. Send a message INTO the WebView ─────────────────────────────────────  // Use injectJavaScript to dispatch a MessageEvent into the page.  // Payload is Base64-encoded before interpolation to avoid JS injection if the  // payload contains characters that could break the surrounding script context.  // The injected script MUST end with `true;` or it will be silently ignored.  function post(type: string, payload?: Record<string, unknown>) {    const json    = JSON.stringify(payload ? { type, payload } : { type })    const encoded = btoa(unescape(encodeURIComponent(json)))    webViewRef.current?.injectJavaScript(`      (function() {        var data = JSON.parse(decodeURIComponent(escape(atob('${encoded}'))));        window.dispatchEvent(new MessageEvent('message', {          data:   data,          origin: window.location.origin,        }));      })();      true;    `)  }   // ── 3. Receive messages FROM the WebView ────────────────────────────────────  // Validate the source URL before processing any message. In a React Native  // WebView the nativeEvent.url is always the URL of the loaded page — check it  // matches the MoneyGram widget domain to reject spoofed messages.  async function handleMessage(event: WebViewMessageEvent) {    const sourceUrl = event.nativeEvent.url ?? ''    if (!sourceUrl.startsWith(WIDGET_ORIGIN)) return     let parsed: { type?: string; payload?: Record<string, unknown> }    try { parsed = JSON.parse(event.nativeEvent.data) } catch { return }    const { type, payload } = parsed     switch (type) {       // ── A. Widget ready — send full config ────────────────────────────────      case 'RAMPS_READY': {        const session = sessionRef.current        if (!session) break         const builtCustomer = customer ? buildCustomer(customer) : undefined         post('RAMPS_CONFIG', {          sessionToken: session.sessionToken,           wallet: {            address:    walletAddress,            chain:      'solana',            asset:      'USDC',            walletType: 'non-custodial',          },           devConfig: {            mockMode:   false,   // always false — true bypasses real API flows            apiBaseUrl: process.env.EXPO_PUBLIC_RAMPS_API_URL ?? 'https://playground.xramps.moneygram.com/api',          },           theme: 'dark',           // Optional: pre-fill KYC — widget skips the form for filled fields          ...(builtCustomer && Object.keys(builtCustomer).length > 0            ? { customer: builtCustomer }            : {}),           // Optional: pre-fill amount + destination          // amount alone stores the value; amount + destinationCountry skips the country picker          ...(!isViewMode && sendAmount && sendAmount > 0            ? {                transaction: {                  type:   rampMode,                  asset:  'USDC',                  amount: sendAmount,                  ...(rampMode === 'off-ramp' && destinationCountry    ? { destinationCountry }    : {}),                  ...(rampMode === 'off-ramp' && destinationSubdivision ? { destinationSubdivision } : {}),                },              }            : !isViewMode && rampMode === 'on-ramp'            ? { transaction: { type: 'on-ramp', asset: 'USDC' } }            : {}),           // View mode: show status of an existing transaction          ...(isViewMode && viewTransactionId            ? { mode: 'view', transactionId: viewTransactionId }            : {}),        })        break      }       // ── B. Widget asks for USDC balance ───────────────────────────────────      // Note: this only checks USDC. If the user has no SOL for fees,      // sendTransaction will fail after KYC. See the "SOL transaction fees"      // section above for how to guard against this.      case 'RAMPS_CHECK_BALANCE':        post('RAMPS_BALANCE_RESULT', {          walletAddress,          balance,          asset:      'USDC',          sufficient: balance >= ((payload?.amount as number) ?? 0),        })        break       // ── C. Sign and broadcast the on-chain transfer ───────────────────────      // Payload: { chain, to, amount, asset }      // `chain` and `asset` are always present — use them if your app supports      // multiple chains or assets. For Solana/USDC-only integrations they will      // always be 'solana' and 'USDC' respectively.      case 'RAMPS_SIGN_TRANSACTION': {        const to     = payload?.to as string        const amount = payload?.amount as string        const chain  = payload?.chain as string   // 'solana'        const asset  = payload?.asset as string   // 'USDC'        if (!to || !amount) {          post('RAMPS_SIGN_ERROR', { error: 'Missing transaction parameters' })          break        }         // Capture the amount — RAMPS_TRANSACTION_COMPLETE doesn't always include it        pendingAmountRef.current = amount         // Sandbox-only: detect placeholder deposit address when the Solana wallet        // isn't yet provisioned for your agent ID. Gate strictly on __DEV__ so this        // code path cannot reach production — do not rely on manual removal.        if (__DEV__) {          const isPlaceholder = to.toLowerCase().includes('stub') || to.length < 32          if (isPlaceholder) {            console.warn('[MoneyGram] Sandbox placeholder address — bypassing signing')            post('RAMPS_SIGN_SUCCESS', { txHash: 'SANDBOX_' + Date.now(), walletAddress })            break          }        }         setSigning(true)        try {          const txHash = await sendUsdc(wallet, connection, to, amount)          post('RAMPS_SIGN_SUCCESS', { txHash, walletAddress })        } catch (err) {          post('RAMPS_SIGN_ERROR', { error: (err as Error).message })        } finally {          setSigning(false)        }        break      }       // ── D. Transaction complete — persist the record ──────────────────────      // Payload fields: { id, type, status, chain, asset, walletAddress,      //   amount, destinationCountry, destinationCurrency,      //   referenceNumber, createdAt, updatedAt }      case 'RAMPS_TRANSACTION_COMPLETE': {        const p = (payload ?? {}) as Record<string, unknown>        const record: MgiRecord = {          id:              String(p.id ?? `mg-${Date.now()}`),          referenceNumber: String(p.referenceNumber ?? ''),          amount:          pendingAmountRef.current || '0',          asset:           'USDC',          status:          (p.status as TransactionStatus) ?? 'completed',          createdAt:       Date.now(),        }        // Persist immediately — referenceNumber is what the recipient shows at the agent location        const key = `mgi_tx_${record.id}_${record.createdAt}`        await AsyncStorage.setItem(key, JSON.stringify(record))  // or SQLite / MMKV        onTransactionSaved?.(record)        // Do NOT close — let the widget show its own completion screen        // Widget fires RAMPS_CLOSE when the user dismisses it        break      }       // Widget fires RAMPS_SIGN_ERROR independently on its own timeout/failure.      // Reset the signing overlay so the user is not permanently blocked.      case 'RAMPS_SIGN_ERROR':        setSigning(false)        break       case 'RAMPS_CLOSE':        onClose()        break       // Open external URLs (T&Cs, KYC docs) in the device browser.      // Restrict to https:// — reject javascript:, file:, intent:// etc.      case 'RAMPS_OPEN_URL': {        const url = String(payload?.url ?? '')        if (url.startsWith('https://')) Linking.openURL(url)        break      }    }  }   if (error) {    return (      <View style={styles.overlay}>        <Text style={styles.errorText}>Unable to load MoneyGram</Text>        <Text style={styles.errorDetail}>{error}</Text>        <TouchableOpacity onPress={onClose} style={styles.button}>          <Text style={styles.buttonText}>Go back</Text>        </TouchableOpacity>      </View>    )  }   return (    <View style={StyleSheet.absoluteFillObject}>      {widgetUrl && (        <WebView          ref={webViewRef}          source={{ uri: widgetUrl }}          style={{ flex: 1 }}          onMessage={handleMessage}          onLoadEnd={() => setLoading(false)}          javaScriptEnabled          domStorageEnabled          cacheEnabled={false}          allowsInlineMediaPlayback          mediaPlaybackRequiresUserAction={false}        />      )}       {loading && (        <View style={[StyleSheet.absoluteFillObject, styles.overlay]}>          <ActivityIndicator size="large" color="#c9a84c" />          <Text style={styles.loadingText}>Loading MoneyGram…</Text>        </View>      )}       {signing && (        <View style={[StyleSheet.absoluteFillObject, styles.overlay]}>          <ActivityIndicator size="large" color="#c9a84c" />          <Text style={styles.loadingText}>Signing transaction…</Text>        </View>      )}    </View>  )} const styles = StyleSheet.create({  overlay:     { flex: 1, alignItems: 'center', justifyContent: 'center', backgroundColor: '#0d1220' },  loadingText: { color: '#9ca3af', marginTop: 12, fontSize: 14 },  errorText:   { color: '#fff', fontSize: 16, fontWeight: '600', marginBottom: 8, textAlign: 'center' },  errorDetail: { color: '#9ca3af', fontSize: 13, textAlign: 'center', marginBottom: 20, paddingHorizontal: 24 },  button:      { paddingHorizontal: 24, paddingVertical: 12, backgroundColor: '#1e293b', borderRadius: 12 },  buttonText:  { color: '#fff', fontSize: 14, fontWeight: '600' },})

// New cash-out — no pre-fill<MoneyGramWidget  walletAddress={solanaAddress}  balance={usdcBalance}  rampMode="off-ramp"  onClose={() => setOpen(false)}  onTransactionSaved={(record) => saveToStorage(record)}/> // New cash-in — user picks a MoneyGram location in the widget<MoneyGramWidget  walletAddress={solanaAddress}  balance={usdcBalance}  rampMode="on-ramp"  sendAmount={100}  onClose={() => setOpen(false)}  onTransactionSaved={(record) => saveToStorage(record)}/> // New cash-out with full pre-fill (skips country picker and KYC form)<MoneyGramWidget  walletAddress={solanaAddress}  balance={usdcBalance}  rampMode="off-ramp"  sendAmount={50}  destinationCountry="USA"  destinationSubdivision="US-CO"  customer={{    firstName: 'Jane', lastName: 'Doe',    dateOfBirth: '1990-01-15', phone: '2145550100', phoneCountryDialCode: '+1',    addressLine1: '123 Main St', city: 'Dallas', postalCode: '75201',    countryCode: 'USA', countrySubdivisionCode: 'US-TX',    idType: 'DRV', idNumber: 'TX12345678', idIssueCountry: 'USA',    idCountrySubdivisionCode: 'US-TX',  }}  onClose={() => setOpen(false)}  onTransactionSaved={(record) => saveToStorage(record)}/> // View mode — show status of a stored transaction<MoneyGramWidget  walletAddress={solanaAddress}  balance={usdcBalance}  viewTransactionId={storedRecord.id}  onClose={() => setViewId(null)}/>

// AsyncStorage exampleconst key = `mgi_tx_${record.id}_${record.createdAt}`await AsyncStorage.setItem(key, JSON.stringify(record)) // Or SQLite / MMKV for better query support

import { FlatList, Modal, TouchableOpacity, Text } from 'react-native' function HistoryList() {  const [records, setRecords] = useState<MgiRecord[]>([])  const [viewId,  setViewId]  = useState<string | null>(null)   useEffect(() => {    loadAllRecords().then(setRecords)  }, [])   return (    <>      <FlatList        data={records.sort((a, b) => b.createdAt - a.createdAt)}        keyExtractor={(r) => `${r.id}-${r.createdAt}`}        renderItem={({ item: r }) => (          <TouchableOpacity onPress={() => setViewId(r.id)}>            <Text>{r.amount} USDC → Cash Pickup</Text>            <Text>Ref: {r.referenceNumber}</Text>            <Text>View status →</Text>          </TouchableOpacity>        )}      />       {viewId && (        <Modal visible animationType="slide">          <MoneyGramWidget            viewTransactionId={viewId}            walletAddress={solanaAddress}            balance={usdcBalance}            onClose={() => setViewId(null)}          />        </Modal>      )}    </>  )}

<WebView  ref={webViewRef}  source={{ uri: widgetUrl }}  style={{ flex: 1 }}  onMessage={handleMessage}  onLoadEnd={() => setLoading(false)}  javaScriptEnabled             // required — widget relies on JS  domStorageEnabled             // required — widget uses sessionStorage  cacheEnabled={false}          // important — prevents stale widget JS after deploys  allowsInlineMediaPlayback     // required for embedded media content  mediaPlaybackRequiresUserAction={false}/>

<!-- AndroidManifest.xml --><uses-permission android:name="android.permission.INTERNET" /> <!-- Inside <application> — set to false in production --><application android:usesCleartextTraffic="false" ...>

<application android:usesCleartextTraffic="true" ...>