Wallet and Transaction Flow

This guide details the complete wallet management and transaction processing flows in the FinHub platform. These processes include retrieving wallet information, processing transactions, and managing transaction history.

Flow Overview

The following sequence diagram illustrates the wallet and transaction processes:

Detailed API Flow

Step 1: Get Customer Wallets

The first step is to retrieve the customer’s wallet information.

API Request:

POST /api/v2/wallet/customer-wallets
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

{
  "customerId": "cust_12345678"
}

Response:

{
  "wallets": [
    {
      "walletId": "wallet_12345678",
      "walletAddress": "0x1234567890abcdef",
      "walletType": "FIAT",
      "currency": "EUR",
      "balance": "1000.50",
      "availableBalance": "950.25",
      "status": "ACTIVE",
      "createdAt": "2025-05-15T10:30:00Z"
    },
    {
      "walletId": "wallet_87654321",
      "walletAddress": "0xabcdef1234567890",
      "walletType": "CRYPTO",
      "currency": "BTC",
      "balance": "0.05",
      "availableBalance": "0.05",
      "status": "ACTIVE",
      "createdAt": "2025-05-16T14:20:00Z"
    }
  ]
}

Implementation Notes:

The system returns all wallets associated with the customer
Each wallet includes its current balance and available balance
Wallet types can be FIAT or CRYPTO
The wallet address is used for transactions

Step 2: Get Transaction History

Customers can view their transaction history across all wallets or filtered by specific criteria.

API Request:

POST /api/v2/wallet/transaction-history
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

{
  "consumerId": "cust_12345678",
  "pageNumber": 0,
  "pageSize": 10,
  "searchKey": "",
  "fromDate": "2025-05-01T00:00:00Z",
  "toDate": "2025-06-01T23:59:59Z",
  "transactionType": "ALL" // or "DEPOSIT", "WITHDRAWAL", "TRANSFER"
}

Response:

{
  "over_all_transaction_history_by_customer": [
    {
      "transactionId": "txn_12345678",
      "orderId": "order_12345678",
      "transactionType": "DEPOSIT",
      "amount": "500.00",
      "currency": "EUR",
      "status": "COMPLETED",
      "sourceWallet": "0x1234567890abcdef",
      "destinationWallet": "0x1234567890abcdef",
      "fee": "2.50",
      "description": "Bank transfer deposit",
      "createdAt": "2025-05-20T09:15:00Z",
      "completedAt": "2025-05-20T09:20:00Z"
    },
    {
      "transactionId": "txn_87654321",
      "orderId": "order_87654321",
      "transactionType": "TRANSFER",
      "amount": "100.00",
      "currency": "EUR",
      "status": "COMPLETED",
      "sourceWallet": "0x1234567890abcdef",
      "destinationWallet": "IBAN: DE89370400440532013000",
      "fee": "1.00",
      "description": "SEPA transfer to external account",
      "createdAt": "2025-05-25T14:30:00Z",
      "completedAt": "2025-05-25T14:35:00Z"
    }
  ],
  "total_count": 24
}

Implementation Notes:

The response includes pagination information
Transactions can be filtered by date range, type, and search term
Each transaction includes detailed information about the source and destination
The total count helps with pagination implementation

Step 3: Process Transaction Fee

Before initiating a transaction, the system calculates any applicable fees.

API Request:

POST /api/v2/wallet/process-fee
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

{
  "customerId": "cust_12345678",
  "transactionType": "TRANSFER",
  "amount": "100.00",
  "currency": "EUR",
  "sourceWalletId": "wallet_12345678",
  "destinationType": "EXTERNAL_IBAN"
}

Response:

{
  "feeAmount": "1.00",
  "feeCurrency": "EUR",
  "feeType": "PERCENTAGE",
  "feePercentage": "1.00",
  "totalAmount": "101.00",
  "description": "1% fee for external SEPA transfers"
}

Implementation Notes:

Fees vary based on transaction type, amount, and destination
The system provides a breakdown of the fee calculation
The total amount includes the transaction amount plus fees
Some transaction types may have zero fees

Step 4: Process Transaction Limit

The system validates that the transaction does not exceed any applicable limits.

API Request:

POST /api/v2/wallet/process-limit
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

{
  "customerId": "cust_12345678",
  "transactionType": "TRANSFER",
  "amount": "100.00",
  "currency": "EUR",
  "sourceWalletId": "wallet_12345678"
}

Response:

{
  "limitCheck": "PASSED",
  "dailyLimit": "5000.00",
  "dailyUsed": "100.00",
  "dailyRemaining": "4900.00",
  "monthlyLimit": "20000.00",
  "monthlyUsed": "600.00",
  "monthlyRemaining": "19400.00",
  "singleTransactionLimit": "10000.00"
}

Implementation Notes:

The system checks multiple limit types (daily, monthly, per transaction)
If any limit is exceeded, the transaction is rejected
Limits may vary based on customer tier and KYC status
The response includes remaining limits for customer information

Step 5: Two-Factor Authentication (if required)

For security, certain transactions require two-factor authentication.

API Request to send verification code:

POST /api/v2/auth/2fa/send-code
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

{
  "customerId": "cust_12345678",
  "phoneNumber": "+12125551234"
}

Response:

