Web · Custodial cash-out · Solana / USDC

async function createCustodialSession(req, res) {  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_...  if (!secretKey) return res.status(500).json({ error: 'Secret key not configured' })   // Authenticated user from your auth layer, NOT from the client body alone  const customerIdentifier = req.user.id  // e.g. UUID, stable internal ID   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({      customerIdentifier,      walletAddress: process.env.PARTNER_OMNIBUS_WALLET,  // your custodianCashOutWallet      chain: 'solana',      // Optional: correlate this flow with your own transaction reference      // walletTransactionId: '550e8400-e29b-41d4-a716-446655440000',    }),  })   const data = await mgiRes.json()  if (!mgiRes.ok) return res.status(mgiRes.status).json(data)   return res.status(200).json({    sessionToken: data.sessionToken,    sessionId:    data.sessionId,    walletType:   data.walletType,   // 'custodial'    widgetUrl:    data.widgetUrl,     // includes ?mode=off-ramp, do not hardcode  })}

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

const { sessionToken, walletType, widgetUrl } = await fetch('/api/ramps-session', {  method: 'POST',}).then((r) => r.json()) const PARTNER_OMNIBUS_WALLET = 'YourSolanaHotWalletAddress...' const ramps = createRamps({  container: document.getElementById('ramps-widget'),  sessionToken,  widgetUrl,   wallet: {    address: PARTNER_OMNIBUS_WALLET,    chain: 'solana',    asset: 'USDC',    walletType,  // 'custodial' from session, do not hardcode unless testing  },   transaction: {    type: 'off-ramp',    destinationCountry: 'MEX',  // optional pre-fill  },   // Custodial: partner backend moves funds when deposit address is ready.  // Treat the browser payload as informational only. Your backend resolves  // the active Ramps transaction for this customer and re-reads the  // destination, asset, chain, and amount from the Ramps API (Step 5)  // before moving any funds.  onDepositAddress: async () => {    const res = await fetch('/api/internal-transfer', { method: 'POST' })    if (!res.ok) throw new Error('Transfer failed')    const { txHash } = await res.json()    return txHash  // required: widget polls using this hash  },   onComplete: (tx) => {    console.log('Cash-out complete', tx.referenceNumber)  },   onError: (err) => {    console.error('Ramps error', err.reason)  },}) ramps.open()

interface DepositAddress {  address: string       // MoneyGram deposit address (transfer USDC here)  memo?: string         // Memo if required by the deposit instruction  chain: 'solana'  asset: 'USDC'  amount?: string       // Optional: amount to transfer (stringified)}

onDepositAddress: async () => {  // All verification, balance checks, and fund movement happen server-side  const txHash = await callInternalTransferApi()  // POST /api/internal-transfer  return txHash  // SDK sends RAMPS_SIGN_SUCCESS to the widget with this hash}

GET /v1/transactions/:id/statusx-api-key: ramps_sk_...

// POST /api/internal-transferapp.post('/api/internal-transfer', async (req, res) => {  const userId = req.user.id  // from your auth middleware; nothing read from req.body   // 1. Resolve the customer's active cash-out transaction. For example, store  //    the Ramps transactionId against the user when the widget session starts,  //    or look up the pending transfer you recorded for this customer.  const transactionId = await getActiveRampsTransactionId(userId)  if (!transactionId) {    return res.status(404).json({ error: 'No active cash-out transaction' })  }   // 2. Idempotency: one durable transfer record per Ramps transaction id.  //    On retry, return the stored result instead of paying out twice.  const existing = await findTransferByRampsTransactionId(transactionId)  if (existing) {    return res.json({ txHash: existing.txHash })  }   // 3. Verify the transfer against the Ramps API (server API key, not browser input)  const tx = await fetch(`${RAMPS_API}/v1/transactions/${transactionId}/status`, {    headers: { 'x-api-key': process.env.MONEYGRAM_SK },  }).then((r) => r.json())   if (tx.status !== 'awaiting_funds' || tx.asset !== 'USDC' || !tx.depositAddress) {    return res.status(409).json({ error: 'Transaction is not awaiting funds' })  }   // 4. Validate the amount before touching any balance: it must exist and be  //    a positive USDC decimal string.  const amount = tx.sendAmount  if (typeof amount !== 'string' || !/^\d+(\.\d{1,6})?$/.test(amount) || parseFloat(amount) <= 0) {    return res.status(422).json({ error: 'Invalid transaction amount' })  }   // 5. Atomically reserve the funds: a single conditional ledger operation  //    that debits only if the balance is sufficient (for example, a  //    conditional UPDATE or a ledger hold). Never check-then-debit in two steps.  const reservation = await reserveCustomerUsdc(userId, amount, transactionId)  if (!reservation.ok) {    return res.status(400).json({ error: 'Insufficient balance' })  }   // 6. Send from the hot wallet; reverse the reservation on failure.  try {    const txHash = await hotWallet.sendUsdc({      to: tx.depositAddress,      memo: tx.depositMemo ?? undefined,      amount,      // Use mainnet or devnet mint per your sandbox/production environment    })    await recordTransfer({ transactionId, userId, amount, txHash })  // completes the idempotency record    return res.json({ txHash })  } catch (err) {    await releaseCustomerUsdc(reservation.id)  // compensate: give the funds back    return res.status(502).json({ error: 'On-chain transfer failed' })  }})

Your backend          Your frontend           Ramps widget / SDK        Ramps API           MGI     │                      │                         │                    │                │     │ POST /v1/sessions    │                         │                    │                │     │ (sk, customerId)     │                         │                    │                │     │◀─ sessionToken ──────│                         │                    │                │     │                      │ createRamps(custodial)  │                    │                │     │                      │────────────────────────▶│                    │                │     │                      │                         │ quote, KYC, commit │                │     │                      │                         │───────────────────▶│───────────────▶│     │                      │◀── onDepositAddress ────│◀─ deposit address ─│◀───────────────│     │◀─ POST /internal-transfer                      │                    │                │     │ hot wallet ─ USDC ──────────────────────────────────────────────────────────────────▶│     │── txHash ───────────▶│ (callback return)       │                    │                │     │                      │                         │ poll check-deposit │                │     │                      │◀── onComplete + ref# ───│◀───────────────────│                │