Wallet and Transaction Flow

This guide details the complete wallet management and transaction processing flows in the FinHub platform v2.1. The new APIs provide a streamlined three-step process for executing transfers: checking allowed operations, preparing orders, and executing them. The flow includes enhanced security through payment consents and beneficiary management.

Flow Overview

The following sequence diagram illustrates the enhanced wallet and transaction processes with v2.1 APIs:

Prerequisites

Before processing transactions, ensure:

Customer is activated - Account activation automatically creates wallet and IBAN
Customer is authenticated - Valid customer token required for all operations
Session is established - X-Session-Id header required for transaction operations
Beneficiaries are added - At least one beneficiary for transfers
Payment consent is created (optional but recommended) - For enhanced security

Detailed API Flow

Step 1: Get Wallet Details

After customer activation, retrieve the wallet information including the IBAN and current balance. API Request:

GET /api/v2.1/wallet/{walletId}
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Response:

{
  "data": {
    "walletId": "wal_def789ghi012",
    "customerId": "cust_abc123def456",
    "iban": "FR1420041010050500013M02606",
    "bic": "FINHFRPPXXX",
    "currency": "EUR",
    "status": "ACTIVE",
    "balance": {
      "available": "1000.50",
      "current": "1000.50",
      "locked": "0.00"
    },
    "limits": {
      "dailyTransactionLimit": "25000.00",
      "monthlyTransactionLimit": "100000.00",
      "inherited": true,
      "source": "CUSTOMER_CATEGORY"
    },
    "features": {
      "instantPayments": true,
      "internationalTransfers": true,
      "cryptoOperations": false
    },
    "createdAt": "2025-01-23T10:30:00Z"
  }
}

Three-Balance Model:

Available: Funds available for immediate use
Current: Total balance including pending transactions
Locked: Funds reserved for pending operations

Step 2: Add Beneficiaries

Before making transfers, add beneficiaries to the wallet. API Request:

POST /api/v2.1/fintrans/{walletId}/beneficiaries
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Request Body:

{
  "partyType": "INDIVIDUAL_CUSTOMER",
  "firstName": "Emma",
  "lastName": "Johnson",
  "shortName": "Emma Johnson",
  "iban": "GB82WEST12345698765432",
  "currency": "EUR",
  "country": "GB",
  "email": "emma.johnson@example.com",
  "phoneNumber": "+441234567890",
  "bicSwiftCode": "WESTGB2L",
  "networkName": "SEPA",
  "bankName": "Westminster Bank",
  "bankAddress": "1 Churchill Place, London E14 5HP, UK",
  "purposeCode": "OTHR"
}

Response:

{
  "data": {
    "id": "ben_abc123xyz789",
    "status": "ACTIVE",
    "shortName": "Emma Johnson",
    "iban": "GB82WEST12345698765432",
    "networkName": "SEPA",
    "verificationStatus": "VERIFIED",
    "createdAt": "2025-01-23T11:00:00Z"
  }
}

For enhanced security, create a payment consent that defines transfer limits and beneficiary restrictions. API Request:

POST /api/v2.1/fintrans/{walletId}/consents/payment
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Request Body:

{
  "paymentType": "TRANSFER",
  "limits": {
    "maxAmountPerTransaction": "5000.00",
    "dailyLimit": "10000.00",
    "weeklyLimit": "25000.00",
    "monthlyLimit": "50000.00",
    "currency": "EUR"
  },
  "beneficiaryRestrictions": {
    "enabled": true,
    "allowedBeneficiaries": ["ben_abc123xyz789"],
    "allowNewBeneficiaries": false
  },
  "validFrom": "2025-01-23",
  "validUntil": "2026-01-23",
  "description": "Standard payment consent for EUR transfers"
}

Response:

{
  "data": {
    "id": "consent_def456ghi012",
    "consentReference": "consent-payment-xyz789",
    "status": "ACTIVE",
    "requiresAcceptance": false,
    "validUntil": "2026-01-23"
  }
}

Three-Step Transfer Process

The v2.1 API introduces a secure three-step process for executing transfers:

Step 4: Get Allowed Operations

First, check what operations are available for the wallet based on current balance, limits, and consents. API Request:

GET /api/v2.1/fintrans/{walletId}/allowed-operations
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Response:

