Sui payments

Accept native SUI and Sui coins (e.g. USDC) on devnet, testnet, and mainnet through hosted checkout, payment links, and the NodeRails SDK — with gas-sponsored one-time payments and subscription wallets.

Chain IDs

Sui uses NodeRails-specific numeric chain IDs (same pattern as Solana cluster IDs). Pass these in allowedChains on checkout sessions, payment links, invoices, and payment intents.

Merchant setup

1. In the merchant dashboard, enable Sui on your app (Settings → Chains).
2. Connect a Sui settlement wallet (Wallet Standard extension such as Sui Wallet or Slush).
3. Ensure SUI and/or USDC (or other enabled coins) are toggled for the Sui network you use.
4. Register Sui escrow object IDs in admin after publishing the Move package (platform ops).

SDK: Sui-only checkout session

Restrict checkout to Sui testnet and USDC + native SUI using allowedChains and allowedTokens:

import { NodeRails } from '@noderails/sdk';

const noderails = new NodeRails({
  appId: process.env.NODERAILS_APP_ID!,
  apiKey: process.env.NODERAILS_API_KEY!,
});

const session = await noderails.checkoutSessions.create({
  mode: 'PAYMENT',
  successUrl: 'https://yoursite.com/success?session={CHECKOUT_SESSION_ID}',
  cancelUrl: 'https://yoursite.com/cancel',
  allowedChains: [202],              // Sui testnet only
  allowedTokens: ['SUI-202', 'USDC-202'],
  items: [
    {
      name: 'Buy me a coffee',
      amount: '5.00',
      currency: 'USD',
      quantity: 1,
    },
  ],
  metadata: { orderId: 'order_123' },
});

// Redirect: https://pay.noderails.com/checkout/{session.id}

Customer checkout flow

1. Customer opens the hosted payment page.
2. Connects a Sui wallet (Wallet Standard).
3. For one-time payments, approves a gas-sponsored capture transaction (user signs; platform sponsors gas via MTXM).
4. For subscriptions, customer funds a NodeRails subscription wallet on Sui, then renewals are captured from that wallet.
5. NodeRails sends payment.captured to your webhook when escrow holds funds.

Webhooks

Sui payments use the same webhook events as EVM and Solana. Register your endpoint in the dashboard (Settings → Webhooks) and verify signatures with your signing secret (whsec_…).

app.post('/api/webhooks/noderails', express.raw({ type: 'application/json' }), (req, res) => {
  const event = NodeRails.webhooks.constructEvent(
    req.body,
    req.headers['x-noderails-signature'] as string,
    req.headers['x-noderails-timestamp'] as string,
    process.env.NODERAILS_WEBHOOK_SECRET!,
  );

  if (event.event === 'payment.captured') {
    const chainId = event.data.authorizationChainId; // 201 | 202 | 203 for Sui
    const tokenKey = event.data.authorizationTokenKey; // e.g. SUI-202
    const txRef = event.data.captureTxHash; // Sui transaction digest
    console.log('Sui payment captured', { chainId, tokenKey, txRef });
  }

  res.sendStatus(200);
});

Subscribe at minimum to payment.captured. Use Webhooks for the full event list and signature details.

Sponsored checkout API (payment-ui / custom integrators)

If you build a custom checkout UI (not hosted pay.noderails.com), the server exposes Sui sponsor endpoints used by payment-ui. These are called after authorize returns captureData with chainType: "SUI" and sponsored: true.

Subscriptions on Sui

Subscriptions on Sui use an on-chain subscription wallet per customer. The customer authorizes and funds the wallet once; renewals are captured from that wallet without a new wallet connection each cycle. Enable Sui on your app and create subscription checkout sessions or payment links with a product plan as usual.

Token keys and coin types

• Native SUI: token key SUI-202 (testnet), contract native in API responses.
• USDC on Sui: token key USDC-202; contractAddress is the full Move coin type (e.g. 0x2::sui::SUI or USDC type string from admin).

Related docs

• Quick Start
• SDK — Checkout Sessions
• SDK — Webhook Endpoints
• Supported Chains & Tokens