FinHub
Open Developer Portal

Phase 8: Transaction Operations

Fund wallet, execute transfers, and manage high-value transactions

Phase 8: Transaction Operations

The final phase covers transaction operations: funding the wallet, preparing transfers, executing payments, and handling high-value transactions with document requirements.

Transaction Flow

flowchart LR
    A[Fund Wallet] --> B[Prepare Transfer]
    B --> C{High Value?}
    C -->|Yes| D[Upload Documents]
    C -->|No| E[Execute Transfer]
    D --> E
    E --> F[Monitor Status]

Step 1: Fund Wallet (Topup)

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

Request Body:

json
{
  "sourceAccount": {
    "iban": "FR7612345678901234567890123",
    "accountHolder": "Acme Corporation Limited",
    "bic": "BNPAFRPP"
  },
  "targetAccount": {
    "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440120",
    "iban": "FR7630001007941234567890186"
  },
  "amount": {
    "value": "5000000",
    "currency": "EUR"
  },
  "description": "Initial wallet funding",
  "reference": "FUND-2026-001"
}

Status: 200 OK

json
{
  "code": 200,
  "message": "Topup order prepared successfully",
  "data": {
    "preparedOrderId": "prep-4455e8400-e29b-41d4-a716-446655440210",
    "operationType": "TOPUP",
    "status": "PREPARED",
    "amount": {
      "value": "5000000",
      "valueFormatted": "50000.00",
      "currency": "EUR"
    },
    "fees": {
      "value": "0",
      "valueFormatted": "0.00",
      "currency": "EUR"
    },
    "totalAmount": {
      "value": "5000000",
      "valueFormatted": "50000.00",
      "currency": "EUR"
    },
    "estimatedExecutionTime": "2026-01-15T17:00:00.000Z",
    "validUntil": "2026-01-15T20:00:00.000Z"
  }
}

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

Request Body:

json
{
  "preparedOrderId": "prep-4455e8400-e29b-41d4-a716-446655440210",
  "consentConfirmation": {
    "confirmed": true,
    "confirmationMethod": "EXPLICIT"
  }
}

Status: 200 OK

json
{
  "code": 200,
  "message": "Topup executed successfully",
  "data": {
    "executionId": "exec-5566e8400-e29b-41d4-a716-446655440220",
    "orderId": "order-6677e8400-e29b-41d4-a716-446655440221",
    "status": "EXECUTING",
    "estimatedCompletionTime": "2026-01-15T17:00:00.000Z"
  }
}

Step 2: High-Value Transfer with Documents

For transactions ≥ €10,000, supporting documents may be required.

Upload Payment Document

Endpoint: POST /api/v2.1/fintrans/{walletId}/payment-documents

Content-Type: multipart/form-data

Form Data:

documentType: INVOICE
file: [invoice_INV-2026-001.pdf]
transactionReference: INV-2026-001
amount: 15000.00
currency: EUR
beneficiaryName: Supplier Corporation Ltd
description: Invoice payment for software licenses

Status: 201 Created

json
{
  "code": 201,
  "message": "Payment document uploaded successfully",
  "data": {
    "documentId": "doc-7788e8400-e29b-41d4-a716-446655440230",
    "transactionReference": "INV-2026-001",
    "status": "VERIFIED"
  }
}

Payment Document Types

Document TypeDescription
INVOICESupplier invoice
CONTRACTService contract
PURCHASE_ORDERPurchase order
PROFORMAProforma invoice
TAX_DOCUMENTTax-related document

Step 3: Prepare Business Transfer

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

Request Body:

json
{
  "sourceAccount": {
    "walletId": "wallet-aa0e8400-e29b-41d4-a716-446655440120",
    "iban": "FR7630001007941234567890186"
  },
  "targetAccount": {
    "iban": "GB82WEST12345698765432",
    "beneficiaryName": "Supplier Corporation Ltd",
    "bic": "WESTGB21"
  },
  "amount": {
    "value": "1500000",
    "currency": "EUR"
  },
  "description": "Invoice payment #INV-2026-001",
  "reference": "INV-2026-001",
  "paymentConsentId": "consent-3344e8400-e29b-41d4-a716-446655440200",
  "supportingDocuments": [
    "doc-7788e8400-e29b-41d4-a716-446655440230"
  ],
  "metadata": {
    "invoiceNumber": "INV-2026-001",
    "invoiceDate": "2026-01-10",
    "purchaseOrderNumber": "PO-2026-001",
    "contractReference": "CNT-2024-001"
  }
}