{
  "data": {
    "operations": [
      {
        "type": "transfer",
        "enabled": true,
        "limits": {
          "minAmount": "1.00",
          "maxAmount": "5000.00",
          "dailyLimit": "10000.00",
          "monthlyLimit": "50000.00"
        },
        "consentRequired": true,
        "activeConsents": 1
      },
      {
        "type": "topup",
        "enabled": true,
        "limits": {
          "minAmount": "10.00",
          "maxAmount": "50000.00"
        },
        "consentRequired": false
      }
    ],
    "beneficiaries": {
      "total": 1,
      "active": 1,
      "currencies": ["EUR"]
    },
    "account": {
      "balances": {
        "available": "1000.50",
        "current": "1000.50",
        "locked": "0.00"
      },
      "currency": "EUR",
      "status": "ACTIVE"
    }
  }
}

Step 5: Prepare Order

Prepare the transfer order to validate and calculate fees. API Request:

POST /api/v2.1/fintrans/{walletId}/order/prepare
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Request Body:

{
  "amount": {
    "value": "25050",  // €250.50 in cents
    "scale": 2,
    "currency": "EUR"
  },
  "operationType": "TRANSFER",
  "target": {
    "iban": "GB82WEST12345698765432",
    "name": "Emma Johnson"
  },
  "reference": "Invoice payment #INV-2025-001",
  "consent": {
    "consentReference": "consent-payment-xyz789"
  }
}

Response:

{
  "data": {
    "orderId": "prep_order_abc123",
    "status": "PREPARED",
    "amount": {
      "value": "25050",
      "scale": 2,
      "currency": "EUR"
    },
    "fees": {
      "transferFee": "250",  // €2.50 in cents
      "totalAmount": "252"   // €2.52 total fees
    },
    "totalAmount": {
      "value": "25302",  // €253.02 total including fees
      "scale": 2,
      "currency": "EUR"
    },
    "validations": {
      "consentValid": true,
      "sufficientBalance": true,
      "withinLimits": true,
      "beneficiaryAllowed": true
    },
    "expiresAt": "2025-01-23T12:30:00Z"
  }
}

Step 6: Execute Order

Complete the transfer by executing the prepared order. API Request:

POST /api/v2.1/fintrans/{walletId}/types/transfer/execute
Content-Type: application/json
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Request Body:

{
  "preparedOrderId": "prep_order_abc123",
  "authenticationCode": "123456",  // 2FA code if required
  "consentConfirmation": {
    "consentId": "consent-payment-xyz789",
    "confirmed": true,
    "timestamp": "2025-01-23T12:00:00.000Z",
    "channel": "WEB",
    "signature": "customer_confirmed_transfer"
  }
}

Response:

{
  "data": {
    "transactionId": "txn_xyz789def123",
    "orderId": "ord_final_abc456",
    "status": "COMPLETED",
    "executedAt": "2025-01-23T12:00:05.000Z",
    "amount": {
      "value": "250.50",
      "currency": "EUR"
    },
    "fees": {
      "total": "2.52"
    },
    "balances": {
      "before": {
        "available": "1000.50",
        "current": "1000.50",
        "locked": "0.00"
      },
      "after": {
        "available": "747.48",
        "current": "747.48",
        "locked": "0.00"
      }
    },
    "networkReference": "SEPA-2025-XYZ789",
    "beneficiary": {
      "name": "Emma Johnson",
      "iban": "GB82WEST12345698765432"
    }
  }
}

Step 7: Get Transaction History

View completed transactions and their details. API Request:

GET /api/v2.1/fintrans/{walletId}/transactions?page=0&size=10&sort=executedAt,desc
Authorization: Bearer {customer_token}
X-Tenant-ID: {tenant_id}
X-Session-Id: {session_id}

Response:

{
  "data": {
    "transactions": [
      {
        "transactionId": "txn_xyz789def123",
        "type": "TRANSFER",
        "amount": "250.50",
        "currency": "EUR",
        "status": "COMPLETED",
        "reference": "Invoice payment #INV-2025-001",
        "beneficiary": {
          "name": "Emma Johnson",
          "iban": "GB82***5432"  // Masked for security
        },
        "fees": "2.52",
        "executedAt": "2025-01-23T12:00:05.000Z",
        "networkReference": "SEPA-2025-XYZ789"
      }
    ],
    "pagination": {
      "page": 0,
      "size": 10,
      "totalElements": 47,
      "totalPages": 5
    }
  }
}

