Integration Guides

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)
  • Wallet funding (top-up) via wallet-to-wallet transfers

API Reference: developer.eftcorp.com/reference — search for wallets or customers to find all wallet and customer endpoints.

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"
  }
]

6. Check Customer Wallet Eligibility

Before provisioning a wallet for a customer, check which wallet types they are eligible for. Eligibility is determined by the customer's KYC outcome and must be verified before wallet creation.

Request

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/wallet-types
Authorization: Bearer {jwt}

Example Response

[
  { "walletTypeId": 5001, "allowed": true },
  { "walletTypeId": 5002, "allowed": false }
]

Only proceed with wallet creation for a walletTypeId where allowed is true.

Create Wallet

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/wallets
Authorization: Bearer {jwt}
Content-Type: application/json
{
  "walletTypeId": 5001,
  "currency": "ZAR",
  "status": "ACTIVE",
  "externalUniqueId": "wal-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 0
}

status: "ACTIVE", externalUniqueId, and version: 0 are all required. externalUniqueId must be a unique UUID — duplicates are rejected with 409 Conflict.

7. Wallet Funding (Top-up)

Trigger: "top up wallet", "fund wallet", "add money to wallet", "credit wallet"

Required inputs: tenantId, destination walletId, source walletId (float wallet), amount, currency

Wallet funding is a wallet-to-wallet transfer from a float or merchant wallet into a customer wallet.

Step 1 — Check Destination Wallet Balance

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

Response:

{
  "walletId": 1092847,
  "currentBalance": 250.00,
  "availableBalance": 250.00,
  "status": "ACTIVE",
  "currency": "ZAR"
}

Step 2 — Execute Transfer

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/wallets/transfers
{
  "fromWalletId": 9000001,
  "toWalletId": 1092847,
  "amount": 1500.00,
  "description": "Wallet top-up",
  "externalUniqueId": "topup-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response: 204 No Content on success (no response body).

Step 3 — Confirm New Balance

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

Notes

  • externalUniqueId must be a unique UUID per transfer. Duplicate IDs are rejected with 409 Conflict.
  • Transfers are synchronous — COMPLETED status means funds have moved immediately.
  • Do not retry with the same externalUniqueId. If uncertain whether a transfer completed, check the wallet balance first.

API Reference: GET /wallets/{walletId} · POST /wallets/transfers

Common Patterns for AI Agents

1. Customer Wallet Summary

  1. Get customer
  2. Retrieve wallets
  3. For each wallet:
    • Show balances
    • Highlight reserved funds

2. Transaction History Analysis

  1. Select wallet
  2. Fetch transactions with:
    • fields=payments (if enriched data needed)
  3. 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