> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Balance Ledger

> Retrieve a business's balance ledger — every credit and debit on the business's balance, including funding deposits and outgoing payments, with the direction and balance effect of each entry. Use this endpoint to reconcile balance movements against your own books.

For full disbursement records of each movement — payment method, FX rate, and fee breakdown — use [Platform Disbursements](/api-reference/workforce/platform/list-disbursements) filtered by `businessId` instead.




## OpenAPI

````yaml /openapi/workforce-management.yaml get /v1/businesses/{businessId}/transactions
openapi: 3.0.0
info:
  description: APIs for interacting with Cadana Payroll Platform
  version: 1.0.0
  title: Business Workforce Management
  termsOfService: https://cadanapay.com/terms-and-conditions
  contact:
    email: api@cadanapay.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://api.cadanapay.com
    description: Prod Server
  - url: https://dev-api.cadanapay.com
    description: Dev Server
security:
  - Authorization: []
tags:
  - name: Custom Auth
    description: APIs for interacting with Custom Authentication
  - name: Persons
    description: APIs for interacting with the HR module
  - name: Milestones
    description: APIs for milestone-based contractor pay
  - name: Instant Pay
    description: APIs for interacting with Instant Pay functionality
  - name: Users
    description: APIs for interacting with employee/contractor Cadana accounts
  - name: Files
    description: APIs for interacting with file uploads
  - name: Payrolls
    description: APIs for interacting with Payroll
  - name: Platform
    description: Platform APIs for interacting with businesses
  - name: Businesses
    description: APIs for interacting with Business
  - name: Treasury
    description: APIs for business balances, funding, and withdrawals
  - name: KYB
    description: APIs for business verification
  - name: Contracts
    description: APIs for interacting with contracts
  - name: Sandbox
    description: APIs for relevant sandbox simulations
  - name: Invoices
    description: APIs for interacting with invoices
  - name: Reimbursements
    description: APIs for interacting with reimbursements
  - name: Entities
    description: >-
      APIs for managing legal sub-entities (subsidiaries, branches) under a
      parent business
paths:
  /v1/businesses/{businessId}/transactions:
    get:
      tags:
        - Treasury
      summary: Get Balance Ledger
      description: >
        Retrieve a business's balance ledger — every credit and debit on the
        business's balance, including funding deposits and outgoing payments,
        with the direction and balance effect of each entry. Use this endpoint
        to reconcile balance movements against your own books.


        For full disbursement records of each movement — payment method, FX
        rate, and fee breakdown — use [Platform
        Disbursements](/api-reference/workforce/platform/list-disbursements)
        filtered by `businessId` instead.
      operationId: getBusinessTransactions
      parameters:
        - $ref: '#/components/parameters/businessId'
        - name: currency
          in: query
          description: Currency code for transactions (required)
          required: true
          schema:
            type: string
            example: USD
        - name: startDate
          in: query
          description: Start date for transactions filter (required)
          required: true
          schema:
            type: string
            format: date
            example: '2024-01-01'
        - $ref: '#/components/parameters/XMultiTenantKey'
      responses:
        '200':
          $ref: '#/components/responses/GetBusinessTransactionsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        5XX:
          $ref: '#/components/responses/InternalError'
      security:
        - Authorization: []
