> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transactions List
> List your account's program-balance movements — deposits, card fundings, issuances, invoice payments, and reversals. GET /transactions. Requires accounts:read scope.
## Overview
Returns a paginated list of program-balance transactions for the authenticated business, scoped to the API key's environment. Each record represents a movement of funds in your operational balance — deposits in, card fundings out, invoice payments, and more.
By default, results span the last **30 days**. The maximum date range is **92 days** — use multiple requests for longer histories.
## Query Parameters
| Parameter | Type | Default | Description |
| ----------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | integer | 20 | Results per page (max 100) |
| `offset` | integer | 0 | Number of records to skip |
| `from` | string | 30 days ago | Start date/time (`YYYY-MM-DD` or ISO 8601) |
| `to` | string | now | End date/time (`YYYY-MM-DD` or ISO 8601) |
| `type` | string | — | Filter by type: `DEPOSIT`, `WITHDRAWAL`, `CARD_FUNDING`, `CARD_WITHDRAWAL`, `CARD_ISSUANCE`, `CARD_TERMINATION_REFUND`, `INVOICE_PAYMENT`, `REVERSAL` |
| `status` | string | — | Filter by status: `PENDING`, `SETTLED`, `FAILED`, `REVERSED` |
| `direction` | string | — | `CREDIT` or `DEBIT` |
| `cardId` | string | — | Filter to movements related to a specific card |
| `search` | string | — | Search by memo or reference |
## Example
```bash cURL theme={null}
curl -G https://api.fyatu.com/api/v3.20/transactions \
-H "Authorization: Bearer $FYATU_API_KEY" \
-d from=2026-05-01 \
-d to=2026-05-31 \
-d type=CARD_FUNDING
```
```javascript Node.js theme={null}
const params = new URLSearchParams({
from: '2026-05-01',
to: '2026-05-31',
type: 'CARD_FUNDING',
limit: '50'
});
const resp = await fetch(
`https://api.fyatu.com/api/v3.20/transactions?${params}`,
{ headers: { 'Authorization': `Bearer ${process.env.FYATU_API_KEY}` } }
);
const body = await resp.json();
for (const tx of body.data) {
const sign = tx.direction === 'DEBIT' ? '-' : '+';
console.log(`${sign}${tx.amount.displayValue} ${tx.type} [${tx.status}]`);
}
```
```python Python theme={null}
import os, requests
resp = requests.get(
'https://api.fyatu.com/api/v3.20/transactions',
headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
params={'from': '2026-05-01', 'to': '2026-05-31', 'type': 'CARD_FUNDING'}
)
for tx in resp.json()['data']:
sign = '-' if tx['direction'] == 'DEBIT' else '+'
print(f"{sign}{tx['amount']['displayValue']} {tx['type']} [{tx['status']}]")
```
## Success Response (200)
```json theme={null}
{
"success": true,
"status": 200,
"message": "Transactions retrieved",
"data": [
{
"transactionId": "txn_01HXYZ8888ABCDEF9999",
"type": "CARD_FUNDING",
"direction": "DEBIT",
"status": "SETTLED",
"amount": 500.00,
"currency": "USD",
"fee": 0.00,
"reference": "fund_01HXYZ5555ABCDEF1111",
"account": "prg_01HXYZ9876ABCDEF0000",
"memo": "Card funding — crd_01HXYZ5555ABCDEF1111",
"balanceBefore": 10000.00,
"balanceAfter": 9500.00,
"relatedTransactionId": null,
"completedAt": "2026-05-22T14:32:00Z",
"createdAt": "2026-05-22T14:30:00Z",
"cardId": "crd_01HXYZ5555ABCDEF1111"
}
],
"pagination": {
"total": 47,
"limit": 20,
"offset": 0,
"hasMore": true
},
"meta": {
"requestId": "req_01HXY123456ABCDEF",
"platform": "Fyatu CaaS",
"timestamp": "2026-05-22T15:00:00Z"
}
}
```
## Transaction Types
| Type | Direction | Description |
| ------------------------- | --------- | --------------------------------------------------------- |
| `DEPOSIT` | CREDIT | Funds added to your operational balance |
| `WITHDRAWAL` | DEBIT | Funds withdrawn from your operational balance |
| `CARD_ISSUANCE` | DEBIT | Debit for issuing a new virtual card |
| `CARD_FUNDING` | DEBIT | Debit for loading funds onto a card |
| `CARD_WITHDRAWAL` | CREDIT | Credit when balance is unloaded from a card |
| `CARD_TERMINATION_REFUND` | CREDIT | Remaining card balance returned when a card is terminated |
| `INVOICE_PAYMENT` | DEBIT | Monthly platform fee deducted from your balance |
| `REVERSAL` | Varies | Correction or reversal of a prior transaction |
## Field Reference
| Field | Description |
| ---------------------- | ------------------------------------------------------------------------------ |
| `transactionId` | Unique transaction identifier |
| `type` | Movement type — see table above |
| `direction` | `CREDIT` (funds in) or `DEBIT` (funds out) |
| `status` | `PENDING`, `SETTLED`, `FAILED`, or `REVERSED` |
| `amount` | Transaction amount in USD |
| `currency` | Always `USD` |
| `fee` | Fee in USD applied to this transaction (`0` when no fee) |
| `reference` | Internal reference ID linking to the originating operation |
| `account` | Program ID associated with this movement |
| `memo` | Human-readable description of the transaction |
| `balanceBefore` | Operational balance in USD before this transaction; `null` if not recorded |
| `balanceAfter` | Operational balance in USD after this transaction; `null` if not recorded |
| `relatedTransactionId` | For reversals, the ID of the original transaction; `null` otherwise |
| `completedAt` | ISO 8601 timestamp when the transaction settled; empty string if still pending |
| `cardId` | Card ID if the movement is card-related; `null` otherwise |
## Error Codes
| Code | HTTP | Cause |
| --------------------- | ---- | ------------------------------------- |
| `DATE_RANGE_TOO_WIDE` | 422 | Date range exceeds the 92-day maximum |
| `INSUFFICIENT_SCOPE` | 403 | Key lacks `accounts:read` scope |
## OpenAPI
````yaml v3.20/openapi.json GET /transactions
openapi: 3.1.0
info:
title: FYATU CaaS API v3.20
description: >-
FYATU Cards-as-a-Service API — API key authentication, Cardholder
lifecycle, Card issuance, Transactions, Webhooks, and Programs.
version: 3.20.0
contact:
name: FYATU Support
url: https://fyatu.com
email: support@fyatu.com
servers:
- url: https://api.fyatu.com/api/v3.20
description: >-
FYATU CaaS API — the environment (LIVE or SANDBOX) is determined by the
API key, not the URL
security:
- BearerAuth: []
tags:
- name: Meta
description: Liveness, account info, and supported event types
- name: Account
description: Account-level balance and funding status
- name: Programs
description: Read card program configuration
- name: Cardholders
description: Create and manage cardholder profiles
- name: Cards
description: Issue, fund, freeze, and terminate virtual cards
- name: Transactions
description: Read-only card transaction history
- name: Webhooks
description: Manage webhook endpoints for real-time event delivery
- name: Products
description: Read card product configurations
paths:
/transactions:
get:
tags:
- Account
summary: List transactions
description: >-
Returns a paginated list of program-balance movements for the
authenticated business. Includes deposits, card fundings, issuances,
invoice payments, and reversals. Default date range is 30 days; maximum
is 92 days.
operationId: listTransactions
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: offset
in: query
schema:
type: integer
minimum: 0
default: 0
- name: from
in: query
schema:
type: string
description: Start date (YYYY-MM-DD or ISO 8601). Defaults to 30 days ago.
example: '2026-05-01'
- name: to
in: query
schema:
type: string
description: End date (YYYY-MM-DD or ISO 8601). Defaults to now.
example: '2026-05-31'
- name: type
in: query
schema:
type: string
enum:
- DEPOSIT
- WITHDRAWAL
- CARD_FUNDING
- CARD_WITHDRAWAL
- CARD_ISSUANCE
- CARD_TERMINATION_REFUND
- INVOICE_PAYMENT
- REVERSAL
- name: status
in: query
schema:
type: string
enum:
- PENDING
- SETTLED
- FAILED
- REVERSED
- name: direction
in: query
schema:
type: string
enum:
- CREDIT
- DEBIT
- name: cardId
in: query
schema:
type: string
description: Filter to movements related to a specific card
- name: search
in: query
schema:
type: string
description: Search by memo or reference
responses:
'200':
description: Transactions retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionListResponse'
example:
success: true
status: 200
message: Transactions retrieved
data:
- transactionId: txn_01HXYZ8888ABCDEF9999
type: CARD_FUNDING
direction: DEBIT
status: SETTLED
amount: 500
currency: USD
fee: 0
reference: fund_01HXYZ5555ABCDEF1111
account: prg_01HXYZ9876ABCDEF0000
memo: Card funding — crd_01HXYZ5555ABCDEF1111
balanceBefore: 10000
balanceAfter: 9500
relatedTransactionId: null
completedAt: '2026-05-22T14:32:00Z'
createdAt: '2026-05-22T14:30:00Z'
cardId: crd_01HXYZ5555ABCDEF1111
pagination:
total: 47
limit: 20
offset: 0
hasMore: true
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'422':
description: Date range exceeds 92 days
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
status: 422
message: Date range exceeds 92-day maximum
error:
code: DATE_RANGE_TOO_WIDE
detail: Date range must not exceed 92 days
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
TransactionListResponse:
type: object
properties:
success:
type: boolean
example: true
status:
type: integer
example: 200
message:
type: string
example: Transactions retrieved
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
pagination:
$ref: '#/components/schemas/Pagination'
meta:
$ref: '#/components/schemas/Meta'
Error:
type: object
properties:
success:
type: boolean
example: false
status:
type: integer
example: 422
message:
type: string
example: Human readable message
error:
$ref: '#/components/schemas/ErrorBody'
meta:
$ref: '#/components/schemas/Meta'
Transaction:
type: object
properties:
transactionId:
type: string
example: txn_01HXYZ8888ABCDEF9999
type:
type: string
enum:
- AUTHORIZATION
- CLEARING
- REVERSAL
- FEE
example: AUTHORIZATION
status:
type: string
enum:
- APPROVED
- DECLINED
- REVERSED
example: PENDING
amount:
$ref: '#/components/schemas/TransactionAmount'
merchant:
$ref: '#/components/schemas/TransactionMerchant'
cardId:
type: string
example: crd_01HXYZ5555ABCDEF1111
cardholderId:
type: string
example: chl_01HXYZ1234ABCDEF5678
programId:
type: string
example: prg_01HXYZ9876ABCDEF0000
relatedTransactionId:
type: string
nullable: true
description: Set for reversals and refunds
example: null
environment:
type: string
enum:
- LIVE
- SANDBOX
example: LIVE
declineReason:
type: string
nullable: true
example: null
processedAt:
type: string
format: date-time
nullable: true
example: null
createdAt:
type: string
format: date-time
example: '2026-05-22T14:30:00Z'
Pagination:
type: object
properties:
total:
type: integer
example: 47
limit:
type: integer
example: 20
offset:
type: integer
example: 0
hasMore:
type: boolean
example: true
Meta:
type: object
properties:
requestId:
type: string
example: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform:
type: string
example: Fyatu CaaS
timestamp:
type: string
format: date-time
example: '2026-05-22T15:00:00Z'
ErrorBody:
type: object
properties:
code:
type: string
example: VALIDATION_ERROR
detail:
type: string
example: dateOfBirth must be in YYYY-MM-DD format
TransactionAmount:
type: object
properties:
value:
type: integer
format: int64
description: Amount in cents
example: 2999
currency:
type: string
example: USD
displayValue:
type: string
description: Human-readable amount without currency symbol
example: '29.99'
TransactionMerchant:
type: object
properties:
name:
type: string
nullable: true
example: Amazon
city:
type: string
nullable: true
example: Seattle
country:
type: string
nullable: true
example: US
mcc:
type: string
nullable: true
description: ISO 18245 Merchant Category Code
example: '5999'
mccDescription:
type: string
nullable: true
example: Miscellaneous General Merchandise
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing:
summary: API key missing
value:
success: false
status: 401
message: API key is required
error:
code: AUTH_TOKEN_MISSING
detail: API key is required
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
invalid:
summary: API key invalid
value:
success: false
status: 401
message: Invalid API key
error:
code: AUTH_TOKEN_INVALID
detail: Invalid API key
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
Forbidden:
description: Scope denied or business suspended
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
status: 403
message: Scope denied
error:
code: INSUFFICIENT_SCOPE
detail: This endpoint requires the cards:write scope
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
RateLimitExceeded:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
status: 429
message: Rate limit exceeded
error:
code: RATE_LIMIT_EXCEEDED
detail: Too many requests
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
InternalError:
description: Unexpected server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
success: false
status: 500
message: Internal error
error:
code: INTERNAL_ERROR
detail: An unexpected error occurred
meta:
requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
platform: Fyatu CaaS
timestamp: '2026-05-22T15:00:00Z'
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
`.
````