Users API

User Operations

The User service (client.user) allows you to access information about the user associated with your API key, including account details, bank accounts, and Shopify sessions.

Get User Information

Retrieve comprehensive information about your user account:

const user = await client.user.get();
console.log(`User ID: ${user.id}`);
console.log(`Balance: ${user.polar_balance_usdc} USDC`);
console.log(`KYC Complete: ${user.kyc_complete}`);

Response Type

interface User {
  id: string;
  sign_in_method: 'EMAIL' | 'SHOPIFY';
  email: string;
  shopify_shop: string | null;
  notification_email: string | null;
  business_name: string | null;
  customer_id: string | null;
  kyc_complete: boolean;
  kyc_link_id: string | null;
  polar_balance_usdc: number;
  shopifyConfigurationId: string | null;
  created_at: string;
  updated_at: string;
}

Response Fields

Field	Type	Description
id	string	Unique user identifier
sign_in_method	string	Authentication method used (EMAIL or SHOPIFY)
email	string	User's email address
shopify_shop	string|null	Shopify shop domain (if applicable)
notification_email	string|null	Email for notifications (if different from main email)
business_name	string|null	Business or company name
customer_id	string|null	Bridge customer ID for KYC/banking
kyc_complete	boolean	Whether KYC verification is completed
kyc_link_id	string|null	Bridge KYC link identifier
polar_balance_usdc	number	Current USDC balance in user's SuiPay account
shopifyConfigurationId	string|null	Associated Shopify configuration ID
created_at	string	Account creation timestamp
updated_at	string	Last account update timestamp

Usage Examples

// Basic user info
try {
  const user = await client.user.get();
  console.log(`Welcome ${user.email}!`);
  console.log(`Current balance: ${user.polar_balance_usdc} USDC`);
  
  if (user.kyc_complete) {
    console.log('✅ KYC verification complete');
  } else {
    console.log('⚠️  KYC verification required for bank withdrawals');
  }
} catch (error) {
  console.error('Failed to get user info:', error);
}

Security Note: This method returns sensitive information including the user's current USDC balance (polar_balance_usdc) and Bridge customer ID (customer_id). Ensure this data is handled securely and not exposed to unauthorized parties.

Get User Bank Accounts

Retrieve a list of bank accounts associated with your user account:

const bankAccounts = await client.user.getBankAccounts();
console.log(`Found ${bankAccounts.length} bank account(s)`);

bankAccounts.forEach(account => {
  console.log(`${account.bank_name || 'Bank'} (****${account.last_four})`);
  console.log(`Type: ${account.account_type}`);
});

Response Type

interface BankAccount {
  id: string;
  user_id: string;
  bridge_id: string;
  bank_name?: string;
  last_four: string;
  country_code: string;
  account_type: string;
  created_at: string;
  updated_at: string;
}

Bank Account Fields

Field	Type	Description
id	string	SuiPay bank account identifier
user_id	string	Associated user identifier
bridge_id	string	Bridge service account identifier
bank_name	string?	Name of the bank (optional)
last_four	string	Last 4 digits of account number
country_code	string	Country code for the account
account_type	string	Type of bank account (e.g., checking, savings)
created_at	string	Account connection timestamp
updated_at	string	Last account update timestamp

Usage Examples

// List bank accounts and check verification status
try {
  const bankAccounts = await client.user.getBankAccounts();
  
  if (bankAccounts.length === 0) {
    console.log('No bank accounts connected');
    console.log('Connect a bank account in your SuiPay dashboard to enable withdrawals');
  } else {
    console.log('Connected bank accounts:');
    bankAccounts.forEach((account, index) => {
      console.log(`${index + 1}. ${account.bank_name || 'Bank'}`);
      console.log(`   Type: ${account.account_type}`);
      console.log(`   Last 4: ****${account.last_four}`);
      console.log(`   Country: ${account.country_code}`);
    });
  }
} catch (error) {
  console.error('Failed to get bank accounts:', error);
}

// Find a specific bank account for withdrawals
const bankAccounts = await client.user.getBankAccounts();
const primaryAccount = bankAccounts.find(account => 
  account.account_type === 'checking'
);

if (primaryAccount) {
  console.log(`Using primary account: ${primaryAccount.bank_name || 'Bank'} (****${primaryAccount.last_four})`);
  // Use primaryAccount.id for withdrawal requests
} else {
  console.log('No checking account available');
}

Get User Shopify Sessions

Retrieve a list of Shopify sessions associated with your user account (only applicable for Shopify-integrated users):

const sessions = await client.user.getSessions();
console.log(`Found ${sessions.length} Shopify session(s)`);

sessions.forEach(session => {
  console.log(`Shop: ${session.shop}`);
  console.log(`User ID: ${session.userId || 'N/A'}`);
  console.log(`Online: ${session.isOnline ? 'Yes' : 'No'}`);
  console.log(`Created: ${new Date(session.createdAt).toLocaleDateString()}`);
});

Response Type

interface ShopifySession {
  id: string;
  shop: string;
  state: string;
  isOnline: boolean;
  scope?: string;
  expires?: string;
  accessToken: string;
  userId?: string;
  createdAt: string;
  updatedAt: string;
}

Shopify Session Fields

