--- title: "Search transactions" method: GET path: "/pty/account/v1/transactions" tags: ["Ledger API - Transactions"] --- # Search transactions `GET /pty/account/v1/transactions` ## Request - Base URL: `https://api.uat.paymentology.com` - URL: `https://api.uat.paymentology.com/pty/account/v1/transactions` - Auth: HTTP bearer ## Query parameters - `account_id` string - `token` string - `type` SearchTransactionType[] - `transaction_reference` string - `transaction_description` string - `currency` string - `min_amount` string - `max_amount` string - `updated_from` string, date-time - `updated_to` string, date-time - `merchant` string - `sort_by` 'UPDATED_AT' | 'AMOUNT': Field to sort transaction search results by. `UPDATED_AT` sorts by the transaction creation time. - `sort_order` 'ASC' | 'DESC': Sort direction. - `limit` integer - `cursor` string ## Response `200` Successful Response - TransactionSearchResponse - `filters` TransactionSearchFilters, required: Echo of the filters applied to the search request. Exactly one of account_id or token is present. - `account_id` string: Account ID filter applied. - `token` string: Token filter applied. - `type` SearchTransactionType[]: Transaction types filter applied. - `transaction_reference` string: Transaction reference filter applied. - `transaction_description` string: Transaction description filter applied. - `currency` string: Currency filter applied (ISO 4217). - `min_amount` string: Minimum amount filter applied (minor units, inclusive). - `max_amount` string: Maximum amount filter applied (minor units, inclusive). - `updated_from` string, date-time: Start (inclusive) of the creation-time filter applied. - `updated_to` string, date-time: End (exclusive) of the creation-time filter applied. - `merchant` string: Merchant name filter applied (partial match). - `sort_by` 'UPDATED_AT' | 'AMOUNT': Field to sort transaction search results by. `UPDATED_AT` sorts by the transaction creation time. - `sort_order` 'ASC' | 'DESC': Sort direction. - `limit` integer: Page size applied. - `items` TransactionSearchItem[], required - `id` string, uuid, required: Unique transaction identifier (UUID). - `type` string, required: Transaction type. May include values outside the SearchTransactionType filter enum. - `status` 'COMPLETED' | 'REJECTED', required: Outcome of the transaction. - `COMPLETED` — balances were applied. - `REJECTED` — the transaction was recorded but no balance changed (for example, insufficient funds). The reason is carried in `rejection_reason`. - `rejection_reason` RejectionReason, nullable: Populated only when `status = REJECTED`. Carries a machine-readable code and a human-readable message. - `code` string, required: Machine-readable rejection code. - `message` string, required: Human-readable rejection message. - `amount` TransactionAmount, required - `amount` string, required: Amount in minor units. Must be greater than 0 (e.g., 2000 = 20.00 USD). - `currency` string, required: ISO 4217 currency code. - `transaction_reference` string: Reference identifying the transaction. For deposits, transfers and withdrawals, this is the `transaction_reference` supplied on the request. For card transactions, this is the card transaction ID (the same value as `tid`). - `transaction_description` string: Free-text description supplied when the transaction was posted. It does not classify the transaction type or channel; use `type` for that. - `updated_at` string, date-time, required: When the transaction was recorded. Transactions are immutable, so this never changes after creation. - `account_balance_after` string, nullable: The searched account's net available (spendable) balance immediately after this transaction. - `account_pending_balance_after` string, nullable: The searched account's total pending (reserved) balance immediately after this transaction — outstanding holds in aggregate, not this transaction's hold. Rises on authorisation by the held amount, falls on settlement of that hold, and is zero when the account has no in-flight holds. - `tid` string: Card transaction ID — groups related messages (e.g., auth and clearing share the same tid) - `rid` string: Unique ID for each individual message on a card transaction - `sequence` integer: Order of the message on a card transaction (e.g., auth = 1, clearing = 2) - `token` string: Card token identifier - `merchant` string: Merchant name (card transactions) - `source_account_id` string: Source account identifier (for transfers, withdrawals, fees) - `destination_account_id` string: Destination account identifier (for transfers, deposits, adjustments, interest) - `external_account_reference` string: External counterparty reference for deposits and withdrawals — the funding source on a deposit, the destination on a withdrawal. Absent on other transaction types. - `exchange_rate` string: Exchange rate for cross-currency transfers. - `fee` TransactionFee: Fee shape used in transaction search results. - `amount` string, required: Fee amount in minor units. Must be greater than 0. - `currency` string, required: ISO 4217 currency code. - `charged_to` 'SOURCE' | 'DESTINATION': Indicates which side of the transfer pays the fee. - `type` string: Fee type - `next_cursor` string, nullable: Cursor for the next page of results. Null if no more pages. - `has_more` boolean, required: Whether more results are available ## Other responses - `400`: `BAD_REQUEST`: invalid parameter. Examples: neither or both of `account_id` and `token` provided; `updated_from` not before `updated_to`; date range over 366 days; `min_amount` greater than `max_amount`; `sort_by=AMOUNT` without `currency`. - `401`: Missing or invalid access token: `UNAUTHORIZED`, `INVALID_CLIENT` or `INVALID_TENANT`. - `403`: Access token rejected by the API gateway (for example, expired). - `404`: `NOT_FOUND`: `account_id` does not exist or does not belong to the client. An unknown `token` returns an empty result instead. - `500`: `INTERNAL_SERVER_ERROR`: unexpected error, including a search that takes longer than 10 seconds. Narrow the filters and retry. - `503`: `INFRASTRUCTURE_ERROR`: temporary failure, retry later. --- [API](https://skmtc.dev/paymentology/apis/ledger-api.md) - [All operations](https://skmtc.dev/paymentology/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paymentology/apis/ledger-api/revisions/a5700c501bee?raw)