Creating Wallets

Get users started in minutes with immediate value—no KYC verification required. Creating wallets allows users to experience the platform's benefits immediately, building momentum toward completing verification when they're ready to move money.

Create User → Create Wallet → Access Program Benefits

What's Available​

After creating wallets users can:

• Link bank accounts and cards for future use
• Receive and accumulate merchant communications
• Receive prizes and promotional benefits
• View balance and explore features

Why This Works: Users see immediate value—their program benefits for use, accounts linked—building momentum toward completing verification.

Implementation Guide​

Let's build the onboarding flow to set up a user and wallet.

Initial Setup​

First, establish your authentication headers that you'll use for all API calls:

const API_CONFIG = {
  baseUrl: 'https://merchant-api.accruesavings.com',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${CLIENT_SECRET}`,
    'client-id': CLIENT_ID
  }
};

Step 1: Create the User​

When a customer first interacts with your application:

Endpoint: POST /api/v1/users

async function createUser(customer) {
  const response = await fetch(`${API_CONFIG.baseUrl}/api/v1/users`, {
    method: 'POST',
    headers: API_CONFIG.headers,
    body: JSON.stringify({
      data: {
        type: 'User',
        attributes: {
          email: customer.email,
          phoneNumber: customer.phone,  // Format: +1XXXXXXXXXX
          firstName: customer.firstName,
          lastName: customer.lastName
        }
      }
    })
  });

  if (response.status === 409) {
    // User exists - this is fine, fetch their ID
    return await findExistingUser(customer.email);
  }

  const data = await response.json();
  return data.data.id;  // Store this ID
}

Key Points:

• Phone numbers must include country code
• Email and phone must be unique
• 409 Conflict means user exists (handle gracefully)
• Returns immediately—no verification needed

Step 2: Create the Wallet​

A wallet can be created for a user:

Endpoint: POST /api/v1/wallets

async function createWallet(userId) {
  const response = await fetch(`${API_CONFIG.baseUrl}/api/v1/wallets`, {
    method: 'POST',
    headers: API_CONFIG.headers,
    body: JSON.stringify({
      data: {
        type: 'Wallet',
        attributes: {
          userId: userId
        }
      }
    })
  });

  const data = await response.json();
  return data.data.id;
}

Important: Wallet creation is instant and doesn't require KYC. Users can immediately start receiving rewards and linking accounts.

Error Handling​

Handle common errors gracefully:

const errorHandlers = {
  UserAlreadyExists: async (email) => {
    // User exists - fetch and continue
    return await findExistingUser(email);
  },

  WalletAlreadyExists: () => ({
    success: true,
    message: 'Wallet ready'
  })
};

Next Steps​

Once a wallet is created, users can:

• Link accounts for future use
• Receive rewards and program benefits
• Explore wallet features

When users are ready to move money, they'll need to complete KYC to enable deposits, purchases, and withdrawals.