Skip to main content

Getting Started as a Merchant 👨‍💼

This guide walks you through the complete process of becoming a DolphinPay merchant and accepting cryptocurrency payments.

What is a DolphinPay Merchant?​

A DolphinPay merchant is any business or individual who wants to accept cryptocurrency payments through the DolphinPay network. As a merchant, you get:

  • Multi-Currency Support: Accept payments in any Sui ecosystem token
  • Custom Fee Structure: Set your own merchant fees (0-10%)
  • Payment Analytics: Track payments, volume, and performance
  • Secure Operations: Full control over your merchant settings
  • Easy Integration: Simple SDK integration for your applications

Prerequisites​

Before registering as a merchant, ensure you have:

  • ✅ Sui Wallet with testnet access
  • ✅ Testnet SUI tokens (get from faucet)
  • ✅ Basic understanding of blockchain transactions
  • ✅ Development environment (for SDK integration)

Step 1: Register Your Merchant Account​

Using the Frontend​

  1. Connect Your Wallet

    • Visit the DolphinPay frontend: [Coming Soon]
    • Click "Connect Wallet" and select your Sui wallet
    • Ensure you're connected to testnet

  2. Navigate to Merchant Registration

    • Go to "Merchant" → "Register"
    • Fill out the registration form

  3. Complete Registration

    // The frontend will build and execute this transaction:
    const txb = client.merchant.buildRegisterMerchant({
      name: "Your Business Name",
      description: "Description of your business",
      feeConfig: {
        customFeeBps: 50, // 0.5% merchant fee
        minFee: "1000000", // 0.001 SUI minimum
        maxFee: "1000000000", // 1 SUI maximum
      },
    })

  4. Confirm Transaction

    • Review the transaction in your wallet
    • Confirm and pay the gas fee (~0.015 SUI)
    • Wait for confirmation

Using SDK Directly​

import { createClient } from "@dolphinpay/sdk"

const client = createClient({
  packageId:
    "0x9c7ca262d020b005e0e6b6a5d083b329d58716e0d80c07b46804324074468f9c",
  network: "testnet",
})

// Build registration transaction
const txb = client.merchant.buildRegisterMerchant({
  name: "My Awesome Store",
  description: "Online store selling digital products",
  feeConfig: {
    customFeeBps: 100, // 1% merchant fee
    minFee: "1000000", // 0.001 SUI minimum
    maxFee: "1000000000", // 1 SUI maximum
  },
})

// Execute transaction
const result = await wallet.signAndExecuteTransactionBlock({
  transactionBlock: txb,
})

console.log("Merchant registered:", result.digest)

Step 2: Configure Your Merchant Settings​

Set Up Fee Structure​

Your merchant fee is charged in addition to the platform fee (0.3%). Total fee = Platform Fee + Merchant Fee.

// Update your fee configuration
const txb = client.merchant.buildConfigureMerchantFees({
  merchantObjectId: "0xyour_merchant_object_id",
  merchantCapId: "0xyour_merchant_cap_id",
  customFeeBps: 200, // 2% merchant fee
  minFee: "1000000", // 0.001 SUI minimum
  maxFee: "1000000000", // 1 SUI maximum
})

Fee Calculation Example:

  • Payment Amount: 10 SUI
  • Platform Fee: 0.3% = 0.03 SUI
  • Merchant Fee: 2% = 0.2 SUI
  • Total Fees: 0.23 SUI
  • You Receive: 9.77 SUI

Add Currency Support​

Configure which currencies you want to accept:

// Add SUI support
const txb1 = client.merchant.buildAddSupportedCurrency({
  merchantObjectId: "0xmerchant_id",
  merchantCapId: "0xmerchant_cap_id",
  currencyType: "0x2::sui::SUI",
  receivingAddress: "0xyour_sui_wallet_address",
})

