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

> ## Agent Instructions
> Document only operations in the linked OpenAPI contract: the source-data ingestion operations and the source-scoped outbound webhook management operations.
> Treat the generated OpenAPI document as authoritative for request fields. Never invent compatibility fields, alternate endpoints, or additional source models.
> Preserve explicit nulls, decimal strings, timestamps, source identifiers, immutable version identifiers, and document-version links exactly as defined.

# Transactions

> Upload a movement of value with the subjects, money legs, and source status you know.

A Transaction is a movement of value reported by your system. It can contain a sent leg, a received
leg, or both, and must identify at least one known customer or account. Karsa does not require you to
invent a counterparty that your source does not know.

## What to send

| Field | Meaning |
| - | - |
| `externalId` | Stable transaction identifier in your system |
| `transactionType` | Source-defined transaction classification |
| `senderCustomerId`, `senderAccountId` | Known sending subjects, otherwise `null` |
| `receiverCustomerId`, `receiverAccountId` | Known receiving subjects, otherwise `null` |
| `sentAmount`, `sentCurrency` | Complete sent money pair, or both `null` |
| `receivedAmount`, `receivedCurrency` | Complete received money pair, or both `null` |
| `normalizedAmount`, `normalizedCurrency` | Optional complete normalized money pair |
| `paymentRail` | Provider-neutral payment rail, or `null` |
| `network` | Settlement or blockchain network, or `null` |
| `description` | Source transaction description, or `null` |
| `fees` | Typed amount/currency fee snapshots |
| `providerReferences` | Typed references supplied by payment providers |
| `status` | Source-defined transaction status |
| `occurredAt` | When the transaction occurred |
| `documents` | DocumentVersion links included in this snapshot |
| `customData` | Additional structured source fields, or `null` |
| `effectiveAt`, `sourceExternalId`, `changeReason` | Version time and optional source metadata |

Money values are decimal strings, not floating-point numbers.

## Upload a transaction

Subject fields use Karsa `resourceId` values returned by earlier customer uploads.

```bash theme={null}
curl --request POST \
  --url https://api.sandbox.useasterisk.com/api/ingestion/transactions \
  --header "Authorization: Bearer $KARSA_API_TOKEN" \
  --header "Idempotency-Key: transaction-example-001-create" \
  --header "Content-Type: application/json" \
  --data '{
    "externalId": "transaction-example-001",
    "sourceExternalId": null,
    "transactionType": "WIRE",
    "senderCustomerId": null,
    "senderAccountId": null,
    "receiverCustomerId": "customer_resource_example_01",
    "receiverAccountId": null,
    "sentAmount": "12500.00",
    "sentCurrency": "USD",
    "receivedAmount": "12500.00",
    "receivedCurrency": "USD",
    "normalizedAmount": null,
    "normalizedCurrency": null,
    "paymentRail": "WIRE",
    "network": null,
    "description": "Invoice settlement",
    "fees": [
      {
        "feeType": "TRANSACTION",
        "amount": "25.00",
        "currency": "USD",
        "description": "Processing fee"
      }
    ],
    "providerReferences": [
      {
        "referenceType": "PROVIDER_TRANSACTION",
        "value": "provider-transaction-example-001",
        "provider": "Example Payments"
      }
    ],
    "status": "SETTLED",
    "occurredAt": "2026-08-05T14:12:00Z",
    "customData": null,
    "effectiveAt": "2026-08-05T14:15:00Z",
    "changeReason": null,
    "documents": []
  }'
```

```json theme={null}
{
  "outcome": "CREATED",
  "resourceId": "transaction_resource_example_01",
  "versionId": "transaction_version_example_01",
  "currentVersionId": "transaction_version_example_01"
}
```

## Update a transaction

Use the Karsa `resourceId` in the path. Stable identifiers and `transactionType` are not
replaceable. Omitted mutable fields carry forward from the current version and an explicit `null`
clears a nullable value. Supplying `fees`, `providerReferences`, or `documents` replaces that
complete collection in the new snapshot; omitting a collection carries it forward.

```bash theme={null}
curl --request PUT \
  --url https://api.sandbox.useasterisk.com/api/ingestion/transactions/transaction_resource_example_01 \
  --header "Authorization: Bearer $KARSA_API_TOKEN" \
  --header "Idempotency-Key: transaction-example-001-update-01" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "COMPLETED",
    "providerReferences": [
      {
        "referenceType": "PROVIDER_TRANSACTION",
        "value": "provider-transaction-example-001",
        "provider": "Example Payments"
      },
      {
        "referenceType": "NETWORK_TRACE",
        "value": "network-trace-example-001",
        "provider": null
      }
    ],
    "effectiveAt": "2026-08-06T14:15:00Z",
    "changeReason": "SOURCE_STATUS_UPDATED"
  }'
```

The response has `outcome: "VERSION_CREATED"` and identifies the newly current immutable version.

## Validation rules

* At least one customer or account subject is required.
* At least one sent or received money pair is required.
* An amount and its currency must either both be present or both be `null`.
* The same rule applies to the optional normalized money pair.
* Document relationships use immutable Document `versionId` values.
* Fee and provider-reference amounts are decimal strings; collection order is preserved.

## Versioning and deduplication

POST remains compatible with complete source snapshots. PUT is the explicit partial update route:
it merges supplied mutable fields with the current version and appends a complete immutable
TransactionVersion. Use a new idempotency key when source data changes and reuse the original key
only when retrying the same logical write to the same path.

## Related

* [Customers](/concepts/customers): upload known parties before referencing them
* [Documents](/concepts/documents): link transaction attachments by version
* [Outcomes](/concepts/outcomes): attach a source result to a transaction


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.