Account Operations API

Type-specific endpoints for financial operations: topups, transfers, and withdrawals using the prepare-execute workflow.

Status: Production ReadyRecommended: Use these endpoints instead of the generic /transfers API which has known issues.

Base URL: https://sandbox.finhub.cloud/api/v2.1/fintrans

For complete details on authentication and headers, refer to the Standard HTTP Headers reference documentation.

Operation Types

The API supports three operation types:

Type	Purpose	Typical Use Case
`topup`	Add funds to account	Funding wallet from external bank
`transfer`	Move funds between accounts	P2P transfers, payouts
`withdrawal`	Remove funds from account	Cash out to external bank

Topup Workflow

Add funds to an account from an external source.

Step 1: Prepare Topup

Validate and stage a topup operation.

Endpoint

POST /api/v2.1/fintrans/{accountId}/types/topup/prepare

Path Parameters

accountId

string

required

Target account UUID to receive fundsExample: 69a7d5b0-58f0-4394-a3fc-4d33058dc89e

Headers

X-Tenant-ID

string

required

Tenant identifier

Authorization

string

required

Bearer token for authentication

Content-Type

string

required

Must be application/json

Request Body

type

string

required

Operation type - must be TOPUP

sourceAccount

object

required

External source account details

Show sourceAccount properties

iban

string

required

IBAN of the source bank accountExample: FI2112345600000785

bic

string

BIC/SWIFT code (optional for SEPA)

accountHolder

string

Name of the account holder

target

object

required

Target account reference

Show target properties

name

string

required

Display name for the targetExample: Wallet: 69a7d5b0-58f0-4394-a3fc-4d33058dc89e

accountId

string

Account UUID (usually same as path parameter)

amount

object

required

Amount to topup (see AmountDto)

Show amount properties

value

string

required

Amount in minor units (cents)Example: "5000000" = 50,000.00 EUR

currency

string

required

ISO 4217 currency codeExample: EUR, USD, GBP

scale

integer

required

Decimal places for the currencyExample: 2 for EUR (cents), 0 for JPY

reference

string

Payment reference or descriptionMax length: 140 characters

metadata

object

Optional metadata for tracking

Show metadata properties

orderId

string

External order reference

customerId

string

Customer identifier

note

string

Internal note

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/69a7d5b0-58f0-4394-a3fc-4d33058dc89e/types/topup/prepare" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TOPUP",
    "sourceAccount": {
      "iban": "FI2112345600000785",
      "accountHolder": "John Doe"
    },
    "target": {
      "name": "Wallet: 69a7d5b0-58f0-4394-a3fc-4d33058dc89e",
      "accountId": "69a7d5b0-58f0-4394-a3fc-4d33058dc89e"
    },
    "amount": {
      "value": "5000000",
      "currency": "EUR",
      "scale": 2
    },
    "reference": "Initial wallet funding",
    "metadata": {
      "orderId": "ORD-2026-001",
      "note": "Wallet funding transaction"
    }
  }'

Response

{
  "code": 200,
  "message": "Success",
  "data": {
    "preparedOrderId": "666f111b-20fd-4756-b610-3ee24938e96a",
    "summary": {
      "amount": {
        "value": "5000000",
        "currency": "EUR",
        "scale": 2
      },
      "sourceAccount": "FI2112345600000785",
      "targetAccount": "69a7d5b0-58f0-4394-a3fc-4d33058dc89e",
      "fees": {
        "value": "0",
        "currency": "EUR",
        "scale": 2
      },
      "estimatedCompletionTime": "2026-01-13T10:30:00Z"
    },
    "validUntil": "2026-01-13T10:25:00Z",
    "requiresConfirmation": true
  }
}

Important: The preparedOrderId is valid for a limited time (typically 5 minutes). Execute the operation before validUntil expires.

Step 2: Execute Topup

Execute a prepared topup operation.

Endpoint

POST /api/v2.1/fintrans/{accountId}/types/topup/execute

Path Parameters

accountId

string

required

Target account UUID (must match the prepare request)

Request Body

preparedOrderId

string

required

Prepared order ID from the prepare stepExample: 666f111b-20fd-4756-b610-3ee24938e96a

confirmationCode

string

2FA or confirmation code (if required by policy)

clientReference

string