// Add USDC support (when available)
const txb2 = client.merchant.buildAddSupportedCurrency({
  merchantObjectId: "0xmerchant_id",
  merchantCapId: "0xmerchant_cap_id",
  currencyType:
    "0x5d4b302506645c37ff133b98c4b50a5ae14841659738d6d733d59d0d217a93bf::coin::COIN",
  receivingAddress: "0xyour_usdc_wallet_address",
})

Set Receiving Addresses​

Each currency needs its own receiving address:

// Update SUI receiving address
const txb = client.merchant.buildSetReceivingAddress({
  merchantObjectId: "0xmerchant_id",
  merchantCapId: "0xmerchant_cap_id",
  currencyType: "0x2::sui::SUI",
  address: "0xyour_new_sui_address",
})

Step 3: Create Your First Payment​

Using SDK​

import { suiToMist } from "@dolphinpay/sdk"

// Create a payment request
const txb = client.payment.buildCreatePayment({
  merchant: "0xyour_merchant_address",
  amount: suiToMist(10), // 10 SUI
  currency: "0x2::sui::SUI",
  description: "Premium subscription",
  metadata: {
    orderId: "ORDER-12345",
    customerId: "CUST-67890",
    productId: "PREMIUM-PLAN",
  },
  expirySeconds: 3600, // 1 hour
})

// Execute transaction
const result = await wallet.signAndExecuteTransactionBlock({
  transactionBlock: txb,
})

console.log("Payment created:", result.digest)

Using Frontend​

  1. Navigate to Create Payment

    • Go to "Payment" → "Create"
    • Connect your wallet if not already connected

  2. Fill Payment Details

    • Merchant: Your merchant address (auto-filled if connected)
    • Amount: Payment amount in SUI (0.0001 - 1000)
    • Description: What the payment is for
    • Expiry: How long the payment link is valid

  3. Review Fees

    • Platform fee: 0.3%
    • Your merchant fee: As configured
    • Total fees and net amount

  4. Create Payment

    • Click "Create Payment"
    • Confirm transaction in wallet
    • Get payment object ID

Step 4: Process Customer Payments​

Customer Payment Flow​

// Customer executes payment (using your payment object)
const txb = client.payment.buildExecutePayment(
  {
    paymentId: "0xcustomer_payment_object_id",
    coinObjectId: "0xcustomer_coin_object_id",
  },
  "0x2::sui::SUI"
)

// Customer signs and executes
const result = await customerWallet.signAndExecuteTransactionBlock({
  transactionBlock: txb,
})

Automatic Fee Distribution​

When a payment is executed:

  1. Platform Fee (0.3%) → Platform treasury
  2. Merchant Fee (your %) → Your configured receiving address
  3. Net Amount → Your configured receiving address

Payment Events​

You'll receive events for all payment activities:

// Listen for payment events
const events = await client.provider.subscribeEvent({
  filter: {
    MoveEventType: `${packageId}::events::PaymentCompleted`,
  },
  onMessage: (event) => {
    const { merchant, amount, netAmount, platformFee, merchantFee } =
      event.parsedJson
    console.log(`Payment received: ${amount} SUI, Net: ${netAmount} SUI`)
  },
})

Step 5: Monitor Your Business​

Payment Analytics​

// Get merchant payments (requires event indexing)
const payments = await client.payment.queryPayments({
  merchant: "0xyour_merchant_address",
  fromDate: Date.now() - 30 * 24 * 60 * 60 * 1000, // Last 30 days
  status: "completed",
})

console.log(`Total payments: ${payments.length}`)
console.log(
  `Total volume: ${payments.reduce((sum, p) => sum + p.amount, 0)} SUI`
)

Merchant Dashboard​

Access your merchant dashboard to view:

  • Payment History: All payments received
  • Volume Analytics: Daily, weekly, monthly volume
  • Fee Earnings: Platform and merchant fees earned
  • Customer Insights: Payment patterns and trends

Step 6: Integration Best Practices​

Secure Your MerchantCap​

