# Transactions

The Transactions API surfaces every monetary movement that touches the accounts your business holds on Rho - card spend, ACH, wires, internal transfers, interest, and refunds. Use it to feed your data warehouse, drive reconciliation, or trigger workflows the moment money lands.

Stable contract
The Transactions API is part of the stable `v1` contract: additive-only, with breaking changes reserved for a new API version. See [Versioning and compatibility](/docs/v1/versioning).

## What a transaction represents

A single `transaction` record models one ledger event against one account. Its key fields:

| Field | What it tells you |
|  --- | --- |
| `id` | A stable global identifier. Safe to use as an idempotency key downstream. |
| `money_movement_id` | Identifier used to correlate transaction legs belonging to the same money movement. |
| `account_id`, `account_type` | The account the event posted against, and its type. |
| `transaction_type` | The kind of event: card credits and debits, ACH, wires, transfers, refunds, repayments, and interest. See the [API Reference](/api/v1/openapi/transactions) for the full list of values. |
| `status` | One of pending, settled, or failed. Most events pass through pending before they settle. |
| `amount` | A signed amount in the account's currency, in minor units (cents for USD). Negative values are debits. |
| `initiated_at`, `posted_at` | When the event was created versus when it cleared the ledger. `posted_at` stays empty until the transaction settles. |
| `attachments` | Stable file descriptors containing `file_id` and `file_name`. The array is empty when no files are attached. |


## Downloading attachments

Transaction responses contain stable attachment metadata but never signed URLs. Request a fresh, short-lived URL only when the file is needed:

```bash
curl "https://rhoapi.rho.co/api/v1/transactions/{transaction_id}/files/{file_id}" \
  -H "Authorization: Bearer $RHO_API_TOKEN"
```

Set `{transaction_id}` to the transaction's `id`, and `{file_id}` to an `attachments[].file_id` value. A transaction `id` identifies one transaction.

The response contains `file_id`, `file_name`, and `download_url`. Fetch it again whenever a new signed URL is needed; do not persist the URL.

## Lifecycle

Most transactions follow the same shape:

1. **Initiated** - Rho creates the record with a status of pending and an `initiated_at` timestamp. `posted_at` is still empty.
2. **Settled** - Once funds clear, the status flips to settled and `posted_at` is filled in. The amount can shift slightly between the initial authorization and final clearing.
3. **Failed** - On an unrecoverable failure (insufficient funds, a returned ACH, a declined card), the status flips to failed and `posted_at` stays empty. The record remains queryable for audit purposes.


Records do **not** move backwards. A transaction that has settled will not flip back to pending - instead, a separate reversal transaction is issued.

## Common workflows

### Reconciling daily activity

Iterate the list endpoint with `posted_after` and `posted_before` set to the boundaries of your accounting day, and `status=settled` to skip in-flight items:

```bash
curl 'https://rhoapi.rho.co/api/v1/transactions?status=settled&posted_after=2026-05-21T00:00:00Z&posted_before=2026-05-22T00:00:00Z&page_size=100' \
  -H "Authorization: Bearer $RHO_API_TOKEN"
```

Follow the cursor (see [Pagination](/docs/v1/pagination)) until `next_page_token` is `null`.

### Detecting card disputes

Filter on `transaction_type=card_refund` and `transaction_type=card_credit` against the `account_type=credit` slice to surface refunds against the card line of credit. Each refund references the original auth via metadata.

### Idempotent ingestion

Use `transaction.id` as the primary key when writing to your warehouse. Re-fetching a day's window will return the same `id` values, making the pipeline naturally idempotent.

## Reference

Full endpoint catalogue - paths, parameters, response shapes, and required scopes - lives in the [API Reference](/api/v1/openapi/transactions).