Skip to main content

Your First Sub-Merchant Wallet

Create and manage sub-merchant wallets to handle payments for multiple businesses or users within your platform. This is essential for SaaS platforms and marketplaces.

Understanding Sub-Merchant Wallets​

Sub-merchant wallets allow you to:

  • Separate funds for different users or businesses
  • Manage individual balances and transactions
  • Enable independent payout capabilities
  • Maintain clear financial boundaries

Creating a Sub-Merchant Wallet​

curl -X POST "https://api.nextapi.com/v1/wallets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sub_merchant",
    "owner": {
      "name": "Jane Smith",
      "email": "jane@business.com",
      "phone": "+639123456789"
    },
    "business": {
      "name": "Jane's Store",
      "registration_number": "BN-123456",
      "industry": "retail"
    },
    "metadata": {
      "platform_user_id": "user_456",
      "signup_date": "2024-01-15"
    }
  }'

Response Example​

{
  "id": "wallet_sub_789",
  "type": "sub_merchant",
  "owner": {
    "name": "Jane Smith",
    "email": "jane@business.com"
  },
  "balance": {
    "available": 0,
    "pending": 0,
    "currency": "PHP"
  },
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Managing Wallet Balances​

Check wallet balance:

curl -X GET "https://api.nextapi.com/v1/wallets/wallet_sub_789/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Add funds to wallet:

curl -X POST "https://api.nextapi.com/v1/wallets/wallet_sub_789/credit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "PHP",
    "reference": "Initial funding"
  }'

Security Considerations​

  • Always validate sub-merchant identity before creating wallets
  • Implement proper access controls for wallet operations
  • Monitor wallet activities for suspicious transactions
  • Keep audit trails for all wallet operations

Next Steps​

  • [Build a SaaS platform with user wallets](../guides/how-to/build-a-saas-platform-with-user-wallets
  • [Understand wallet structure](../guides/core-concepts/understanding-your-wallet-structure
  • [Handle mass payouts](../guides/how-to/run-payroll-or-any-mass-payout