Web integration · 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://yourapp.com', 'http://localhost:3000']  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 client JS  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 by SDK    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"}

<script src="https://playground.xramps.moneygram.com/sdk/index.global.js"></script><script>  // SDK available as global  const { createRamps } = window.RampsSDK</script>

// Type definitions (copy these into your project)type SupportedChain = 'solana' | 'stellar'type SupportedAsset = 'USDC'type WalletType = 'custodial' | 'non-custodial' interface OnChainTransaction {  chain: SupportedChain  to: string  amount: string  asset: SupportedAsset  requiredNetwork?: 'mainnet' | 'testnet'  tokenAddress?: string  tokenDecimals?: number  memo?: string  rawTransaction: unknown} interface TransactionRecord {  id: string  type: 'off-ramp' | 'on-ramp'  status: string  chain: SupportedChain  asset: SupportedAsset  walletType: WalletType  walletAddress: string  amount: number  referenceNumber?: string  createdAt: string  updatedAt: string} // Import SDK from global (loaded via <script> tag)declare const RampsSDK: {  createRamps: (config: any) => any} const { createRamps } = RampsSDK // 1. Create container elementconst container = document.getElementById('ramps-widget-container') // 2. Fetch session from your backendconst session = await fetch('/api/moneygram-session', {  method: 'POST',  headers: { 'Content-Type': 'application/json' },  body: JSON.stringify({ walletAddress: userPublicKey }),}).then(res => res.json()) // 3. Initialize SDKconst ramps = createRamps({  container,  sessionToken: session.sessionToken,    // Wallet context  wallet: {    address: userPublicKey,       // Solana public key    chain: 'solana',    asset: 'USDC',    walletType: 'non-custodial',    displayName: 'Your Wallet'    // Optional - shown in widget header  },    // Transaction signing callback  onSignTransaction: async (tx: OnChainTransaction) => {    console.log('Sign transaction:', tx)    // Implement signing in Step 4    const signature = await signAndSendUsdc(tx)    return signature  },    // Lifecycle callbacks  onReady: () => {    console.log('Widget ready')  },    onComplete: (transaction: TransactionRecord) => {    console.log('Transaction complete:', transaction.referenceNumber)    alert(`Cash pickup code: ${transaction.referenceNumber}`)  },    onError: (error: { transactionId?: string; reason: string }) => {    console.error('Widget error:', error)    alert(`Error: ${error.reason}`)  },    onClose: () => {    console.log('Widget closed')  }}) // 4. Open the widgetramps.open() // Optional: close programmatically// ramps.close() // Optional: cleanup (removes iframe)// ramps.destroy()

