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

# Manage Transactions - Get, Update & Status

> Retrieve and update individual transactions, bulk update multiple transactions, and manage transaction statuses via the Corsa API.

This guide covers managing transactions after ingestion — retrieving individual transactions, updating transaction data, updating statuses, and applying bulk updates across multiple transactions.

Full API endpoint details are available in the [API Reference](https://api.corsa.finance/api-spec.json) (requires API credentials).

<Note>To ingest new transactions (deposits, withdrawals, trades, transfers), see the [Ingest Operations](/api/ingesting-operations) guide.</Note>

***

## Get a Transaction

**Endpoint:** `GET /v1/transactions/{id}`

Retrieve a transaction by its Corsa-generated UUID or your external `referenceId`.

<CodeGroup>
  ```json REST API theme={null}
  GET /v1/transactions/txn-uuid-123
  # or by referenceId:
  GET /v1/transactions/MY-REF-001
  ```

  ```typescript Javascript theme={null}
  const transaction = await corsa.transactions.getTransaction("txn-uuid-123");
  ```

  ```python Python theme={null}
  from corsa_sdk.api.transactions.get_transaction import _get_kwargs

  resp = http.request(**_get_kwargs(id="txn-uuid-123"))
  transaction = resp.json()
  ```
</CodeGroup>

### Response Fields

| Field              | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `id`               | Corsa-generated UUID                                                 |
| `referenceId`      | Your external reference ID                                           |
| `type`             | `DEPOSIT`, `WITHDRAW`, `TRADE`, or `TRANSFER`                        |
| `currentStatus`    | Current status object with type and timestamp                        |
| `amount`           | Amount in the transaction currency                                   |
| `convertedAmount`  | Amount converted to your platform's preferred currency               |
| `from` / `to`      | Source and destination parties                                       |
| `txHash`           | Blockchain transaction hash (for crypto transactions)                |
| `evaluationResult` | Rule evaluation result, if the transaction was evaluated at creation |
| `customFields`     | Any custom key-value data                                            |

***

## Update a Transaction

**Endpoint:** `PUT /v1/transactions/{id}`

Update mutable fields on an existing transaction. Useful for enriching transactions with data that arrives after initial ingestion (for example, a blockchain hash that's confirmed later, or updated risk data from a screening provider).

<CodeGroup>
  ```json REST API theme={null}
  PUT /v1/transactions/txn-uuid-123
  Content-Type: application/json

  {
    "txHash": "0xabcdef1234567890...",
    "paymentRail": "ACH",
    "transferType": "DOMESTIC",
    "customFields": {
      "internalNotes": "Confirmed by compliance team"
    }
  }
  ```

  ```typescript Javascript theme={null}
  const updated = await corsa.transactions.updateTransaction("txn-uuid-123", {
    txHash: "0xabcdef1234567890...",
    paymentRail: "ACH",
    transferType: "DOMESTIC",
    customFields: {
      internalNotes: "Confirmed by compliance team",
    },
  });
  ```

  ```python Python theme={null}
  from corsa_sdk.api.transactions.update_transaction import _get_kwargs
  from corsa_sdk.models.update_transaction_dto import UpdateTransactionDto

  resp = http.request(**_get_kwargs(
      id="txn-uuid-123",
      body=UpdateTransactionDto(
          tx_hash="0xabcdef1234567890...",
          payment_rail="ACH",
          transfer_type="DOMESTIC",
          custom_fields={"internalNotes": "Confirmed by compliance team"},
      ),
  ))
  updated = resp.json()
  ```
</CodeGroup>

### Updatable Fields

| Field             | Description                                |
| ----------------- | ------------------------------------------ |
| `txHash`          | Blockchain transaction hash                |
| `paymentMethod`   | Method used for payment                    |
| `paymentRail`     | Payment network or settlement rail         |
| `transferType`    | `INTERNATIONAL`, `DOMESTIC`, or `INTERNAL` |
| `amount`          | Transaction amount details                 |
| `convertedAmount` | Converted amount details                   |
| `currentRisk`     | Updated risk assessment                    |
| `integrations`    | Third-party integration data               |
| `customFields`    | Custom key-value data                      |

***

## Update Transaction Status

**Endpoint:** `PUT /v1/transactions/{id}/updateStatus`

Update the status of a transaction. Corsa tracks a full status history — each call appends a new entry.

<CodeGroup>
  ```json REST API theme={null}
  PUT /v1/transactions/txn-uuid-123/updateStatus
  Content-Type: application/json

  {
    "type": "SUCCESS",
    "timestamp": "2024-01-15T10:30:00Z",
    "reason": "Payment settled",
    "subStatus": "SETTLED_ACH"
  }
  ```

  ```typescript Javascript theme={null}
  await corsa.transactions.updateTransactionStatus("txn-uuid-123", {
    type: "SUCCESS",
    timestamp: "2024-01-15T10:30:00Z",
    reason: "Payment settled",
    subStatus: "SETTLED_ACH",
  });
  ```

  ```python Python theme={null}
  from corsa_sdk.api.transactions.update_transaction_status import _get_kwargs
  from corsa_sdk.models.transaction_status_dto import TransactionStatusDto

  http.request(**_get_kwargs(
      id="txn-uuid-123",
      body=TransactionStatusDto(
          type="SUCCESS",
          timestamp="2024-01-15T10:30:00Z",
          reason="Payment settled",
          sub_status="SETTLED_ACH",
      ),
  ))
  ```
</CodeGroup>

### Status Fields

| Field                | Required | Description                                                                            |
| -------------------- | -------- | -------------------------------------------------------------------------------------- |
| `type`               | Yes      | `SUCCESS`, `PENDING`, `CANCELLED`, `FAILED`, or `FROZEN`                               |
| `timestamp`          | No       | ISO 8601 timestamp of the status change                                                |
| `reason`             | No       | Human-readable reason for the status                                                   |
| `subStatus`          | No       | Additional status detail                                                               |
| `updateParentStatus` | No       | If `true` and the transaction belongs to a trade, recalculates the parent trade status |

***

## Bulk Update Transactions

**Endpoint:** `PATCH /v1/transactions/bulk/update`

Apply the same field changes to up to 100 transactions in a single request. Use this to enrich or correct a batch of transactions efficiently.

<CodeGroup>
  ```json REST API theme={null}
  PATCH /v1/transactions/bulk/update
  Content-Type: application/json

  {
    "transactionIds": [
      "txn-uuid-001",
      "txn-uuid-002",
      "txn-uuid-003"
    ],
    "update": {
      "paymentRail": "WIRE",
      "transferType": "INTERNATIONAL",
      "customFields": {
        "reviewedBy": "compliance-team"
      }
    }
  }
  ```

  ```typescript Javascript theme={null}
  const result = await corsa.transactions.bulkUpdateTransactions({
    transactionIds: ["txn-uuid-001", "txn-uuid-002", "txn-uuid-003"],
    update: {
      paymentRail: "WIRE",
      transferType: "INTERNATIONAL",
      customFields: {
        reviewedBy: "compliance-team",
      },
    },
  });
  ```

  ```python Python theme={null}
  from corsa_sdk.api.transactions.bulk_update_transactions import _get_kwargs
  from corsa_sdk.models.bulk_update_transactions_dto import BulkUpdateTransactionsDto

  resp = http.request(**_get_kwargs(
      body=BulkUpdateTransactionsDto(
          transaction_ids=["txn-uuid-001", "txn-uuid-002", "txn-uuid-003"],
          update={
              "paymentRail": "WIRE",
              "transferType": "INTERNATIONAL",
              "customFields": {"reviewedBy": "compliance-team"},
          },
      ),
  ))
  result = resp.json()
  ```
</CodeGroup>

<Note>Maximum 100 transaction IDs per request. You can pass Corsa UUIDs or your external `referenceId` values interchangeably.</Note>

### Response

| Field                 | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `updatedTransactions` | Array of successfully updated transaction objects       |
| `failedTransactions`  | Array of transaction IDs that failed with error details |
| `totalProcessed`      | Total number of transaction IDs received                |
| `successCount`        | Number of transactions successfully updated             |
| `failureCount`        | Number of transactions that failed                      |

***

## Look Up Transactions by Blockchain Hash

**Endpoint:** `POST /v1/transactions/lookup-by-hash`

Batch-lookup transactions by their on-chain transaction hash. Useful when a blockchain analytics provider or internal process identifies a hash and you need to find the corresponding Corsa transaction records.

<CodeGroup>
  ```json REST API theme={null}
  POST /v1/transactions/lookup-by-hash
  Content-Type: application/json

  {
    "txHashes": [
      "0xabc123def456...",
      "0x789xyz..."
    ]
  }
  ```

  ```typescript Javascript theme={null}
  const results = await corsa.transactions.lookupTransactionsByHash({
    txHashes: [
      "0xabc123def456...",
      "0x789xyz...",
    ],
  });
  ```

  ```python Python theme={null}
  from corsa_sdk.api.transactions.lookup_transactions_by_hash import _get_kwargs
  from corsa_sdk.models.lookup_transactions_by_hash_dto import LookupTransactionsByHashDto

  resp = http.request(**_get_kwargs(
      body=LookupTransactionsByHashDto(
          tx_hashes=["0xabc123def456...", "0x789xyz..."],
      ),
  ))
  results = resp.json()
  ```
</CodeGroup>

### Request Fields

| Field      | Required | Description                                                                 |
| ---------- | -------- | --------------------------------------------------------------------------- |
| `txHashes` | Yes      | Array of blockchain transaction hashes to look up. Maximum 100 per request. |

The response returns an array of matching transaction objects for each hash provided. Hashes that do not match any stored transaction are omitted from the response.

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Ingest Operations" icon="arrow-right-arrow-left" href="/api/ingesting-operations">
    Ingest deposits, withdrawals, trades, and transfers for your clients.
  </Card>

  <Card title="Manage Alerts & Cases" icon="bell" href="/api/managing-alerts-and-cases">
    Bulk create, assign, and update compliance alerts and investigation cases.
  </Card>
</CardGroup>