Key Features of v2.1 Transaction Flow

Three-Step Process Benefits

Pre-validation: Check allowed operations before attempting transfers
Transparent Fees: Calculate exact fees before execution
Consent Enforcement: Automatic validation of payment consents
Balance Protection: Three-balance model prevents overdrafts
Beneficiary Security: Restrict transfers to approved beneficiaries

Supported Transaction Types

SEPA Transfers: Standard European payments
SEPA Instant: Real-time European transfers
International Transfers: SWIFT and other networks (if enabled)
Internal Transfers: Between customer’s own accounts
Top-ups: Adding funds to the wallet

Error Handling

The v2.1 API provides detailed error responses:

Error Code	HTTP Status	Description
INSUFFICIENT_BALANCE	409	Wallet balance insufficient for the transaction
LIMIT_EXCEEDED	422	Transaction exceeds defined limits
INVALID_BENEFICIARY	403	Beneficiary not in allowed list
CONSENT_EXPIRED	422	Payment consent has expired
CONSENT_LIMIT_EXCEEDED	422	Transaction exceeds consent limits
ORDER_EXPIRED	410	Prepared order has expired
INVALID_IBAN	400	Provided IBAN is invalid
DUPLICATE_EXECUTION	409	Order already executed
WALLET_INACTIVE	403	Wallet is not active
SESSION_REQUIRED	401	Valid session ID required

Error Response Example

{
  "error": {
    "code": "CONSENT_LIMIT_EXCEEDED",
    "message": "Transaction amount exceeds the maximum allowed by payment consent",
    "details": {
      "requestedAmount": "5500.00",
      "maxAllowed": "5000.00",
      "consentReference": "consent-payment-xyz789"
    },
    "requestId": "req_error_abc123",
    "timestamp": "2025-01-23T12:15:00Z"
  }
}

Security Best Practices

Session Management: Always include X-Session-Id for transaction operations
Token Security: Use customer tokens only for customer-initiated operations
Consent Validation: Create payment consents with appropriate limits
Beneficiary Verification: Validate beneficiaries before adding to allowed lists
2FA Implementation: Enable two-factor authentication for high-value transfers
Audit Trail: Log all transaction attempts and outcomes

Implementation Checklist

Implement wallet balance monitoring
Set up beneficiary management workflow
Create payment consents with appropriate limits
Implement three-step transfer process
Handle all error scenarios gracefully
Add transaction history pagination
Implement webhook handlers for real-time updates
Set up monitoring and alerting

Performance Optimization

Cache Beneficiaries: Store frequently used beneficiaries locally
Batch Operations: Group multiple operations when possible
Async Processing: Use webhooks for transaction status updates
Connection Pooling: Maintain persistent API connections
Rate Limiting: Implement client-side rate limiting

Next Steps

After implementing the wallet and transaction flows:

About FinHub

​Wallet and Transaction Flow

​Flow Overview

​Prerequisites

​Detailed API Flow

​Step 1: Get Wallet Details

​Step 2: Add Beneficiaries

​Step 3: Create Payment Consent (Recommended)

​Three-Step Transfer Process

​Step 4: Get Allowed Operations

​Step 5: Prepare Order

​Step 6: Execute Order

​Step 7: Get Transaction History

​Key Features of v2.1 Transaction Flow

​Three-Step Process Benefits

​Supported Transaction Types

​Error Handling

​Error Response Example

​Security Best Practices

​Implementation Checklist

​Performance Optimization

​Next Steps

​Related API Documentation

Wallet and Transaction Flow

Flow Overview

Prerequisites

Detailed API Flow

Step 1: Get Wallet Details

Step 2: Add Beneficiaries

Step 3: Create Payment Consent (Recommended)

Three-Step Transfer Process

Step 4: Get Allowed Operations

Step 5: Prepare Order

Step 6: Execute Order

Step 7: Get Transaction History

Key Features of v2.1 Transaction Flow

Three-Step Process Benefits

Supported Transaction Types

Error Handling

Error Response Example

Security Best Practices

Implementation Checklist

Performance Optimization

Next Steps

Related API Documentation