Field	Type	Description
id	string	Session identifier
shop	string	Shopify shop domain
state	string	OAuth state parameter
isOnline	boolean	Whether this is an online session
scope	string?	Granted OAuth scopes (optional)
expires	string?	Session expiration time (optional)
accessToken	string	Shopify access token
userId	string?	Shopify user ID (optional)
createdAt	string	Session creation timestamp
updatedAt	string	Last session update timestamp

Usage Examples

// Check Shopify integration status
try {
  const sessions = await client.user.getSessions();
  
  if (sessions.length === 0) {
    console.log('No Shopify sessions found');
  } else {
    console.log('Shopify integration active:');
    sessions.forEach(session => {
      console.log(`- Shop: ${session.shop}`);
      console.log(`  User ID: ${session.userId || 'N/A'}`);
      console.log(`  Status: ${session.isOnline ? 'Online' : 'Offline'}`);
      console.log(`  Created: ${new Date(session.createdAt).toLocaleDateString()}`);
      
      if (session.expires) {
        const expiryDate = new Date(session.expires);
        console.log(`  Expires: ${expiryDate.toLocaleDateString()}`);
      }
    });
  }
} catch (error) {
  console.error('Failed to get Shopify sessions:', error);
}

Security Warning: This method returns Shopify access tokens (accessToken) which are highly sensitive. These tokens should never be logged, stored insecurely, or transmitted to client applications. Handle with extreme care.

Error Handling

All user methods can throw specific error types:

import { 
  SuiPayAuthenticationError, 
  SuiPayServerError 
} from '@suipay/api';

try {
  const user = await client.user.get();
} catch (error) {
  if (error instanceof SuiPayAuthenticationError) {
    console.error('Authentication failed - check your API key');
  } else if (error instanceof SuiPayServerError) {
    console.error('Server error:', error.status, error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Common Error Scenarios

Error Type	Description	Common Causes
SuiPayAuthenticationError	Invalid or missing API key	Wrong API key, deactivated key
SuiPayServerError	Server-side error	Temporary service issues
Network errors	Connection issues	Network connectivity problems

Complete User Information Example

Here's a comprehensive example showing how to get and display all user information:

async function displayUserProfile() {
  try {
    // Get basic user info
    const user = await client.user.get();
    console.log('=== User Profile ===');
    console.log(`Name: ${user.business_name || user.email}`);
    console.log(`Email: ${user.email}`);
    console.log(`Sign-in Method: ${user.sign_in_method}`);
    console.log(`Balance: ${user.polar_balance_usdc} USDC`);
    console.log(`KYC Status: ${user.kyc_complete ? '✅ Verified' : '❌ Pending'}`);
    console.log(`Account Created: ${new Date(user.created_at).toLocaleDateString()}`);
    
    // Get bank accounts
    console.log('\n=== Bank Accounts ===');
    const bankAccounts = await client.user.getBankAccounts();
    if (bankAccounts.length === 0) {
      console.log('No bank accounts connected');
    } else {
      bankAccounts.forEach((account, index) => {
        console.log(`${index + 1}. ${account.bank_name || 'Bank'}`);
        console.log(`   Type: ${account.account_type}`);
        console.log(`   Last 4: ****${account.last_four}`);
        console.log(`   Country: ${account.country_code}`);
      });
    }
    
    // Get Shopify sessions (if applicable)
    if (user.sign_in_method === 'SHOPIFY') {
      console.log('\n=== Shopify Integration ===');
      const sessions = await client.user.getSessions();
      if (sessions.length === 0) {
        console.log('No active Shopify sessions');
      } else {
        sessions.forEach(session => {
          console.log(`Shop: ${session.shop}`);
          console.log(`User ID: ${session.userId || 'N/A'}`);
          console.log(`Status: ${session.isOnline ? 'Online' : 'Offline'}`);
          console.log(`Created: ${new Date(session.createdAt).toLocaleDateString()}`);
        });
      }
    }
    
  } catch (error) {
    console.error('Failed to load user profile:', error);
  }
}

Access Control

Important: API keys are scoped to specific users. When you use an API key:

1. The API key can only access the user account it was created for

2. You cannot access other users' data with your API key

3. All resources (payment links, withdrawals, bank accounts) are tied to your user account

4. Sensitive data like balances and access tokens are returned - handle with care

This ensures proper isolation and security between different API key holders.

Data Handling Best Practices

Sensitive Information

The user methods return sensitive data that requires careful handling:

// ✅ Good - handle sensitive data properly
const user = await client.user.get();
const publicUserData = {
  id: user.id,
  email: user.email,
  business_name: user.business_name,
  kyc_complete: user.kyc_complete
};
// Only expose non-sensitive data to frontend

// ❌ Bad - don't expose sensitive data
const user = await client.user.get();
// Don't send entire user object to frontend
// Don't log user.customer_id or user.polar_balance_usdc

Sensitive Fields:

• polar_balance_usdc: Current balance - don't cache or log

• customer_id: Bridge customer ID - used for KYC/banking

• accessToken: Shopify tokens - extremely sensitive

• kyc_complete: KYC status - may be subject to regulations

Security Recommendations

1. Never log sensitive fields in application logs

2. Use HTTPS only for all communications

3. Implement proper access controls in your application

4. Don't cache sensitive data like balances or tokens

5. Regularly rotate API keys and monitor usage

6. Follow data retention policies for financial information

// ✅ Good logging practice
console.log(`User ${user.id} retrieved profile data`);

// ❌ Bad - don't log sensitive data
console.log('User data:', user); // Contains sensitive fields