{
  "status": "SENT",
  "expiresAt": "2025-06-01T09:25:00Z"
}

API Request to verify code:

POST /api/v2/auth/2fa/verify-code
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

{
  "customerId": "cust_12345678",
  "verificationCode": "123456"
}

Response:

{
  "status": "VERIFIED",
  "message": "Verification successful"
}

Implementation Notes:

2FA is typically required for transactions above certain thresholds
The verification code is valid for a limited time (usually 10 minutes)
The customer can request a new code if needed
After successful verification, the transaction can proceed

Step 6: Send Funds (Create Order)

After all validations, the system processes the transaction.

API Request:

POST /api/v2/wallet/send-fund
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

{
  "sourceWalletAddress": "0x1234567890abcdef",
  "destinationWalletAddress": "",
  "amount": "100.00",
  "currency": "EUR",
  "beneficiaryIban": "DE89370400440532013000",
  "beneficiaryName": "Jane Smith",
  "beneficiaryBankName": "Deutsche Bank",
  "beneficiaryCountry": "DE",
  "description": "Monthly rent payment"
}

Response:

{
  "orderId": "order_12345678",
  "transactionId": "txn_12345678",
  "status": "PROCESSING",
  "createdAt": "2025-06-01T09:45:00Z",
  "estimatedCompletionTime": "2025-06-01T10:00:00Z"
}

Implementation Notes:

For SEPA transfers, the beneficiary IBAN is required
The system creates an order and a transaction record
Initial status is PROCESSING
The estimated completion time varies by transaction type

Step 7: Get Order Details

After initiating a transaction, the customer can check its status.

API Request:

POST /api/v2/wallet/order-detail
Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

{
  "orderId": "order_12345678",
  "walletAddress": "0x1234567890abcdef"
}

Response:

{
  "orderId": "order_12345678",
  "transactionId": "txn_12345678",
  "orderType": "TRANSFER",
  "amount": "100.00",
  "fee": "1.00",
  "totalAmount": "101.00",
  "currency": "EUR",
  "status": "COMPLETED",
  "sourceWallet": "0x1234567890abcdef",
  "destinationDetails": {
    "type": "EXTERNAL_IBAN",
    "iban": "DE89370400440532013000",
    "name": "Jane Smith",
    "bankName": "Deutsche Bank",
    "country": "DE"
  },
  "createdAt": "2025-06-01T09:45:00Z",
  "updatedAt": "2025-06-01T09:50:00Z",
  "completedAt": "2025-06-01T09:50:00Z",
  "description": "Monthly rent payment"
}

Implementation Notes:

The order status can be PROCESSING, COMPLETED, FAILED, or CANCELLED
If the order fails, a reason is provided
The response includes all details about the transaction
The system updates the status in real-time

Transaction Types

The platform supports several transaction types:

Deposit: Adding funds to a wallet from an external source
Withdrawal: Transferring funds from a wallet to an external account
Internal Transfer: Moving funds between wallets owned by the same customer
External Transfer: Sending funds to another customer or external account
SEPA Transfer: Sending funds to an external IBAN account
Currency Exchange: Converting funds from one currency to another

Error Handling

The transaction process includes comprehensive error handling for various scenarios:

Error Scenario	Error Code	Description
Insufficient funds	INSUFFICIENT_FUNDS	The wallet does not have enough funds for the transaction
Limit exceeded	LIMIT_EXCEEDED	The transaction exceeds the customer’s limits
Invalid beneficiary	INVALID_BENEFICIARY	The beneficiary information is invalid
Invalid IBAN	INVALID_IBAN	The provided IBAN is not valid
Transaction rejected	TRANSACTION_REJECTED	The transaction was rejected by the system
2FA verification failed	2FA_VERIFICATION_FAILED	The 2FA verification was unsuccessful
Wallet inactive	WALLET_INACTIVE	The source or destination wallet is not active

Implementation Considerations

When implementing the wallet and transaction flows, consider the following:

Security: Implement proper authentication and authorization for all transactions
Idempotency: Ensure transactions are not processed multiple times
Consistency: Maintain consistent state across all services
Monitoring: Implement real-time monitoring for transaction processing
Compliance: Ensure all transactions comply with relevant regulations
Performance: Optimize for high throughput and low latency
Resilience: Implement proper error handling and recovery mechanisms

Next Steps

After implementing the wallet and transaction flows, consider:

About FinHub

​Wallet and Transaction Flow

​Flow Overview

​Detailed API Flow

​Step 1: Get Customer Wallets

​Step 2: Get Transaction History

​Step 3: Process Transaction Fee

​Step 4: Process Transaction Limit

​Step 5: Two-Factor Authentication (if required)

​Step 6: Send Funds (Create Order)

​Step 7: Get Order Details

​Transaction Types

​Error Handling

​Implementation Considerations

​Next Steps

Wallet and Transaction Flow

Flow Overview

Detailed API Flow

Step 1: Get Customer Wallets

Step 2: Get Transaction History

Step 3: Process Transaction Fee

Step 4: Process Transaction Limit

Step 5: Two-Factor Authentication (if required)

Step 6: Send Funds (Create Order)

Step 7: Get Order Details

Transaction Types

Error Handling

Implementation Considerations

Next Steps