components:
  parameters:
    businessId:
      name: businessId
      in: path
      description: The unique identifier for the business
      required: true
      schema:
        type: string
    XMultiTenantKey:
      name: X-MultiTenantKey
      in: header
      required: false
      schema:
        type: string
      description: >-
        Required when using a Platform API token. The tenant key identifying
        which business to operate on.
  responses:
    GetBusinessTransactionsResponse:
      description: List of business transactions
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/BusinessTransaction'
              node:
                $ref: '#/components/schemas/node'
    BadRequestError:
      description: Bad input provided by client
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    NotFoundError:
      description: Requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    InternalError:
      description: Internal error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalError'
  schemas:
    BusinessTransaction:
      type: object
      description: A business ledger transaction
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the transaction
        status:
          type: string
          description: Status of the transaction
          example: Completed
        vendorId:
          type: string
          description: ID of the vendor/recipient
        vendorName:
          type: string
          description: Name of the vendor/recipient
        reference:
          type: string
          description: Transaction reference
        direction:
          type: string
          enum:
            - DEBIT
            - CREDIT
          description: Direction of the transaction
        balanceEffect:
          type: string
          enum:
            - increase
            - decrease
          description: Effect on balance
        paymentDetails:
          $ref: '#/components/schemas/businessTransactionPaymentDetails'
        amount:
          $ref: '#/components/schemas/Amount'
        transactionFee:
          $ref: '#/components/schemas/Amount'
        totalAmount:
          $ref: '#/components/schemas/Amount'
        sourceAmount:
          $ref: '#/components/schemas/Amount'
        fxRate:
          type: number
          nullable: true
          description: FX rate if currency conversion was involved
        reason:
          type: string
          description: Reason for the transaction
        bulkPaymentReference:
          type: string
          description: Reference for bulk payments
        createdTimestamp:
          type: integer
          description: Unix timestamp when the transaction was created
        lastUpdatedTimestamp:
          type: integer
          description: Unix timestamp when the transaction was last updated
        date:
          type: string
          format: date
          description: Date of the transaction
    node:
      type: object
      description: Node pagination
      properties:
        previous:
          type: string
          nullable: true
        next:
          type: string
          nullable: true
    BadRequestError:
      description: Bad input provided by client
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            params:
              description: A map for meta data around the error that occurred
              type: object
      example:
        code: invalid_request_body
        message: The request body provided is not valid
        params:
          field: Value is invalid.
    NotFoundError:
      description: Not Found
      allOf:
        - $ref: '#/components/schemas/Error'
      example:
        code: resource_not_found
        message: Requested resource could not be found.
    InternalError:
      description: Internal server error
      allOf:
        - $ref: '#/components/schemas/Error'
      example:
        code: internal_error
        message: An unexpected error occurred. Please try again later.
    businessTransactionPaymentDetails:
      type: object
      description: >-
        Payment details for a business ledger transaction. Unlike a
        beneficiary's payment method, the `preferredMethod` here is a hybrid
        descriptor: it is either the underlying payment rail used, or a
        transaction-category label derived from the ledger entry type (for fees,
        payroll, statutory deposits, interest, etc.).
      required:
        - preferredMethod
      properties:
        preferredMethod:
          type: string
          enum:
            - bank
            - momo
            - swift
            - ach
            - wire
            - crypto
            - card
            - proxy
            - Transfer
            - Payment Fee
            - Payroll
            - Payroll Reversal
            - Subscription Fees
            - Statutory Deposit
            - Payroll Fees
            - Interest
          description: >-
            The payment rail or transaction category for this transaction.
            Wallet-to-wallet movements (including deposits and internal
            transfers) are always reported as `Transfer` rather than `wallet`.
            Ledger entries without an underlying payment rail use a category
            label: `Payment Fee`, `Payroll`, `Payroll Reversal`, `Subscription
            Fees`, `Statutory Deposit`, `Payroll Fees`, or `Interest`.
          example: Payroll
        momo:
          $ref: '#/components/schemas/momoDetails'
        bank:
          $ref: '#/components/schemas/bankDetails'
        swift:
          $ref: '#/components/schemas/swiftDetails'
        ach:
          $ref: '#/components/schemas/achDetails'
        wallet:
          $ref: '#/components/schemas/walletDetails'
        wire:
          $ref: '#/components/schemas/wireDetails'
    Amount:
      type: object
      required:
        - value
        - currency
      properties:
        value:
          type: string
          description: The value of the amount
          example: '10.00'
        currency:
          type: string
          description: The currency of the asset
          example: USD
    Error:
      type: object
      properties:
        code:
          description: A machine parsable error code
          type: string
          enum:
            - invalid_request_body
            - resource_not_found
            - forbidden
            - internal_error
        message:
          description: A human readable message describing the error
          type: string
    momoDetails:
      type: object
      properties:
        accountName:
          type: string
          description: The name associated with the mobile money account
          example: John Doe
        provider:
          type: string
          description: The name of the mobile money provider
          example: MTN
        providerCode:
          type: string
          description: The code identifying the mobile money provider
          example: MTN
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        currency:
          type: string
          description: The currency of the mobile money account
          example: GHS
    bankDetails:
      type: object
      properties:
        accountName:
          type: string
          description: The name on the bank account
          example: John Doe
        accountNumber:
          type: string
          description: The bank account number
          example: '1234567890'
        accountType:
          type: string
          description: The type of bank account (e.g., Checking, Savings)
          example: Checking
        ownerType:
          type: string
          description: The type of account owner
          enum:
            - Individual
            - Business
          example: Individual
        bankCode:
          type: string
          description: The bank identification code
          example: EXMPJPJT
        bankName:
          type: string
          description: The name of the bank
          example: Gotham City Bank
        branchName:
          type: string
          description: The name of the bank branch
          example: Downtown Branch
        sortCode:
          type: string
          description: The bank sort code (UK); carries the IFSC for India
          example: '401234'
        iban:
          type: string
          description: The International Bank Account Number
          example: GB00000000000000000000
        provider:
          type: string
          description: The platform providing this account (e.g., wise)
          example: wise
        currency:
          type: string
          description: The currency of the bank account
          example: USD
        beneficiaryId:
          $ref: '#/components/schemas/beneficiaryId'
        address:
          $ref: '#/components/schemas/address'
        phoneNumber:
          $ref: '#/components/schemas/phoneNumber'
        email:
          type: string
          format: email
          description: The email address of the account holder
          example: john.doe@example.com
    swiftDetails:
      type: object
      required:
        - currency
        - iban
        - accountName
        - accountNumber
        - bankName
        - swiftCode
        - address
      properties:
        currency:
          type: string
          description: The currency of the bank account
          example: EUR
        iban:
          type: string
          description: The International Bank Account Number
          example: DE00000000000000000000
        accountName:
          type: string
          description: The name on the bank account
          example: John Doe
        accountNumber:
          type: string
          description: The bank account number
          example: '1234567890'
        bankName:
          type: string
          description: The name of the bank
          example: Example Bank
        swiftCode:
          type: string
          description: The SWIFT/BIC code of the bank
          example: EXMPDEFF
        address:
          $ref: '#/components/schemas/address'
    achDetails:
      type: object
      properties:
        bankName:
          type: string
          description: The name of the bank
          example: Example Bank
        accountName:
          type: string
          description: The name on the bank account
          example: John Doe
        routingNumber:
          type: string
          description: The ACH routing number of the bank
          example: '000000000'
        accountNumber:
          type: string
          description: The bank account number
          example: '1234567890'
        accountType:
          type: string
          description: The type of bank account (Checking or Savings)
          example: Checking
        provider:
          type: string
          description: The platform providing this account (e.g., wise)
          example: wise
        address:
          $ref: '#/components/schemas/address'
    walletDetails:
      type: object
      properties:
        type:
          type: string
          description: The type of wallet account
          enum:
            - user
            - business
          example: user
        identifier:
          type: string
          description: The unique identifier for the wallet account
          example: 69a2a928-ed49-4e53-92ec-a72b4ee7eacc
        currency:
          type: string
          description: The currency of the wallet
          example: USD
    wireDetails:
      type: object
      description: Wire transfer payment details
      properties:
        bankName:
          type: string
          description: The name of the bank
          example: Example Bank
        accountName:
          type: string
          description: The name on the account
          example: John Doe
        routingNumber:
          type: string
          description: The routing number
          example: '000000000'
        accountNumber:
          type: string
          description: The account number
          example: '123456789'
        address:
          $ref: '#/components/schemas/address'
    phoneNumber:
      type: object
      description: Person's phone number
      properties:
        countryCode:
          type: string
          example: '1'
        number:
          type: string
          example: '2345678901'
    beneficiaryId:
      type: object
      description: ID details for the beneficiary
      properties:
        type:
          type: string
          enum:
            - NIT
            - CC
            - CE
            - TI
            - PASS
          description: Type of beneficiary ID
          example: NIT
        value:
          type: string
          description: ID number of the beneficiary
          example: '123456789'
    address:
      type: object
      description: Address
      required:
        - countryCode
      properties:
        line1:
          type: string
          example: Street 1
        line2:
          type: string
          example: Apt 1
        city:
          type: string
          example: Gotham
        postalCode:
          type: string
          example: '10001'
        state:
          type: string
          example: NY
        countryCode:
          type: string
          example: US
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: API_SECRET_KEY

````