Client-side reference for idempotency

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/69a7d5b0-58f0-4394-a3fc-4d33058dc89e/types/topup/execute" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preparedOrderId": "666f111b-20fd-4756-b610-3ee24938e96a",
    "confirmationCode": "123456"
  }'

Response

{
  "code": 200,
  "message": "Transaction executed successfully",
  "data": {
    "executionId": "01d40939-0b87-4cda-b4aa-ac6cf3ab61ab",
    "status": "EXECUTED",
    "transactionId": "TXN-2026-001-ABC123",
    "amount": {
      "value": "5000000",
      "currency": "EUR",
      "scale": 2
    },
    "executedAt": "2026-01-13T10:24:35.123Z",
    "estimatedSettlement": "2026-01-13T11:00:00Z",
    "trackingReference": "TRK-666f111b-20fd"
  }
}

Transfer Workflow

Move funds between internal accounts or to external beneficiaries.

Prepare Transfer

POST /api/v2.1/fintrans/{accountId}/types/transfer/prepare

Request Body Structure

{
  "type": "TRANSFER",
  "sourceAccount": {
    "accountId": "69a7d5b0-58f0-4394-a3fc-4d33058dc89e"
  },
  "beneficiary": {
    "id": "benef_123456",
    "accountNumber": "LT121000011101001000",
    "name": "Recipient Name"
  },
  "amount": {
    "value": "10000",
    "currency": "EUR",
    "scale": 2
  },
  "reference": "Invoice payment #INV-2026-001",
  "transferType": "SEPA"
}

Execute Transfer

POST /api/v2.1/fintrans/{accountId}/types/transfer/execute

Same execution flow as topup - provide preparedOrderId.

Withdrawal Workflow

Remove funds from wallet to an external bank account. Typically used for cash-out operations to a personal or business bank account.

Step 1: Prepare Withdrawal

POST /api/v2.1/fintrans/{accountId}/types/withdraw/prepare

Endpoint Note: The operation type is withdraw (not withdrawal) in the URL path.

Path Parameters

accountId

string

required

Source wallet/account UUID

Request Body

sourceAccount

object

required

Source wallet details

Show sourceAccount properties

walletId

string

required

Wallet UUID to withdraw from

targetAccount

object

required

Target bank account details

Show targetAccount properties

iban

string

required

IBAN of the destination bank accountExample: FI2112345600000785

accountHolder

string

required

Name of the account holderExample: "John Doe"

bic

string

BIC/SWIFT code (optional for SEPA)Example: "NDEAFIHH"

amount

object

required

Withdrawal amount

Show amount properties

value

string

required

Amount in minor units (cents)Example: "500000" = 5,000.00 EUR

currency

string

required

ISO 4217 currency codeExample: EUR

scale

integer

required

Decimal places (typically 2 for EUR)

description

string

Withdrawal description/referenceExample: "E2E Test - Withdrawal to personal account"

reference

string

Transaction referenceExample: "WD-TEST-1736777400000"

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/wallet_abc123/types/withdraw/prepare" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccount": {
      "walletId": "wallet_abc123"
    },
    "targetAccount": {
      "iban": "FI2112345600000785",
      "accountHolder": "John Doe",
      "bic": "NDEAFIHH"
    },
    "amount": {
      "value": "500000",
      "currency": "EUR",
      "scale": 2
    },
    "description": "Withdrawal to personal account",
    "reference": "WD-2026-001"
  }'

Response

{
  "code": 200,
  "message": "Success",
  "data": {
    "preparedOrderId": "abc123-def456-ghi789",
    "summary": {
      "amount": {
        "value": "500000",
        "currency": "EUR",
        "scale": 2
      },
      "sourceAccount": "wallet_abc123",
      "targetAccount": "FI2112345600000785",
      "fees": {
        "value": "250",
        "currency": "EUR",
        "scale": 2
      }
    },
    "validUntil": "2026-01-13T10:25:00Z"
  }
}

Step 2: Execute Withdrawal

POST /api/v2.1/fintrans/{accountId}/types/withdraw/execute

Request Body

preparedOrderId

string

required

Prepared order ID from prepare step

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/wallet_abc123/types/withdraw/execute" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preparedOrderId": "abc123-def456-ghi789"
  }'

Purchase Operations

Process merchant payments by debiting from customer wallet. Used for goods/services purchases.

Step 1: Prepare Purchase

POST /api/v2.1/fintrans/{accountId}/types/purchase/prepare

