Description

Purpose and use

:::warning[Retired — no client runs on this module] This module is no longer used, by anyone. Every live money movement goes through the transfers module (modules/transfers, GET /v2/transfers), which owns the party model, the DSL product execution and the status history — and no client integration remains on these endpoints. They are not a supported path that some clients have yet to leave; they are kept so that records written before the move stay readable, and for nothing else.

They receive no fixes. A defect found here is closed as out of scope rather than patched, and that includes any correction to how a party is named or identified. Do not build against this surface, do not extend it, and do not point a client at it — anything new belongs in transfers. The Zahlex hand-off this module once carried was removed in September 2026; the live hand-off to the payment rail is the transfers product step described in Payment rail gateway. :::

The transactions manual covers the retired transaction workflows that prepared, approved, signed, monitored and completed customer money movements before the transfers module took them over. It is a reading guide for records left behind by those flows — drafts, final transactions, inward payments, status history and manual FX overrides — not a description of anything the bank runs today.

Who uses this. Payment operations, customer support and compliance reviewers, when they have to read a transaction recorded before the move to transfers. No client integration runs on these endpoints any more, so nothing here describes a live flow.

How it works. A transaction can begin as a draft, move through approval and signing, pass compliance checks, and then settle into posted ledger movements. Status history and journal-entry lookup provide the audit trail for each step.

What users do. Users create or update drafts, finalize a transaction, sign or cancel when allowed, review status changes, resolve exceptions, and trace the transaction into ledger entries.

Outcomes and side effects. Finalized transactions can create fees, FX conversions, compliance checks, notifications, and ledger postings. Canceled or failed transactions remain in history for audit and customer-service review.

Related manuals: Modern Transfers, Ledgers & Balance Management, KYT, FX.

Overview

The Transactions API provides comprehensive functionality for managing financial transactions:

• Draft and final transaction creation and management
• Multi-currency support with automatic conversion
• Fee and tax calculation
• Transaction signing and approval workflows
• Transaction status tracking and history
• Compliance validation with ComplyAdvantage
• Automated transaction processing
• Recurring transaction support
• Inward transfer (IWT) processing

Core Concepts

Transaction Types

• iwt: Inward transfer (from external to internal account)
• owt: Outward transfer (from internal to external account)
• int: Internal transfer (between different customers within the same institution)
• own: Own account transfer (between accounts of the same customer)

Transaction Statuses

• incomplete: Partially created transaction
• draft: Draft transaction being prepared
• waiting-for-signature: Awaiting digital signature
• pending: Ready for processing
• in-progress: Currently being processed
• completed: Successfully completed
• cancelled: Cancelled by user
• failed: Failed to process
• suspended: Temporarily suspended (e.g., compliance review)

Account Types

• recipient: External recipient
• account: Internal account
• sender: External sender (for inward transfers)

Endpoints

Draft Transaction Management

Create Draft Transaction

POST /v1/customers/{customer_id}/transaction/draft

Create a draft transaction that can be modified before final submission.

Update Draft Transaction

PUT /v1/customers/{customer_id}/transaction/{transaction_id}/draft

Update an existing draft transaction.

Delete Draft Transaction

DELETE /v1/transaction/{transaction_id}

Delete a draft transaction.

Transaction Creation

Create Fast Transaction

POST /v1/customers/{customer_id}/transaction

Create and immediately submit a transaction for processing.

Request Body:

{
  "sender": {
    "account": {
      "id": "uuid"
    }
  },
  "recipient": {
    "type": "recipient",
    "recipient": {
      "id": "uuid"
    }
  },
  "original_amount": {
    "currency": "EUR",
    "amount": 100.00
  },
  "channel": "api",
  "description": "Payment for services",
  "is_recurring": false,
  "recurring_period": "1m"
}

Response:

{
  "id": "uuid",
  "sender": {
    "name": "John Doe Company",
    "iban": "CH1234567890123456789",
    "amount": {
      "currency": "CHF",
      "amount": 105.50
    },
    "fee": {
      "currency": "CHF", 
      "amount": 2.50
    }
  },
  "recipient": {
    "name": "Acme Corp",
    "iban": "DE89370400440532013000",
    "amount": {
      "currency": "EUR",
      "amount": 100.00
    },
    "fee": {
      "currency": "EUR",
      "amount": 1.00
    }
  },
  "amount": {
    "currency": "EUR",
    "amount": 100.00
  },
  "status": "waiting-for-signature",
  "channel": "api",
  "task_id": "uuid",
  "type": "owt",
  "direction": "outgoing",
  "value_date": "2024-03-21T10:00:00Z",
  "created_at": "2024-03-21T10:00:00Z",
  "modified_at": "2024-03-21T10:00:00Z"
}