const ramps = createRamps({  container,  sessionToken: session.sessionToken,    wallet: { /* ... */ },    // Customer pre-fill (all optional)  customer: {    firstName: 'John',    lastName: 'Smith',    email: '[email protected]',    phone: '2145550100',    phoneCountryDialCode: '+1',    dateOfBirth: '1990-01-15'  // YYYY-MM-DD  },    // Transaction pre-fill (all optional)  transaction: {    type: 'off-ramp',    destinationCountry: 'MEX',           // ISO 3166-1 alpha-3    destinationCurrency: 'MXN',          // ISO 4217    destinationSubdivision: 'MX-CMX',    // ISO 3166-2 (required for MEX, USA, CAN)    amount: 100,                         // Pre-fill amount    asset: 'USDC'  },    onSignTransaction: async (tx) => { /* ... */ }})

const session = await fetch('/api/moneygram-session', {  method: 'POST',  headers: { 'Content-Type': 'application/json' },  body: JSON.stringify({ walletAddress: userPublicKey }),}).then(res => res.json()) // Replace mode on the widget URL from the session response. Do not append a second mode.const widgetUrl = new URL(session.widgetUrl)widgetUrl.searchParams.set('mode', 'on-ramp') const ramps = createRamps({  container,  sessionToken: session.sessionToken,  widgetUrl: widgetUrl.toString(),  mode: 'on-ramp',   wallet: {    address: userPublicKey,    chain: 'solana',    asset: 'USDC',    walletType: 'non-custodial',  },   transaction: {    type: 'on-ramp',    amount: 100,   // optional pre-fill (fiat amount)    asset: 'USDC',  },   // onSignTransaction is not called for standard cash-in flows   onComplete: (transaction) => {    console.log('Cash-in complete:', transaction.referenceNumber, transaction.type)  },   onError: (error) => console.error(error),  onClose: () => console.log('Widget closed'),}) ramps.open()

const ramps = createRamps({  container,  sessionToken: session.sessionToken,    viewTransaction: {    id: 'tx_abc123'  // Transaction ID (transaction.id from onComplete), not the reference number  },    onClose: () => {    console.log('User closed transaction view')  }}) ramps.open()

# Option A: Solana Kit (recommended for new projects)npm install @solana/kit @solana-program/token@^0.9.0 # Option B: Web3.js v1 (stable, widely used)npm install @solana/web3.js @solana/spl-token

onSignTransaction: async (tx: OnChainTransaction) => {  // tx includes requiredNetwork, tokenAddress, tokenDecimals — derived from your API key.  const rpcUrl = tx.requiredNetwork === 'mainnet'    ? process.env.SOLANA_MAINNET_RPC!    : process.env.SOLANA_DEVNET_RPC!  const mint = new PublicKey(tx.tokenAddress!)    // Use your wallet's internal signing method  const signature = await yourWallet.signAndSendTransaction({    instructions: buildUsdcTransferInstructions(tx, mint),    feePayer: userPublicKey,    rpcUrl,  })    return signature // Return the transaction signature string}

import { address, createClient } from '@solana/kit'import { tokenProgram } from '@solana-program/token' // createClient() starts an empty client; .use(tokenProgram()) adds the// client.token namespace used below. Add your RPC plugin the same way// (see the Solana Kit docs for the current RPC plugin API), e.g.// createClient().use(solanaDevnetRpc).use(tokenProgram()).const client = createClient().use(tokenProgram()) async function signAndSendUsdc(tx: OnChainTransaction): Promise<string> {  // Always derive the mint and decimals from the transaction, never  // hardcode them. tx.tokenAddress/tokenDecimals reflect the network your  // API key resolves to (devnet in sandbox, mainnet in production).  if (!tx.tokenAddress || !tx.tokenDecimals) {    throw new Error('Missing tokenAddress/tokenDecimals on transaction')  }  const mint = address(tx.tokenAddress)  const decimals = tx.tokenDecimals   // Signer wraps your wallet's signing method  const signer = {    address: address(yourWallet.getPublicKey()),    signTransactions: async (transactions) => yourWallet.signTransactions(transactions),  }   const { context } = await client.token.instructions    .transferToATA({      mint,      authority: signer,      recipient: address(tx.to),      amount: toBaseUnits(tx.amount, decimals),      decimals,    })    .sendTransaction()   return context.signature} // Use in SDKconst ramps = createRamps({  // ...  onSignTransaction: signAndSendUsdc})

import { Connection, PublicKey, Transaction } from '@solana/web3.js'import {  getAssociatedTokenAddress,  createTransferInstruction,  TOKEN_PROGRAM_ID} from '@solana/spl-token' function toBaseUnits(amount: string, decimals: number): bigint {  const [whole, fraction = ''] = amount.split('.')  if (!/^\d+$/.test(whole) || (fraction && !/^\d+$/.test(fraction))) {    throw new Error('Amount must be a decimal string')  }  if (fraction.length > decimals) {    throw new Error(`Amount has more than ${decimals} decimal places`)  }  return BigInt(whole + fraction.padEnd(decimals, '0'))} async function signAndSendUsdc(tx: OnChainTransaction): Promise<string> {  // Get wallet from your wallet provider  const userPublicKey = yourWallet.getPublicKey() // Use your wallet's method    if (!userPublicKey) {    throw new Error('Wallet not connected')  }  if (!tx.tokenAddress || tx.tokenDecimals == null) {    throw new Error('Missing tokenAddress or tokenDecimals on the sign payload')  }  if (tx.requiredNetwork !== 'mainnet' && tx.requiredNetwork !== 'testnet') {    throw new Error('Sign payload is missing requiredNetwork')  }   const rpcUrl = tx.requiredNetwork === 'mainnet'    ? process.env.SOLANA_MAINNET_RPC!    : process.env.SOLANA_DEVNET_RPC!  const connection = new Connection(rpcUrl, 'confirmed')   // Parse transaction details from the payload. Do not hardcode a mint or use parseFloat.  const toPublicKey = new PublicKey(tx.to)  const amountBaseUnits = toBaseUnits(tx.amount, tx.tokenDecimals)  const mintAddress = new PublicKey(tx.tokenAddress)    // Get associated token accounts  const fromAta = await getAssociatedTokenAddress(    mintAddress,    userPublicKey,    false,    TOKEN_PROGRAM_ID  )    const toAta = await getAssociatedTokenAddress(    mintAddress,    toPublicKey,    false,    TOKEN_PROGRAM_ID  )    console.log('Transfer:', {    from: fromAta.toString(),    to: toAta.toString(),    amount: amountBaseUnits.toString()  })    // Create transfer instruction  const transferInstruction = createTransferInstruction(    fromAta,    toAta,    userPublicKey,    amountBaseUnits,    [],    TOKEN_PROGRAM_ID  )    // Build transaction  const transaction = new Transaction()  transaction.add(transferInstruction)    // Get recent blockhash  const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash()  transaction.recentBlockhash = blockhash  transaction.feePayer = userPublicKey    // Sign with your wallet  const signedTransaction = await yourWallet.signTransaction(transaction)    // Send transaction  const signature = await connection.sendRawTransaction(signedTransaction.serialize())    console.log('Transaction sent:', signature)    // Confirm transaction  await connection.confirmTransaction({    signature,    blockhash,    lastValidBlockHeight  })    console.log('Transaction confirmed:', signature)  return signature} // Use in SDKconst ramps = createRamps({  // ...  onSignTransaction: signAndSendUsdc})

onSignTransaction: async (tx) => {  try {    // Validate user has enough balance    const decimals = tx.tokenDecimals ?? 6    const required = toBaseUnits(tx.amount, decimals)    const balance = await checkUsdcBalanceBaseUnits(tx.tokenAddress!)    if (balance < required) {      throw new Error(`Insufficient USDC balance. Need ${tx.amount} USDC`)    }        // Sign and send    const signature = await signAndSendUsdc(tx)    return signature      } catch (error) {    console.error('Transaction failed:', error)        // User rejected signature    if (error.message?.includes('rejected')) {      throw new Error('Transaction cancelled by user')    }        // Network error    if (error.message?.includes('fetch')) {      throw new Error('Network error. Please try again.')    }        // Re-throw for widget to handle    throw error  }}

const USDC_MINT_MAINNET = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'const USDC_MINT_DEVNET = '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU' const usdcMint = process.env.NODE_ENV === 'production'   ? USDC_MINT_MAINNET   : USDC_MINT_DEVNET

// 1. Switch your wallet to devnet// (Implementation depends on your wallet) // 2. Get devnet SOL// Visit https://faucet.solana.com/ and enter your address // 3. Get devnet USDC// Visit https://faucet.circle.com/ and request USDC // 4. Verify balanceimport { Connection, PublicKey } from '@solana/web3.js' const connection = new Connection('https://api.devnet.solana.com')const mint = new PublicKey('4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU')const balance = await connection.getTokenAccountBalance(yourTokenAccount)console.log('USDC balance:', balance.value.uiAmount)