Path Parameters

accountId

string

required

Customer wallet/account UUID

Request Body

sourceAccount

object

required

Source wallet details

Show sourceAccount properties

walletId

string

required

Wallet UUID to debit from

merchantDetails

object

required

Merchant information

Show merchantDetails properties

merchantId

string

required

Merchant identifierExample: "MERCHANT_TEST_001"

merchantName

string

required

Merchant display nameExample: "Test Merchant Ltd"

merchantCategory

string

required

Merchant category code (MCC)Valid Values: RETAIL, DINING, SERVICES, ENTERTAINMENT, OTHER

amount

object

required

Purchase amount

Show amount properties

value

string

required

Amount in minor unitsExample: "250000" = 2,500.00 EUR

currency

string

required

Currency code

scale

integer

required

Decimal places

description

string

Purchase descriptionExample: "E2E Test - Purchase transaction"

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/wallet_abc123/types/purchase/prepare" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAccount": {
      "walletId": "wallet_abc123"
    },
    "merchantDetails": {
      "merchantId": "MERCHANT_TEST_001",
      "merchantName": "Test Merchant Ltd",
      "merchantCategory": "RETAIL"
    },
    "amount": {
      "value": "250000",
      "currency": "EUR",
      "scale": 2
    },
    "description": "Purchase transaction - electronics"
  }'

Step 2: Execute Purchase

POST /api/v2.1/fintrans/{accountId}/types/purchase/execute

Same execution pattern as withdrawal - provide preparedOrderId.

Sale Operations

Process revenue receipts by crediting to merchant/seller wallet. Used for sales, invoices, and revenue recognition.

Step 1: Prepare Sale

POST /api/v2.1/fintrans/{accountId}/types/sale/prepare

Path Parameters

accountId

string

required

Merchant/seller wallet/account UUID

Request Body

targetAccount

object

required

Target wallet to credit

Show targetAccount properties

walletId

string

required

Wallet UUID to credit

customerDetails

object

required

Customer/payer information

Show customerDetails properties

customerId

string

required

Customer identifierExample: "CUSTOMER_TEST_001"

customerName

string

required

Customer display nameExample: "Test Customer"

customerEmail

string

Customer email addressExample: "[email protected]"

amount

object

required

Sale amount

Show amount properties

value

string

required

Amount in minor unitsExample: "750000" = 7,500.00 EUR

currency

string

required

Currency code

scale

integer

required

Decimal places

description

string

Sale descriptionExample: "E2E Test - Sale transaction (revenue receipt)"

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/fintrans/wallet_abc123/types/sale/prepare" \
  -H "X-Tenant-ID: tenant_cloudvault" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetAccount": {
      "walletId": "wallet_abc123"
    },
    "customerDetails": {
      "customerId": "CUSTOMER_TEST_001",
      "customerName": "Test Customer",
      "customerEmail": "[email protected]"
    },
    "amount": {
      "value": "750000",
      "currency": "EUR",
      "scale": 2
    },
    "description": "Sale transaction - consulting services"
  }'

Step 2: Execute Sale

POST /api/v2.1/fintrans/{accountId}/types/sale/execute

Same execution pattern - provide preparedOrderId.

Beneficiary Management

Manage saved beneficiaries for faster transfers.

Create Beneficiary

POST /api/v2.1/fintrans/{accountId}/beneficiaries

Request Body

{
  "name": "Regular Supplier Ltd",
  "accountNumber": "LT121000011101001000",
  "bic": "AGBLLT2X",
  "type": "BUSINESS",
  "currency": "EUR",
  "country": "LT",
  "isPrimary": false
}

Response

{
  "code": 200,
  "message": "Beneficiary created successfully",
  "data": {
    "beneficiaryId": "benef_abc123def456",
    "status": "ACTIVE",
    "createdAt": "2026-01-13T10:24:35.123Z"
  }
}

Amount Representation

All amounts must use the AmountDto structure with value as a string in minor units.

Examples

Display Amount	AmountDto Representation
€100.00	`{"value": "10000", "currency": "EUR", "scale": 2}`
€50,000.00	`{"value": "5000000", "currency": "EUR", "scale": 2}`
$1,234.56	`{"value": "123456", "currency": "USD", "scale": 2}`
¥5000	`{"value": "5000", "currency": "JPY", "scale": 0}`