Create Final Transaction

PUT /v1/customers/{customer_id}/transaction/{transaction_id}/final

Convert a draft transaction to final status for processing.

Create Inward Transaction

POST /v1/transactions/iwt

Process an inward transfer from external source.

Request Body:

{
  "sender": {
    "name": "External Bank",
    "iban": "GB29NWBK60161331926819",
    "bic": "NWBKGB2L",
    "country": "GB"
  },
  "recipient": {
    "iban": "CH1234567890123456789",
    "bic": "CHASUS33", 
    "bank": "Swiss Bank",
    "country": "CH"
  },
  "amount": 1000.00,
  "currency": "EUR",
  "channel": "swift",
  "description": "Invoice payment",
  "value_date": "2024-03-21T10:00:00Z"
}

Transaction Actions

Sign Transaction

POST /v1/transaction/{transaction_id}/sign

Digitally sign a transaction to authorize processing.

Cancel Transaction

PATCH /v1/transaction/{transaction_id}/cancel

Cancel a transaction that is waiting for signature.

Resolve Transaction

PATCH /v1/transactions/{transaction_id}/resolve

Resolve a suspended transaction (e.g., after compliance review).

Set Manual FX Rate

PATCH /v2/transactions/{transaction_id}/fx-rate

Override the automatically calculated FX rate for a draft, pending, or waiting-for-signature transaction. The override is stored on the participant metadata, short-circuits automatic conversion, and zeroes the conversion fee so downstream calculations stay consistent.

Request Body:

{
  "fx_rate": 1.0523,
  "reason": "Manual rate entry by operator"
}

Behavior Notes:

• Allowed statuses: draft, pending, waiting-for-signature
• reason is optional but recommended for audit history
• Response returns the sanitized CustomerTransactionAPI payload reflecting the updated amounts

Transaction Queries

Get Transactions

GET /v1/transactions

List transactions with optional filtering and pagination.

Query Parameters:

• status: Filter by transaction status
• type: Filter by transaction type
• customer_id.eq: Filter by customer ID
• sender__account__id.eq: Filter by sender account
• limit: Number of results per page
• offset: Pagination offset
• sort: Sort order (e.g., -created_at)
• stack: Group results by field (e.g., created_at[YYYY-MM])

Get Transfers

GET /v1/transfers

List transfers with filtering, sorting, and pagination support. Uses RBAC-aware query system with JSON-based search and sort parameters.

Query Parameters:

• search.status: Filter by transfer status (e.g., pending, draft, completed, failed, cancelled)
• search.type: Filter by transfer type (e.g., crypto_deposit, crypto_withdrawal, sepa, internal, wire)
• search.ori_customer_id: Filter by originator customer ID (UUID)
• search.ben_customer_id: Filter by beneficiary customer ID (UUID)
• search.customer_id: Deprecated - use search.ori_customer_id instead. Filter by originator customer ID (UUID)
• search.product_id: Filter by product ID (UUID)
• search.product_code: Filter by product code (e.g., CRD)
• search.txn_ccy: Filter by currency code (e.g., EUR, USD, USDC)
• sort: Sort field (prefix with - for descending). Example: -created_at or created_at
• limit: Number of items per page (default: 20, max: 100)
• offset: Starting position for pagination (default: 0)

Example Request:

GET {{base_url}}/v1/transfers?limit=20&offset=0&search.status=pending&sort=-created_at

Response:

{
  "data": [
    {
      "id": "uuid",
      "product_id": "uuid",
      "product_code": "CRD",
      "ori_customer_id": "uuid",
      "ben_customer_id": "uuid",
      "ori_account_id": "uuid",
      "ben_account_id": "uuid",
      "type": "crypto_deposit",
      "status": "pending",
      "txn_amt": "1000.00",
      "txn_ccy": "USDC",
      "txn_paymentPurpose": "Crypto deposit from external wallet",
      "ori_name": "John Doe",
      "ori_iban": "CH9300762011623852957",
      "ori_bic": "UBSWCHZH80A",
      "ben_name": "Beneficiary Name",
      "ben_iban": "",
      "ben_bic": "",
      "ori_walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
      "ben_walletAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
      "bc_network": "ERC20",
      "token": "USDC",
      "bc_txHash": "",
      "txn_netAmt": "99.50",
      "txn_feeAmt": "0.50",
      "direction": "inbound",
      "created_at": "2024-03-21T10:00:00Z",
      "updated_at": "2024-03-21T10:00:00Z"
    }
  ],
  "total": 1,
  "total_unfiltered": 1,
  "has_more": false
}

Get Transaction

GET /v1/customers/{customer_id}/transactions/{transaction_id}

Get detailed transaction information.

Get Transaction Status History

GET /v1/customers/{customer_id}/transactions/{transaction_id}/status-history

Get the complete status change history for a transaction.

Response:

{
  "data": [
    {
      "id": "uuid",
      "status": "draft",
      "date": "2024-03-21T09:00:00Z"
    },
    {
      "id": "uuid", 
      "status": "waiting-for-signature",
      "date": "2024-03-21T09:30:00Z"
    },
    {
      "id": "uuid",
      "status": "pending", 
      "date": "2024-03-21T10:00:00Z"
    }
  ],
  "total": 3,
  "has_more": false
}

Get Journal Entries by Transaction ID

GET /v1/ledgers/entries

Query journal entries (ledger entries) for a specific transaction. Use this endpoint to view all journal entries associated with a transaction ID.

Query Parameters:

• transaction_id.eq: Filter by transaction ID (UUID) - Use this to search for entries by transaction ID
• ledger_id.eq: Filter by ledger ID
• ledger_code.eq: Filter by ledger code
• type.eq: Filter by entry type (debit or credit)
• event.eq: Filter by event name
• limit: Number of results per page (default: 50, max: 100)
• offset: Pagination offset
• sort: Sort order (e.g., -created_at, amount)

Example Request:

GET /v1/ledgers/entries?transaction_id.eq=550e8400-e29b-41d4-a716-446655440000

Response:

{
  "data": [
    {
      "id": "uuid",
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "ledger_id": "uuid",
      "ledger_code": "4022",
      "amount": 1000000,
      "type": "debit",
      "currency_code": "CHF",
      "event": "before-kyt",
      "description": "Suspense Crypto (ERC USDC)",
      "value_date": "2024-03-21T10:00:00Z",
      "created_at": "2024-03-21T10:00:01Z"
    },
    {
      "id": "uuid",
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "ledger_id": "uuid",
      "ledger_code": "20212",
      "amount": 1000000,
      "type": "credit",
      "currency_code": "CHF",
      "event": "before-kyt",
      "description": "Customer Crypto Deposits (ERC USDC)",
      "value_date": "2024-03-21T10:00:00Z",
      "created_at": "2024-03-21T10:00:01Z"
    }
  ],
  "total": 2,
  "has_more": false
}

Usage: To view all journal entries for a specific transaction, use the search parameter transaction_id.eq with the transaction UUID. This is useful for:

• Auditing transaction entries
• Verifying journal entry balances
• Reviewing all ledger movements for a transaction
• Debugging transaction processing

Special Features

Currency Conversion

The system automatically handles currency conversion between sender and recipient currencies using real-time exchange rates and customer-specific tariffs.

Recurring Transactions

Transactions can be set as recurring with patterns:

• 1d, 2d, etc. - Daily recurring
• 1w, 2w, etc. - Weekly recurring
• 1m, 2m, etc. - Monthly recurring

Fee Calculation

Transaction fees are automatically calculated based on:

• Customer tariff settings
• Transaction amount and currency
• Channel used (API, web, mobile)
• Transaction type

Compliance Integration

All transactions are automatically validated against:

• ComplyAdvantage sanctions screening
• Customer risk levels
• Transaction limits and patterns
• KYT (Know Your Transaction) requirements

Error Codes

Transaction Errors

This table lists the most common user-facing errors. A full multilingual set is defined in config/samples/transactions_m.