Accounts API

Manage user wallet accounts, check balances, and manage external funding sources.

Base:/v1/account, /v1/FundingSource

Endpoints

GET

/v1/account

List Accounts

Retrieve all accounts for the authenticated user. Returns wallet accounts with balances.

Response

{
  "value": [
    {
      "id": 1,
      "accountNumber": "ACC-001-USD",
      "name": "Main USD Wallet",
      "description": "Primary USD account",
      "currencyCode": "USD",
      "status": "Active"
    },
    {
      "id": 2,
      "accountNumber": "ACC-002-JMD",
      "name": "JMD Wallet",
      "currencyCode": "JMD",
      "status": "Active"
    }
  ]
}

GET

/v1/account/{id}/balance

Get Account Balance

Retrieve the current and available balance for a specific account.

Path Parameters

Name	Type	Required	Description
id	number	Required	Account ID

Response

{
  "currentAmount": 5250.00,
  "availableAmount": 5100.00,
  "currencyCode": "USD"
}

Available amount may be less than current amount due to pending holds or reserved funds.

GET

/v1/FundingSource

List Funding Sources

Retrieve registered external funding sources (saved cards, bank accounts) for the current user.

Response

{
  "value": [
    {
      "id": 5,
      "name": "My Visa ****1111",
      "paymentOptionId": 1,
      "statusId": "Active",
      "isVerified": true,
      "maskedAccountNumber": "****1111",
      "expiryDate": "12/26"
    }
  ]
}

POST

/v1/fundingSource/{id}/verify

Verify Funding Source

Verify an external funding source using a verification code.

Path Parameters

Name	Type	Required	Description
id	number	Required	Funding source ID

Request Body

{
  "VerificationCode": "1234"
}

Types

AccountDto

interface AccountDto {
  id: number;
  accountNumber: string;
  name: string;
  description?: string;
  currencyCode: string;
  status: string;
}

FundingSourceDto

interface FundingSourceDto {
  id: number;
  name: string;
  description?: string;
  paymentOptionId: number;
  statusId: string;
  isVerified: boolean;
  isCardNotPresentAllowed?: boolean;
  maskedAccountNumber?: string;
  expiryDate?: string;
}

Usage Examples

Display account balances

TypeScript

import { paymentApi } from '@/lib/api/ecommerce-client';
import { formatCurrency } from '@/lib/api/ecommerce-client';

async function AccountBalances() {
  const accounts = await paymentApi.getAccounts();

  for (const account of accounts) {
    const balance = await paymentApi.getAccountBalance(account.id);
    console.log(
      `${account.name}: ${formatCurrency(balance.availableAmount, balance.currencyCode)}`
    );
  }
}

Use in React component

TypeScript

import { useQuery } from '@tanstack/react-query';
import { paymentApi } from '@/lib/api/ecommerce-client';

function WalletOverview() {
  const { data: accounts } = useQuery({
    queryKey: ['accounts'],
    queryFn: paymentApi.getAccounts,
  });

  return (
    <div className="grid gap-4 md:grid-cols-2">
      {accounts?.map((acc) => (
        <AccountCard key={acc.id} account={acc} />
      ))}
    </div>
  );
}