Wallet and Transaction API Calls

This document provides detailed information about all API calls used in wallet management and transaction processing. Each API call includes the endpoint, method, request parameters, and response format.

Get Customer Wallets

Retrieves all wallets associated with a customer.

Endpoint: /api/v2/wallet/customer-wallets

Microservice: walletMicroService

Method: POST

Headers:

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

Status Codes:

200 OK: Wallets retrieved successfully
401 Unauthorized: Invalid or expired token
404 Not Found: No wallets found for customer

Get Transaction History

Retrieves transaction history for a customer.

Endpoint: /api/v2/wallet/transaction-history

Microservice: walletMicroService

Method: POST

Headers:

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
}

Status Codes:

200 OK: Transaction history retrieved successfully
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or expired token

Process Transaction Fee

Calculates fees for a transaction.

Endpoint: /api/v2/wallet/process-fee

Microservice: customerMicroService

Method: POST

Headers:

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

Status Codes:

200 OK: Fee calculated successfully
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or expired token

Process Transaction Limit

Validates that a transaction does not exceed applicable limits.

Endpoint: /api/v2/wallet/process-limit

Microservice: customerMicroService

Method: POST

Headers:

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

Status Codes:

200 OK: Limit check passed
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or expired token
403 Forbidden: Transaction exceeds limits

Send 2FA Verification Code

Sends a verification code for transaction authorization.

Endpoint: /api/v2/auth/2fa/send-code

Microservice: bffMs

Method: POST

Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

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

Response:

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

Status Codes:

200 OK: Verification code sent successfully
400 Bad Request: Invalid phone number
401 Unauthorized: Invalid or expired token
429 Too Many Requests: Too many verification attempts

Verify 2FA Code

Verifies the 2FA code for transaction authorization.

Endpoint: /api/v2/auth/2fa/verify-code

Microservice: bffMs

Method: POST

Headers:

Content-Type: application/json
Authorization: Bearer {access_token}

Request Body:

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

Response:

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

Status Codes:

200 OK: Verification successful
400 Bad Request: Invalid verification code
401 Unauthorized: Invalid or expired token
410 Gone: Verification code expired
429 Too Many Requests: Too many verification attempts

Send Funds (Create Order)

Creates a transaction order.

Endpoint: /api/v2/wallet/send-fund

Microservice: bffMs

Method: POST

Headers:

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

Status Codes:

201 Created: Order created successfully
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or expired token
403 Forbidden: Insufficient funds or limits exceeded
422 Unprocessable Entity: Invalid beneficiary information

Get Order Details

Retrieves details of a specific order.

Endpoint: /api/v2/wallet/order-detail

Microservice: walletMicroService

Method: POST

Headers:

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

Status Codes:

200 OK: Order details retrieved successfully
401 Unauthorized: Invalid or expired token
404 Not Found: Order not found

Internal API Calls

These are the internal API calls used by the system during wallet and transaction processing:

walletV2.getCustomerWallets

Microservice: walletMicroService

Description: Retrieves all wallets associated with a customer.

Request Parameters:

customerId: Customer ID

Response:

List of wallets with their details (ID, address, type, currency, balance, status)

walletV2.getOverAllTransactionHistoryByCustomer

Microservice: walletMicroService

Description: Retrieves transaction history for a customer.

Request Parameters:

consumerId: Customer ID
pageNumber: Page number for pagination
pageSize: Number of records per page
searchKey: Optional search term
fromDate: Start date for filtering
toDate: End date for filtering
transactionType: Type of transactions to retrieve

Response:

List of transactions with their details
Total count of transactions

walletV2.getAssetTransactions

Microservice: walletMicroService

Description: Retrieves transactions for a specific asset.

Request Parameters:

customerId: Customer ID
assetId: Asset ID
pageNumber: Page number for pagination
pageSize: Number of records per page

Response:

List of transactions for the specified asset
Total count of transactions

walletRule.processFee

Microservice: customerMicroService

Description: Calculates fees for a transaction.

Request Parameters:

customerId: Customer ID
transactionType: Type of transaction
amount: Transaction amount
currency: Transaction currency
sourceWalletId: Source wallet ID
destinationType: Type of destination

Response:

Fee amount and details
Total amount including fees

walletRule.processLimit

Microservice: customerMicroService

Description: Checks if a transaction exceeds any limits.

Request Parameters:

customerId: Customer ID
transactionType: Type of transaction
amount: Transaction amount
currency: Transaction currency
sourceWalletId: Source wallet ID

Response:

Limit check result
Daily and monthly limits and usage

bff.resendCode

Microservice: bffMs

Description: Sends a verification code for transaction authorization.

Request Parameters:

customerId: Customer ID
phoneNumber: Phone number to send code to

Response:

Status of the code sending operation
Expiration time of the code

bff.verifySmsCode

Microservice: bffMs

Description: Verifies the SMS code for transaction authorization.

Request Parameters:

customerId: Customer ID
verificationCode: Code to verify

Response:

Verification status
Status message

bff.sendFund

Microservice: bffMs

Description: Creates a transaction order.

Request Parameters:

sourceWalletAddress: Source wallet address
destinationWalletAddress: Destination wallet address (optional)
amount: Transaction amount
currency: Transaction currency
beneficiaryIban: Beneficiary IBAN (for SEPA transfers)
beneficiaryName: Beneficiary name
beneficiaryBankName: Beneficiary bank name
beneficiaryCountry: Beneficiary country

Response:

Order ID and transaction ID
Status and estimated completion time

walletV2.getOrderDetail

Microservice: walletMicroService

Description: Retrieves details of a specific order.

Request Parameters:

orderId: Order ID
walletAddress: Wallet address

Response:

Detailed order information including status, amounts, source and destination details

Integration Guides

Customer Journey

API 2.x Reference

Wallet and Transaction API Calls

Wallet and Transaction API Calls

Get Customer Wallets

Get Transaction History

Process Transaction Fee

Process Transaction Limit

Send 2FA Verification Code

Verify 2FA Code

Send Funds (Create Order)

Get Order Details

Internal API Calls

walletV2.getCustomerWallets

walletV2.getOverAllTransactionHistoryByCustomer

walletV2.getAssetTransactions

walletRule.processFee

walletRule.processLimit

bff.resendCode

bff.verifySmsCode

bff.sendFund

walletV2.getOrderDetail

Integration Guides

Customer Journey

API 2.x Reference

​Wallet and Transaction API Calls

​Get Customer Wallets

​Get Transaction History

​Process Transaction Fee

​Process Transaction Limit

​Send 2FA Verification Code

​Verify 2FA Code

​Send Funds (Create Order)

​Get Order Details

​Internal API Calls

​walletV2.getCustomerWallets

​walletV2.getOverAllTransactionHistoryByCustomer

​walletV2.getAssetTransactions

​walletRule.processFee

​walletRule.processLimit

​bff.resendCode

​bff.verifySmsCode

​bff.sendFund

​walletV2.getOrderDetail

Wallet and Transaction API Calls

Get Customer Wallets

Get Transaction History

Process Transaction Fee

Process Transaction Limit

Send 2FA Verification Code

Verify 2FA Code

Send Funds (Create Order)

Get Order Details

Internal API Calls

walletV2.getCustomerWallets

walletV2.getOverAllTransactionHistoryByCustomer

walletV2.getAssetTransactions

walletRule.processFee

walletRule.processLimit

bff.resendCode

bff.verifySmsCode

bff.sendFund

walletV2.getOrderDetail