> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```mermaid theme={null}
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 theme={null}
{
"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 theme={null}
{
"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 theme={null}
{
"preparedOrderId": "prep-4455e8400-e29b-41d4-a716-446655440210",
"consentConfirmation": {
"confirmed": true,
"confirmationMethod": "EXPLICIT"
}
}
```
**Status:** `200 OK`
```json theme={null}
{
"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 theme={null}
{
"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 Type | Description |
| ---------------- | -------------------- |
| `INVOICE` | Supplier invoice |
| `CONTRACT` | Service contract |
| `PURCHASE_ORDER` | Purchase order |
| `PROFORMA` | Proforma invoice |
| `TAX_DOCUMENT` | Tax-related document |
***
## Step 3: Prepare Business Transfer
**Endpoint:** `POST /api/v2.1/fintrans/{accountId}/types/transfer/prepare`
**Request Body:**
```json theme={null}
{
"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 theme={null}
{
"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 theme={null}
{
"preparedOrderId": "prep-8899e8400-e29b-41d4-a716-446655440240",
"consentConfirmation": {
"confirmed": true,
"confirmationMethod": "EXPLICIT",
"confirmationTimestamp": "2026-01-15T16:00:00.000Z"
}
}
```
**Status:** `200 OK`
```json theme={null}
{
"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
```mermaid theme={null}
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 theme={null}
{
"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 Type | Fee |
| ----------------------- | ------ |
| SEPA Transfer | €1.50 |
| SWIFT Transfer | €15.00 |
| Topup (Incoming) | Free |
| Internal Transfer | Free |
| 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
```
***
## Related Resources
Common errors and troubleshooting
Implementation best practices