Phase 6: Wallet Operations

Query balance, check allowed operations, and view transaction limits

Phase 6: Wallet Operations

After activation, the customer can query their wallet balance, check allowed operations, and view transaction limits.

Prerequisites

Requirement	Status
Customer Status	ACTIVE
Wallet Status	ACTIVE
Valid Session	JWT token

---

Get Wallet Balance

Request

Endpoint: GET /api/v2.1/fintrans/{accountId}/balance

Path Parameters:

• accountId: Wallet ID from activation response

Headers:

Authorization: Bearer {jwt-token}

Response

Status: 200 OK

{
  "code": 200,
  "message": "Balance retrieved successfully",
  "data": {
    "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
    "iban": "FR7630001007941234567890185",
    "currency": "EUR",
    "status": "ACTIVE",
    "currentBalance": "500000",
    "currentBalanceFormatted": "5000.00",
    "availableBalance": "450000",
    "availableBalanceFormatted": "4500.00",
    "blockedBalance": "50000",
    "blockedBalanceFormatted": "500.00",
    "lastTransaction": "2026-01-14T15:30:00.000Z",
    "balanceHistory": [
      {
        "date": "2026-01-14",
        "balance": "5000.00"
      }
    ]
  }
}

Balance Fields

Field	Description
currentBalance	Total balance in minor units (cents)
currentBalanceFormatted	Formatted balance with currency
availableBalance	Balance available for transactions
blockedBalance	Balance blocked for pending transactions

Balance Format: Balances are returned in minor units (cents). Divide by 100 for the actual amount. Example: 500000 = €5000.00

---

Get Allowed Operations

Request

Endpoint: GET /api/v2.1/fintrans/{accountId}/allowed-operations

Query Parameters:

• includeBeneficiaries: true/false
• includeConsents: true/false

Headers:

Authorization: Bearer {jwt-token}

Response

Status: 200 OK

{
  "code": 200,
  "message": "Allowed operations retrieved successfully",
  "data": {
    "accountId": "wallet-aa0e8400-e29b-41d4-a716-446655440050",
    "operations": [
      {
        "operationType": "TRANSFER",
        "allowedNetworks": ["SEPA", "SWIFT"],
        "requiresConsent": true,
        "requiresApproval": false,
        "enabled": true
      },
      {
        "operationType": "PAYMENT",
        "allowedNetworks": ["SEPA"],
        "requiresConsent": true,
        "requiresApproval": false,
        "enabled": true
      },
      {
        "operationType": "TOPUP",
        "allowedNetworks": ["SEPA"],
        "requiresConsent": false,
        "requiresApproval": false,
        "enabled": true
      }
    ],
    "limits": {
      "perTxn": {
        "EUR": 2000
      },
      "daily": {
        "EUR": 5000
      },
      "monthly": {
        "EUR": 50000
      }
    },
    "accountLimits": {
      "dailyTransactionLimit": 5000,
      "monthlyTransactionLimit": 50000,
      "singleTransactionLimit": 2000,
      "currency": "EUR",
      "limitType": "CATEGORY_BASED",
      "categoryName": "HIGH_RISK_INDIVIDUAL"
    },
    "consentStatus": {
      "hasValidPaymentConsent": true,
      "hasRecurringPaymentConsent": false,
      "hasPreApprovalConsent": false,
      "hasInternationalTransferConsent": true,
      "missingConsents": [],
      "allRequiredConsentsValid": true,
      "lastUpdated": "2026-01-14T14:00:00.000Z"
    },
    "enabledFeatures": [
      "TRANSFER",
      "PAYMENT",
      "INTERNATIONAL",
      "SCHEDULED_PAYMENT"
    ],
    "beneficiaries": [],
    "beneficiaryRules": [
      {
        "ruleType": "ALLOWED_TYPES",
        "allowedValues": ["INTERNAL", "SEPA", "SWIFT"],
        "description": "Allowed beneficiary types"
      },
      {
        "ruleType": "REQUIRE_PRE_REGISTRATION",
        "value": true,
        "description": "Beneficiaries must be pre-registered"
      }
    ]
  }
}

---

Operation Types

Operation	Description	Networks
TRANSFER	Send money to beneficiary	SEPA, SWIFT
PAYMENT	Make a payment	SEPA
TOPUP	Add funds to wallet	SEPA

---

Transaction Limits

Limits are determined by customer categorization:

High-Risk Individual

Limit Type	Amount (EUR)
Per Transaction	2,000
Daily	5,000
Monthly	50,000

Standard Individual

Limit Type	Amount (EUR)
Per Transaction	5,000
Daily	10,000
Monthly	100,000

Limits are enforced at transaction time. Exceeding limits will result in transaction rejection.

---

Consent Status

The consentStatus object indicates which payment consents are in place:

Field	Description
hasValidPaymentConsent	Basic payment consent active
hasRecurringPaymentConsent	Recurring payments enabled
hasPreApprovalConsent	Pre-approved payments enabled
hasInternationalTransferConsent	International transfers enabled
allRequiredConsentsValid	All required consents are active

---

Get Transaction History

Request

Endpoint: GET /api/v2.1/fintrans/{accountId}/orders

Query Parameters:

• page: Page number (default: 0)
• size: Page size (default: 20)
• status: Filter by status
• fromDate: Start date filter
• toDate: End date filter

Headers:

Authorization: Bearer {jwt-token}

Response

Status: 200 OK

{
  "code": 200,
  "message": "Orders retrieved successfully",
  "data": {
    "content": [
      {
        "orderId": "order-ff0e8400-e29b-41d4-a716-446655440081",
        "operationType": "TRANSFER",
        "status": "COMPLETED",
        "amount": "100000",
        "amountFormatted": "1000.00",
        "currency": "EUR",
        "beneficiaryName": "Jane Smith",
        "beneficiaryIban": "GB82WEST12345698765432",
        "reference": "FAM-2026-001",
        "createdAt": "2026-01-14T15:45:00.000Z",
        "executedAt": "2026-01-14T15:45:30.000Z"
      }
    ],
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

---

Next Step

Proceed to Phase 7: Payment Operations to add beneficiaries and execute transfers.

Phase 7: Payment Operations

Add beneficiaries and execute transfers