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

Step 1: Fund Wallet (Topup)

Prepare Request
Prepare Response
Execute Request
Execute Response

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

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

{
  "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/executeRequest Body:

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

Status: 200 OK

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

Request
Response

Endpoint: POST /api/v2.1/fintrans/{walletId}/payment-documentsContent-Type: multipart/form-dataForm 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

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

Request
Response

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

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

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

Request
Response

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

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

Status: 200 OK

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

Get Order Status

Request
Response

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

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

Error Handling

Common errors and troubleshooting

Best Practices

Implementation best practices

​Phase 8: Transaction Operations

​Transaction Flow

​Step 1: Fund Wallet (Topup)

​Step 2: High-Value Transfer with Documents

​Upload Payment Document

​Payment Document Types

​Step 3: Prepare Business Transfer

​Step 4: Execute Transfer

​Order Status Flow

​Get Order Status

​Fee Structure

​Complete B2B Flow Summary

​Related Resources

Error Handling

Best Practices

Phase 8: Transaction Operations

Transaction Flow

Step 1: Fund Wallet (Topup)

Step 2: High-Value Transfer with Documents

Upload Payment Document

Payment Document Types

Step 3: Prepare Business Transfer

Step 4: Execute Transfer

Order Status Flow

Get Order Status

Fee Structure

Complete B2B Flow Summary

Related Resources