Wallet Management

Overview

This skill enables AI agents and applications to view and manage customer wallets, transactions, and reservations using Eclipse APIs.

It supports:

Retrieving customer details
Listing and inspecting wallets
Viewing wallet transactions (including enriched payment data)
Inspecting wallet reservations (held funds)

1. Get Customer Details

Retrieve a single customer profile.

Request

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenant_id}/customers/{customer_id}

Example Response

{
  "customerId": 1234567,
  "title": "MR",
  "gender": "M",
  "firstName": "John",
  "lastName": "Doe",
  "phone1": "27XXXXXXXXX",
  "email": "[email protected]",
  "nationalIdentityNumber": "XXXXXXXXXXXX",
  "status": "ACTIVE",
  "created": "2025-01-01T10:00:00.000Z",
  "lastModified": "2026-01-01T10:00:00.000Z",
  "countryOfResidence": "South Africa",
  "externalUniqueId": "uuid-redacted"
}

2. Get All Customer Wallets

Returns all wallets linked to a customer.

Request

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenant_id}/customers/{customer_id}/wallets?limit={limit}&offset={offset}

Example Response

[
  {
    "walletId": 100001,
    "customerId": 1234567,
    "name": "Primary Wallet",
    "description": "Customer main wallet",
    "currentBalance": 10000.00,
    "availableBalance": 9500.00,
    "reservations": 500.00,
    "status": "ACTIVE",
    "currency": "ZAR",
    "friendlyId": "WALLET-ABC123"
  },
  {
    "walletId": 100002,
    "customerId": 1234567,
    "name": "Savings Wallet",
    "description": "Customer savings wallet",
    "currentBalance": 25000.00,
    "availableBalance": 25000.00,
    "reservations": 0.00,
    "status": "ACTIVE",
    "currency": "ZAR",
    "friendlyId": "WALLET-XYZ789"
  }
]

3. Get Wallet by ID

Retrieve detailed information for a specific wallet.

Request

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenant_id}/wallets/{wallet_id}

Example Response

{
  "walletId": 100001,
  "customerId": 1234567,
  "name": "Primary Wallet",
  "currentBalance": 10000.00,
  "availableBalance": 9500.00,
  "reservations": 500.00,
  "status": "ACTIVE",
  "currency": "ZAR",
  "friendlyId": "WALLET-ABC123",
  "created": "2025-01-01T10:00:00.000Z"
}

4. Get Wallet Transactions

Retrieve transactions for a wallet within a date range.

Request

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenant_id}/wallets/{wallet_id}/transactions
?dateFromIncl={ISO_DATE}
&dateToExcl={ISO_DATE}
&fields={optional}
&limit={limit}
&offset={offset}

Notes

Dates must be in ISO 8601 format: 2026-03-01T00:00:00.000Z
fields can include:
- payments
- withdrawals
- remittances

Example Response

[
  {
    "transactionId": "TX-10001",
    "walletId": 100001,
    "type": "tfr.debit",
    "date": "2026-03-20T10:00:00.000Z",
    "amount": -50.00,
    "currency": "ZAR",
    "balance": 9950.00,
    "description": "Transfer to another wallet",
    "externalUniqueId": "uuid-redacted",
    "reversal": false
  },
  {
    "transactionId": "TX-10002",
    "walletId": 100001,
    "type": "tfr.debit.postilion.offus.pur.pos.domestic",
    "date": "2026-03-18T15:30:00.000Z",
    "amount": -120.00,
    "currency": "ZAR",
    "balance": 10000.00,
    "description": "POS Purchase",
    "info": [
      { "att": "transactionType", "val": "PR" },
      { "att": "cardScheme", "val": "Mastercard" },
      { "att": "channel", "val": "POS" },
      { "att": "maskedPan", "val": "XXXXXX******1234" }
    ],
    "reversal": false
  }
]

5. Get Wallet Reservations

Retrieve active reservations (held funds) on a wallet.

Purpose

Reservations represent funds that are held but not yet settled.

availableBalance = currentBalance - reservations

Request

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenant_id}/wallets/{wallet_id}/reservations

Example Response

[
  {
    "reservationId": 50001,
    "walletId": 100001,
    "sessionId": "session-redacted",
    "description": "Card authorisation hold",
    "amount": 500.00,
    "created": "2026-03-18T10:00:00.000Z",
    "expires": "2026-03-25T10:00:00.000Z"
  }
]

Common Patterns for AI Agents

1. Customer Wallet Summary

Get customer
Retrieve wallets
For each wallet:
- Show balances
- Highlight reserved funds

2. Transaction History Analysis

Select wallet
Fetch transactions with:
- fields=payments (if enriched data needed)
Group by:
- Type (POS, transfer, etc.)
- Date
- Merchant (from info)

3. Available Balance Calculation

Always rely on:

availableBalance (preferred), or
compute manually:

availableBalance = currentBalance - reservations

4. Detect Held Funds

Use reservations endpoint to:

Identify pending card authorisations
Detect long-running holds
Explain balance discrepancies

Error Handling

Typicall 401 responses indicate invalid authentication credentials or JWT and 403 responses indicate permissions issues.

Example Error Response

[
  {
    "type": "BUSINESS",
    "severity": "LOW",
    "description": "JWT has expired",
    "code": "ARCH014",
    "traceId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "spanId": "xxxxxxxxxxxxxxxx",
    "environment": "sandbox-environment"
  }
]

Best Practices

Always use pagination (limit, offset) for transactions
Filter transaction date ranges to reduce payload size
Use fields selectively to optimise performance
Prefer availableBalance over manual calculations where provided