Conversion Helper

// Convert decimal to AmountDto
function toAmountDto(amount, currency = 'EUR', scale = 2) {
  const value = String(Math.round(amount * Math.pow(10, scale)));
  return { value, currency, scale };
}

// Convert AmountDto to decimal
function fromAmountDto(amountDto) {
  return parseInt(amountDto.value) / Math.pow(10, amountDto.scale);
}

// Usage
const dto = toAmountDto(50000); // 50,000.00 EUR
// { value: "5000000", currency: "EUR", scale: 2 }

const amount = fromAmountDto(dto);
// 50000

Operation Limits

Limits are configured per account and can be queried via the allowed operations endpoint.

Typical Limits

Operation	Daily Limit	Single Transaction	Verification Required
Topup	€50,000	€10,000	TENANT_VERIFIED
Transfer (Internal)	€100,000	€25,000	TENANT_VERIFIED
Transfer (SEPA)	€25,000	€10,000	TENANT_VERIFIED
Withdrawal	€10,000	€5,000	FINHUB_VERIFIED

Error Handling

Common Error Codes

Code	Meaning	Action Required
400	Invalid request or expired prepared order	Retry prepare step
402	Insufficient funds	Request smaller amount
403	Forbidden (beneficiary creation)	Retry immediately
409	Duplicate transaction	Check if already processed
429	Rate limit exceeded	Wait and retry with backoff

Retry Strategy

const executeWithRetry = async (fn, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 403 && attempt < maxRetries) {
        await new Promise(resolve => setTimeout(resolve, 100 * attempt));
        continue;
      }
      throw error;
    }
  }
};

Testing

Sandbox Test Data

Use these test IBANs in sandbox environment:

IBAN	Purpose	Result
`FI2112345600000785`	Successful topup	Always succeeds
`FI2112345600000786`	Insufficient funds	Returns 402 error
`FI2112345600000787`	Slow processing	Simulates 30s delay

Transfers API

Three-step transfer workflow

Common Types

AmountDto and other data structures

Verification

Required verifications for operations

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Account Operations API

​Operation Types

​Topup Workflow

​Step 1: Prepare Topup

​Endpoint

​Path Parameters

​Headers

​Request Body

​Code Examples

​Response

​Step 2: Execute Topup

​Endpoint

​Path Parameters

​Request Body

​Code Examples

​Response

​Transfer Workflow

​Prepare Transfer

​Request Body Structure

​Execute Transfer

​Withdrawal Workflow

​Step 1: Prepare Withdrawal

​Path Parameters

​Request Body

​Code Examples

​Response

​Step 2: Execute Withdrawal

​Request Body

​Code Examples

​Purchase Operations

​Step 1: Prepare Purchase

​Path Parameters

​Request Body

​Code Examples

​Step 2: Execute Purchase

​Sale Operations

​Step 1: Prepare Sale

​Path Parameters

​Request Body

​Code Examples

​Step 2: Execute Sale

​Beneficiary Management

​Create Beneficiary

​Request Body

​Response

​Amount Representation

​Examples

​Conversion Helper

​Operation Limits

​Typical Limits

​Error Handling

​Common Error Codes

​Retry Strategy

​Testing

​Sandbox Test Data

​Related Endpoints

Transfers API

Common Types

Verification

Account Operations API

Operation Types

Topup Workflow

Step 1: Prepare Topup

Endpoint

Path Parameters

Headers

Request Body

Code Examples

Response

Step 2: Execute Topup

Endpoint

Path Parameters

Request Body

Code Examples

Response

Transfer Workflow

Prepare Transfer

Request Body Structure

Execute Transfer

Withdrawal Workflow

Step 1: Prepare Withdrawal

Path Parameters

Request Body

Code Examples

Response

Step 2: Execute Withdrawal

Request Body

Code Examples

Purchase Operations

Step 1: Prepare Purchase

Path Parameters

Request Body

Code Examples

Step 2: Execute Purchase

Sale Operations

Step 1: Prepare Sale

Path Parameters

Request Body

Code Examples

Step 2: Execute Sale

Beneficiary Management

Create Beneficiary

Request Body

Response

Amount Representation

Examples

Conversion Helper

Operation Limits

Typical Limits

Error Handling

Common Error Codes

Retry Strategy

Testing

Sandbox Test Data

Related Endpoints