SDK Reference

SuiOutKit browser SDK API for merchants.

Install

npm install suioutkit

Drop-in checkout for your site - no backend to deploy. See Installation. The SDK defaults to mode: "live" (hosted API at https://api.suioutkit.xyz, mainnet when live). Currently operating on testnet - use mode: "test" for staging or mode: "local" for local development.

Constructor

const sdk = new SuiOutKit({
  merchantAddress: "0x...",                     // required
  // settlementToken: "USDC",                   // optional: single token or ["SUI","USDC"]
  // mode: "local",                             // localhost:5000, testnet
  // mode: "test",                              // staging, testnet
  // mode: "live",                              // production, mainnet (default)
});

Methods

`initCheckout(options)`

const session = await sdk.initCheckout({
  amount: 29.99,
  currency: "USD",
  coinType?: "0x2::sui::SUI",   // optional: override settlement coin
  settlementToken?: string | string[],  // optional: single token or ["SUI","USDC"]
  metadata?: { orderId: "ORDER-123" },
});

Returns CheckoutSession with token, nonce, coinType, supportedCoins (each entry includes symbol, type, decimals), settlementToken (a string or string[]), estimatedRate, resolvedCurrency, currencySymbol, etc.

`openModal(session, options?)`

Opens the built-in modal (bank transfer, OPay, USSD, Stripe, Sui wallet, outPay). Loads styles from {backendUrl}/style.css.

Payment methods shown in the modal depend on the customer’s currency: NGN customers see bank transfer, OPay, USSD, card, and crypto; GHS customers see bank transfer, card, and crypto; other customers see card and crypto. Cross-region NGN customers see a “Pay in NGN →” label for local payment rails.

const modal = sdk.openModal(session, {
  onClose: () => console.log("Modal closed"),
  onPaymentComplete: (result) => console.log("Paid", result.txDigest),
  redirectUrl: "/thank-you",
  autoCloseOnSuccess: true,
});

Options (SuiOutKitModalOptions):

Option	Type	Description
`onClose`	`() => void`	Fired when the user dismisses the overlay
`onPaymentComplete`	`(result: PaymentResult) => void`	Fired after on-chain settlement with `{ nonce, txDigest, walrusBlobId }`
`redirectUrl`	`string`	Redirect the browser here after successful payment
`autoCloseOnSuccess`	`boolean`	Auto-close the modal after settlement instead of showing success panel

`wrapButton(selector, options)`

Binds checkout to a DOM button by CSS selector.

sdk.wrapButton("#pay-btn", {
  amount: 29.99,
  currency: "USD",
  coinType: "0x2::sui::SUI",   // optional
  metadata: { orderId: "ORDER-123" },   // optional
});

wrapButton accepts amount, currency, coinType, and metadata - pass settlementToken to initCheckout or the SuiOutKit config instead.

`confirmCryptoPayment(nonce, txDigest, method?)`

Submit a wallet/outPay transaction digest after a custom crypto flow. Methods: "sui_wallet" | "outpay".

Helper exports

import {
  request,
  formatCurrency,
  toTokenUnits,
  formatToken,
  createPolling,
} from "suioutkit";

Export	Purpose
`request`	Fetch with timeout + JSON
`formatCurrency(amount, currency)`	Format any fiat amount with correct symbol (e.g. `formatCurrency(29.99, "USD")` → `$29.99`)
`toTokenUnits`	Base units → float
`formatToken`	Display token amounts
`createPolling`	`{ start(), stop() }` interval helper

Notes:

request is the SDK’s fetch helper (default export from utils/http).
The SDK also re-exports DEFAULT_API_ORIGIN and API_V1_PREFIX from its config for advanced integrations.

Custom UI

Without the modal:

initCheckout
POST /v1/checkout/charge with { token, method, phoneNumber? }
Poll GET /v1/checkout/status/:nonce

Crypto: POST /v1/checkout/crypto/intent → wallet PTB → confirmCryptoPayment.

Network

The SDK sets the Sui network automatically based on mode. No manual script tag is needed (like in previous versions).

Full npm readme

See sdk/README.md in the repository.