Overview

The Transactions API allows you to retrieve and analyze the financial movements affecting your accounts. Transactions represent the individual ledger entries that occur when money moves into, out of, or between accounts. Unlike Transfers, Deposits, or Conversions (which represent higher-level operations), Transactions give you visibility into the specific ledger movements these operations cause.

Key features of the Transactions API:

• View detailed transaction history for all accounts
• Filter transactions by multiple criteria
• Get transaction-level balance change information
• Link transactions to their originating operations (transfers, deposits, conversions)
• Support for both credit (money in) and debit (money out) transaction types

The Transaction Object

Understanding Transactions

Key Concepts: Transaction Completion vs. Entity Settlement

When working with our banking API, it's essential to understand the distinction between transaction completion and entity settlement:

Transaction Completion

A transaction object in a "COMPLETED" state indicates that the ledger entry has been finalized and the account balance has been affected. This means:

• The funds have been debited from or credited to the available balance
• The transaction has been recorded in the ledger
• The balance change is reflected in the account

Entity Settlement

The settlement status of the related entity (transfer, deposit, conversion) is separate from the transaction's completion status:

• A completed transaction shows the balance has been affected
• This does not necessarily mean the related operation (transfer, deposit, conversion) has been fully settled
• The related entity might still be in process with external systems or banking partners

Important Clarification

For Accounts:

When you see a "COMPLETED" transaction in your transaction history, this means:

• ✅ Your balance has been updated
• ✅ The transaction has been recorded in your account
• ❌ This does NOT guarantee funds have reached their final destination (for outbound transfers)
• ❌ This does NOT guarantee that conversions have settled on the quote side

For Developers:

When implementing with our API:

• Use transaction data to show accurate balance changes if needed
• To determine if a transfer has been fully settled, check the state of the transfer entity itself via the Transfers API
• To determine if a conversion has been fully settled, check the state of the conversion entity via the Conversions API
• To track the complete lifecycle, use both transaction data and the related entity's data

Example Scenarios

Transfer to an External Bank

1. You initiate a transfer to an external bank account
2. A "COMPLETED" transaction immediately shows in your account
3. Your available balance is reduced
4. The actual settlement to the recipient bank would typically take some time
5. During this time, the transfer entity would typically show "PROCESSING" state
6. Once settled with the recipient bank, the transfer entity would show "COMPLETED" state

Currency Conversion Process (USD to EUR):

1. You initiate a currency conversion from USD to EUR
2. The process unfolds in these distinct stages:

Initial Stage (Immediate)

• USD transaction shows as "COMPLETED" with action "conversion_out"
• USD available balance is reduced immediately
• EUR transaction appears as "PENDING" with action "conversion_in"
• EUR balance is not yet increased
• Conversion entity shows state "PROCESSING"

Completion Stage (After Processing)

• USD transaction remains "COMPLETED" (no change)
• EUR transaction updates to "COMPLETED"
• EUR available balance is increased with the converted amount
• Conversion entity updates to "COMPLETED" state

Transaction States During Conversion

Balance Effects

Entity States

Checking Settlement Status

To determine if a related entity is fully settled:

1. Get the related_entity.id from the transaction
2. Use this ID to query the appropriate endpoint based on the related_entity.type:
   • /v2/transfers/{id} for transfers
   • /v2/deposits/{id} for deposits
   • /v2/conversions/{id} for conversions
3. Check the state field of the returned entity to determine its settlement status

Field Reference for Transaction vs. Settlement Status

Remember: Transaction completion (impact on balance) and entity settlement (completion of the full operation) are distinct concepts in our banking system.

Endpoints

List Transactions

Retrieve a paginated list of transactions for your institution.

GET /v2/transactions

Query Parameters

Example Request

curl -X GET "https://api.sandbox.waza.co/lync/banking/v2/transactions?account_id=abcdef12-3456-7890-abcd-ef1234567890&type=credit" \
  -H "x-waza-api-key: your_api_key_here"

Example Response

{
  "data": {
    "items": [
      {
        "id": "abcdef12-3456-7890-abcd-ef1234567890",
        "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
        "state": "COMPLETED",
        "created_date": "2023-05-14T10:30:45Z",
        "completion_date": "2023-05-14T10:35:22Z",
        "amount": {
          "value": 100000,
          "currency": "USD"
        },
        "type": "credit",
        "related_entity": {
          "type": "deposit",
          "id": "12345678-1234-1234-1234-123456789012"
        },
        "balance_before": {
          "value": 500000,
          "currency": "USD"
        },
        "balance_after": {
          "value": 600000,
          "currency": "USD"
        },
        "action": "inbound_funds"
      }
    ],
    "page": 1,
    "limit": 20,
    "totalItems": 1
  }
}

Get Transaction by ID

Retrieve details for a specific transaction.

GET /v2/transactions/{id}

Path Parameters

Example Request

curl -X GET "https://api.sandbox.waza.co/lync/banking/v2/transactions/abcdef12-3456-7890-abcd-ef1234567890" \
  -H "x-waza-api-key: your_api_key_here"

Example Response

{
  "data": {
    "id": "abcdef12-3456-7890-abcd-ef1234567890",
    "account_id": "fedcba98-7654-3210-fedc-ba9876543210",
    "state": "COMPLETED",
    "created_date": "2023-05-14T10:30:45Z",
    "completion_date": "2023-05-14T10:35:22Z",
    "amount": {
      "value": 100000,
      "currency": "USD"
    },
    "type": "credit",
    "related_entity": {
      "type": "deposit",
      "id": "12345678-1234-1234-1234-123456789012"
    },
    "balance_before": {
      "value": 500000,
      "currency": "USD"
    },
    "balance_after": {
      "value": 600000,
      "currency": "USD"
    },
    "action": "inbound_funds"
  }
}

Transaction Actions

The Transaction API uses the action field to indicate the specific type of financial activity:

Related Entities

Transactions are connected to higher-level operations through the related_entity field. This allows you to:

1. Find all transactions related to a specific transfer, deposit, or conversion
2. Understand how higher-level operations affect individual account balances
3. Track the complete lifecycle of funds as they move through your accounts