Status: 200 OK

json
{
  "code": 200,
  "message": "Order prepared successfully",
  "data": {
    "preparedOrderId": "prep-8899e8400-e29b-41d4-a716-446655440240",
    "operationType": "TRANSFER",
    "status": "PREPARED",
    "amount": {
      "value": "1500000",
      "valueFormatted": "15000.00",
      "currency": "EUR"
    },
    "fees": {
      "value": "150",
      "valueFormatted": "1.50",
      "currency": "EUR"
    },
    "totalAmount": {
      "value": "1500150",
      "valueFormatted": "15001.50",
      "currency": "EUR"
    },
    "validUntil": "2026-01-15T20:00:00.000Z",
    "warnings": [],
    "requiredApprovals": [
      {
        "reason": "Amount exceeds approval threshold",
        "threshold": "5000000",
        "requiredRoles": ["TRANSACTION_APPROVER", "ADMIN_USER"]
      }
    ]
  }
}

Step 4: Execute Transfer

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

Request Body:

json
{
  "preparedOrderId": "prep-8899e8400-e29b-41d4-a716-446655440240",
  "consentConfirmation": {
    "confirmed": true,
    "confirmationMethod": "EXPLICIT",
    "confirmationTimestamp": "2026-01-15T16:00:00.000Z"
  }
}

Status: 200 OK

json
{
  "code": 200,
  "message": "Order executed successfully",
  "data": {
    "executionId": "exec-9900e8400-e29b-41d4-a716-446655440250",
    "orderId": "order-0011e8400-e29b-41d4-a716-446655440251",
    "preparedOrderId": "prep-8899e8400-e29b-41d4-a716-446655440240",
    "status": "EXECUTING",
    "executionTimestamp": "2026-01-15T16:00:30.000Z",
    "estimatedCompletionTime": "2026-01-15T17:00:00.000Z",
    "transactionReference": "TXN-20260115-001",
    "confirmationNumber": "CNF-20260115-001"
  }
}

Order Status Flow

flowchart LR
    A[PREPARED] --> B{Approval Required?}
    B -->|No| C[EXECUTING]
    B -->|Yes| D[PENDING_APPROVAL]
    D --> E{Approved?}
    E -->|Yes| C
    E -->|No| F[REJECTED]
    C --> G{Outcome}
    G -->|Success| H[COMPLETED]
    G -->|Failure| I[FAILED]

Get Order Status

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

json
{
  "code": 200,
  "message": "Order retrieved successfully",
  "data": {
    "orderId": "order-0011e8400-e29b-41d4-a716-446655440251",
    "operationType": "TRANSFER",
    "status": "COMPLETED",
    "amount": "1500000",
    "amountFormatted": "15000.00",
    "currency": "EUR",
    "fees": "150",
    "feesFormatted": "1.50",
    "beneficiaryName": "Supplier Corporation Ltd",
    "beneficiaryIban": "GB82WEST12345698765432",
    "reference": "INV-2026-001",
    "transactionReference": "TXN-20260115-001",
    "createdAt": "2026-01-15T16:00:00.000Z",
    "executedAt": "2026-01-15T16:00:30.000Z",
    "completedAt": "2026-01-15T16:05:00.000Z"
  }
}

Fee Structure

Transaction TypeFee
SEPA Transfer€1.50
SWIFT Transfer€15.00
Topup (Incoming)Free
Internal TransferFree
Bulk Payment (per item)€0.50

Complete B2B Flow Summary

┌─────────────────────────────────────────────────────────────┐
│ ORGANIZATION CUSTOMER COMPLETE LIFECYCLE                     │
└─────────────────────────────────────────────────────────────┘

Phase 1: Registration (10 min)
  └─→ Organization + Default Admin created

Phase 2: Personnel (20 min)
  └─→ Directors, Shareholders, Employees added

Phase 3: Verification (2-5 days)
  └─→ KYB documents submitted and approved

Phase 4: Consents (10 min)
  └─→ Organization consents with authorized signatory

Phase 5: Activation (instant)
  └─→ Role validation, IBAN generated, wallet activated

Phase 6: Beneficiaries (ongoing)
  └─→ Business beneficiaries with due diligence

Phase 7: Payment Consent (5 min)
  └─→ Consent with limits and restrictions

Phase 8: Transactions (ongoing)
  └─→ Topup, transfers, payments with documents
Error Handling

Common errors and troubleshooting

Best Practices

Implementation best practices

Type to search…

↑↓ navigate ↵ open esc close