Skip to main content

Quick Start

Prepare a DolphinPay integration for Sui testnet in a few steps. The project package is live on Sui testnet; take its IDs from DEPLOYMENT.md, or publish your own package with the Testnet Deployment guide.

1. Prerequisites​

info

Payments are native Circle USDC only (6 decimals), enforced on-chain. SUI is used only for gas. The platform fee is 0 bps and merchants have no fees, so payers pay exactly the payment amount plus gas.

2. Get the deployment IDs​

The current testnet Package ID and shared AdminConfig ID are recorded in DEPLOYMENT.md at the repository root. That file is the single source of truth — do not use IDs from old docs or commits. The live deployment is already configured for native Circle USDC (allowed currency set on-chain) with a 0 bps platform fee. There is no mainnet deployment.

3. Use the SDK​

Install and build​

There is no stable npm registry release of @dolphinpay/sdk yet — build it from source:

git clone https://github.com/DolphinsLab/dolphin-pay.git
cd dolphin-pay/sdk
bun install
bun run build

Consumers add the built sdk/ directory as a local file dependency. In this repository, frontend/package.json does exactly that:

{
  "dependencies": {
    "@dolphinpay/sdk": "file:../sdk"
  }
}

Adjust the relative path to wherever your project sits relative to sdk/.

Create a payment​

import { createClient, usdcToUnits, USDC_TYPES } from '@dolphinpay/sdk';

// IDs from DEPLOYMENT.md
const client = createClient({
  network: 'testnet',
  packageId: '<PACKAGE_ID>',
  adminConfigId: '<ADMIN_CONFIG_ID>',
});

// '10' USDC (decimal string) → 6-decimal base-unit string
const txb = client.payment.buildCreatePayment({
  merchant: '0xMERCHANT_ADDRESS',
  amount: usdcToUnits('10'),
  currencyType: USDC_TYPES.testnet,
  description: 'Payment for order #123',
  expirySeconds: 3600, // 1 hour
});

// Sign and execute with the user's wallet (e.g. @mysten/dapp-kit)
await signAndExecuteTransaction({ transaction: txb });

The SDK builds transactions; your wallet signs and executes them. The created Payment is a shared object, so any payer can execute it.

Execute a payment (payer side)​

const txb = client.payment.buildExecutePayment(
  {
    paymentId: '0xPAYMENT_OBJECT_ID',
    coinObjectId: '0xUSDC_COIN_OBJECT_ID',
    amount: usdcToUnits('10'), // splits the exact amount from the coin
  },
  USDC_TYPES.testnet
);

await signAndExecuteTransaction({ transaction: txb });

The SDK uses Sui gRPC (SuiGrpcClient) exclusively — no JSON-RPC, no websockets.

4. Run the frontend​

cd frontend
bun install

Create frontend/.env.local with the IDs from DEPLOYMENT.md:

NEXT_PUBLIC_SUI_NETWORK=testnet
NEXT_PUBLIC_PACKAGE_ID=<PACKAGE_ID>
NEXT_PUBLIC_ADMIN_CONFIG_ID=<ADMIN_CONFIG_ID>
bun run dev       # http://localhost:3000
bun run build     # production build
bun run deploy    # OpenNext build + deploy to Cloudflare Workers

5. Test the flow​

  1. Connect wallet — connect your Sui wallet on testnet
  2. Register as merchant (optional) — via the merchant page, or pay to any address
  3. Create a payment — set the USDC amount, description, and expiry; share the checkout link (/pay/[paymentId])
  4. Execute the payment — the payer pays in USDC from their wallet
  5. Verify — check the transaction on SuiVision

Tips​

  • Dry-run first — Payment and Merchant builders have matching dryRun* methods (e.g. client.payment.dryRunCreatePayment(params, sender)); Admin transactions can be passed to client.dryRunTransaction(tx, sender)
  • Amounts are base units — always convert with usdcToUnits / unitsToUsdc; usdcToUnits takes a decimal string and returns a base-unit string — never use floating-point math on amounts
  • Payments expire — the default expiry is 3600 seconds; expired payments cannot be executed
  • No refunds — there are no on-chain refunds; cancel a pending payment with buildCancelPayment before it is executed

Troubleshooting​

Transaction failed

  • Ensure the payment coin is testnet USDC (USDC_TYPES.testnet) — any other coin type aborts on-chain
  • Check you hold enough USDC for the amount and enough SUI for gas
  • Verify the payment hasn't expired or been cancelled

Objects not found

  • Re-check the Package ID and AdminConfig ID against DEPLOYMENT.md; earlier packages are defunct

Wallet not connecting

  • Confirm the extension is installed and set to testnet, then refresh

What's next?​