Transactions

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.

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": []
  }'

{
  "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.

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.

Customers: upload known parties before referencing them
Documents: link transaction attachments by version
Outcomes: attach a source result to a transaction

Platform overview

Customer data

Financial data

Evidence

Results

Events

What to send

Upload a transaction

Update a transaction

Validation rules

Versioning and deduplication

​What to send

​Upload a transaction

​Update a transaction

​Validation rules

​Versioning and deduplication

​Related

What to send

Upload a transaction

Update a transaction

Validation rules

Versioning and deduplication

Related