SuiOutKit

Universal payment gateway for merchants: accept fiat (bank transfer, OPay, cards) and crypto (Sui wallet, outPay). Funds are settled on Sui and paired with on‑chain receipts and Walrus-stored invoice metadata.

Layer	Path	Role
SDK	sdk/	Browser package (suioutkit) - checkout modal, session API, wallet flows
Backend	backend/	Express service - providers, FX, treasury checks, Walrus, on-chain PTBs
Contracts	contracts/suioutkit/	Move - treasury, settle_fiat, SuiOutKitReceipt

Features

• Fiat checkout - Flutterwave (NGN bank transfer, OPay) and Stripe (cards)
• Crypto checkout - Sui wallet and outPay via Mysten Payment Kit
• On-chain settlement - Operator treasury releases tokens; Payment Kit enforces nonce uniqueness
• Receipts - SuiOutKitReceipt on Sui + structured invoice blobs on Walrus
• Treasury gating - Charges blocked when the vault cannot cover the FX-derived settlement amount

How it works

Flow in short: merchant calls the SDK to create a session; the backend orchestrates the charge with a provider, records state in Redis, uploads receipts to Walrus, and finally executes an on-chain settlement PTB which mints a receipt and transfers funds to the merchant.

Helpers & key files

Quick links to common helpers and implementation entry points used by integrators and contributors:

• SDK - sdk/src/index.ts - package entry and SuiOutKit class - sdk/src/config/api.ts - API origin and path helpers - sdk/src/utils/http.ts - request helper (timeout, retries) - sdk/src/utils/format.ts - formatNgn, formatToken, toTokenUnits - sdk/src/hooks/usePaymentStatus.ts - SSE/react helper
• Backend - backend/src/index.ts - HTTP entry (Express app) - backend/src/routes/checkout.ts - session, charge, webhook handlers - backend/src/routes/payments.ts - SSE payment stream - backend/src/config/coins.ts - multi-token config loader - backend/src/services/sui.ts - on-chain interaction and settlement helpers - backend/src/services/walrus.ts - invoice upload helper - backend/src/services/redis.ts - session store and locks
• Contracts - contracts/suioutkit/sources/checkout.move - settlement logic - contracts/suioutkit/sources/treasury.move - treasury management

Use these files as the first stop when implementing or debugging flows; they map directly to the routes and helpers the SDK expects.

For step-by-step API and environment details, see the docs.

Quick start

Merchants (production)

npm install suioutkit

import { SuiOutKit } from "suioutkit";

const sdk = new SuiOutKit({ merchantAddress: "0xYOUR_MERCHANT_SUI_ADDRESS" });
const session = await sdk.initCheckout({ amount: 45000, currency: "NGN", coinType: "0x2::sui::SUI" });
sdk.openModal(session);

Hosted API: https://api.suioutkit.xyz (mode: "live" default) · routes: /v1/checkout/* · Hosted API

Contributors (local stack)

Prerequisites: Node 18+, Docker Compose, optional sui CLI for Move tests.

cp backend/.env.example backend/.env
# Fill provider keys, contract IDs, operator keys
docker compose up --build

SDK override: mode: "local" (localhost:5000, testnet) or mode: "test" (staging, testnet).

Demo

With the stack running, open demo/demo.html. Health: http://localhost:5000/health

An extended flow is in demo/demo-e2e.html.

Full SDK reference: sdk/README.md.

Repository layout

suioutkit/
├── backend/           # Express + TypeScript API
├── sdk/               # Browser SDK (npm: suioutkit)
├── contracts/suioutkit/  # Move package
├── demo/              # HTML integration examples
├── docs/              # Developer guide and docs index
└── .github/workflows/ # CI (build + Move tests)

Documentation

Document	Description
Documentation	All docs (single source in docs/)
Project website	Renders docs/ at /docs/* (cd website && npm run dev)
Hosted API	api.suioutkit.xyz, /v1 routes, deploy checklist
Developer Guide	Contributors: architecture, env vars, CI
SDK README	Merchant integration, API reference, custom UI

Source map (for contributors)

Topic	Location
HTTP entry	backend/src/index.ts
Checkout routes	backend/src/routes/checkout.ts
Sui settlement	backend/src/services/sui.ts
Move settlement	contracts/suioutkit/sources/checkout.move
SDK entry	sdk/src/index.ts
Checkout modal	sdk/src/components/modal.ts

Testing and CI

• TypeScript - npm run build in backend/ and sdk/ (no separate test suite by default).
• Move - sui move test in contracts/suioutkit/.
• CI - .github/workflows/ci.yml builds both packages and runs Move tests when sui is on the runner.

Security

High-level security guidance is summarized here; see the linked documents for full operator and reporting procedures:

• SECURITY.md - how to report vulnerabilities and the preferred private contact.
• docs/guides/security.md - production security practices and operator hardening checklist.

Contributing

1. Fork and branch from main.
2. Keep changes focused; run npm run build in affected packages.
3. Update docs when behavior or public API changes.
4. Open a PR with a clear description and green CI.

Authors

• @The3rdWebLabs
• @CYBWithFlourish

License

GPL-3.0