Your MerchantCap object controls all merchant operations:

// ✅ Good: Store securely
const MERCHANT_CAP_ID = process.env.MERCHANT_CAP_ID

// ❌ Bad: Hardcode in client code
const MERCHANT_CAP_ID = "0x..." // Don't do this!

Handle Multiple Currencies​

const SUPPORTED_CURRENCIES = {
  SUI: "0x2::sui::SUI",
  USDC: "0xusdc_coin_type",
  USDT: "0xusdt_coin_type",
}

async function createMultiCurrencyPayment(amount, currency) {
  const currencyType = SUPPORTED_CURRENCIES[currency]
  if (!currencyType) {
    throw new Error(`Unsupported currency: ${currency}`)
  }

  return client.payment.buildCreatePayment({
    merchant: merchantAddress,
    amount: suiToMist(amount),
    currency: currencyType,
    description: `${currency} payment`,
    metadata: { currency },
    expirySeconds: 3600,
  })
}

Implement Webhooks​

Set up webhooks for real-time notifications:

// Configure webhook URL in merchant settings
const txb = client.merchant.buildUpdateMerchantSettings({
  merchantObjectId: "0xmerchant_id",
  merchantCapId: "0xmerchant_cap_id",
  settings: {
    webhookUrl: "https://your-api.com/webhooks/dolphinpay",
    autoSettlement: true,
    settlementThreshold: suiToMist(10),
  },
})

Security Considerations​

MerchantCap Security​

  • Never share your MerchantCap ID publicly
  • Store securely in environment variables or secure vault
  • Use separate caps for different environments (testnet/mainnet)
  • Monitor usage and revoke if compromised

Address Management​

  • Use dedicated addresses for different currencies
  • Regularly rotate receiving addresses for security
  • Monitor balances and transfer to cold storage regularly
  • Verify addresses before updating merchant configuration

Fee Structure​

  • Start conservative with merchant fees (0.5-1%)
  • Monitor impact on payment conversion rates
  • Adjust based on your business model and costs
  • Consider minimum fees to cover transaction costs

Testing Your Integration​

Testnet Testing​

  1. Use testnet SUI from faucet (free)
  2. Test all payment flows with small amounts
  3. Verify fee calculations are correct
  4. Test error scenarios (insufficient balance, expired payments)

Dry Run Testing​

// Test payment creation without executing
const dryResult = await client.payment.dryRunCreatePayment(
  {
    merchant: "0xyour_merchant_address",
    amount: suiToMist(1),
    currency: "0x2::sui::SUI",
    description: "Test payment",
    metadata: {},
    expirySeconds: 3600,
  },
  "0xcustomer_address"
)

if (dryResult.success) {
  console.log("Payment would succeed")
  console.log("Gas cost:", dryResult.effects.gasUsed)
} else {
  console.error("Payment would fail:", dryResult.error)
}

Go Live Checklist​

Before going live with real customers:

  • Mainnet Deployment: Deploy contracts to mainnet
  • Security Audit: Complete security review
  • Testing: Comprehensive testnet testing
  • Monitoring: Set up payment monitoring
  • Support: Customer support processes
  • Documentation: User guides and FAQs
  • Backup: Secure backup of merchant capabilities

Troubleshooting​

Common Issues​

"Unauthorized merchant operation"

  • Verify you have the correct MerchantCap
  • Ensure you're the owner of the merchant
  • Check if merchant is active (not deactivated)

"Currency not supported"

  • Add currency support using addSupportedCurrency
  • Set receiving address for the currency
  • Verify currency type string is correct

"Invalid receiving address"

  • Check address format (should start with 0x)
  • Verify address exists on the network
  • Ensure address is not the zero address

Get Help​

Next Steps​

Now that you're set up as a merchant, explore these resources:

Congratulations! 🎉 You're now ready to accept cryptocurrency payments with DolphinPay. Start building your Web3 payment integration today!