Transactions

Endpointhttps://api.kontorion.eu/v1

Start a wallet hold for a transaction

POST

https://api.kontorion.eu/v1

/transaction/reserve

Resolves the price for the requested product and places a hold on the customer's wallet. Capture or release follow at /transaction/{id}/capture or /transaction/{id}/release. Returns 202 status="dropped" when keyed-prices policy=drop and no key matches.

Start a wallet hold for a transaction › Request Body

customer_id

string

object

external_cost_amount

number

ExternalCostAmount + ExternalCostCurrency feed the resolver's cost.* formula-variable namespace. Required when the resolved price's tier expression references cost. and the caller owns the actual cost value (telco wholesale pass-through, per-call carrier fees, etc.). Both fields go together or neither — the validator enforces the pair.

external_cost_currency

string

hold_expires_at

string

HoldExpiresAt is the TTL of the hold the reserve creates. If the caller doesn't capture the hold by this instant the wallet auto-releases it. Renamed from expires_at in the shape cleanup — the old name was ambiguous about what expires.

idempotency_key

string

object

metric_key

string

price_key

string

object

product_id

string

quantity

number

subscription_id

string

wallet_currency

string

WalletCurrency optionally pins the hold to the customer's wallet in this currency. The one-wallet-per-(customer, currency) invariant (idx_wallets_customer_currency) makes the lookup unambiguous. When unset the reserve falls back to the customer's primary wallet (the row with is_primary=true). Either lookup fails with a clear DomainError when the wallet doesn't exist — no auto-routing across currencies.

Start a wallet hold for a transaction › Responses

Hold created

blocked_reasons

string[]

can_proceed

boolean

expires_at

string

fx_rate_id

string

hold_id

string

object

resolved_currency

string

object

tax_rate

number

tax_rule_id

string

wallet_id

string

Phase F: cross-flow reconciliation handles. Callers persist these alongside their internal record so preview/reserve/invoice numbers can be tied back to the same tax rule and FX rate snapshot.

POST/transaction/reserve

curl --request POST \
  --url https://api.kontorion.eu/v1/transaction/reserve \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "customer_id",
  "dimension_vars": {
    "key": "string"
  },
  "external_cost_amount": 0,
  "external_cost_currency": "external_cost_currency",
  "hold_expires_at": "hold_expires_at",
  "idempotency_key": "idempotency_key",
  "metadata": {
    "key": {}
  },
  "metric_key": "metric_key",
  "price_key": "price_key",
  "pricing_vars": {
    "key": 0
  },
  "product_id": "product_id",
  "quantity": 0,
  "subscription_id": "subscription_id",
  "wallet_currency": "wallet_currency"
}
'

shell

Example Request Body

{
  "customer_id": "customer_id",
  "dimension_vars": {
    "key": "string"
  },
  "external_cost_amount": 0,
  "external_cost_currency": "external_cost_currency",
  "hold_expires_at": "hold_expires_at",
  "idempotency_key": "idempotency_key",
  "metadata": {
    "key": {}
  },
  "metric_key": "metric_key",
  "price_key": "price_key",
  "pricing_vars": {
    "key": 0
  },
  "product_id": "product_id",
  "quantity": 0,
  "subscription_id": "subscription_id",
  "wallet_currency": "wallet_currency"
}

json

Example Responses

{
  "blocked_reasons": [
    "string"
  ],
  "can_proceed": true,
  "expires_at": "expires_at",
  "fx_rate_id": "fx_rate_id",
  "hold_id": "hold_id",
  "net_amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "resolved_amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "resolved_currency": "resolved_currency",
  "tax_amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "tax_rate": 0,
  "tax_rule_id": "tax_rule_id",
  "wallet_id": "wallet_id"
}

json

application/json

Ingest a usage event (fire-and-forget billing)

POST

https://api.kontorion.eu/v1

/transaction/usage-event

Accepts a single usage event or a batch ({"events": [...]}). Records the event for billing on the next invoice; does not check wallet balance, credit limits, or hold availability. Use the reserve/capture flow when up-front fund availability matters.

Ingest a usage event (fire-and-forget billing) › Request Body

customer_id

string

object

external_cost_amount

number

external_cost_currency

string

hold_id

string

idempotency_key

string

object

metric_key

string

price_key

string

M186 - required for keyed products

object

product_id

string

quantity

number

subscription_id

string

timestamp

string

Timestamp is the moment the event occurred (when the customer consumed the unit). Optional — when absent or zero, the server stamps it from time.Now() at ingest. Backfill / historical imports set this explicitly to whatever the source recorded. Distinct from UsageEvent.IngestedAt, which is always the server-side ingestion instant.

wallet_currency

string

WalletCurrency optionally pins the event to a specific wallet. Shape parity with /reserve's wallet_currency. Validated at ingest: the wallet must exist for (customer_id, wallet_currency). NULL falls back to the customer's preferred-currency cascade at finalize — the pre-040 single-wallet path.

Ingest a usage event (fire-and-forget billing) › Responses

Created event or batch result wrapped in data envelope

POST/transaction/usage-event

curl --request POST \
  --url https://api.kontorion.eu/v1/transaction/usage-event \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "customer_id",
  "dimension_vars": {
    "key": "string"
  },
  "external_cost_amount": 0,
  "external_cost_currency": "external_cost_currency",
  "hold_id": "hold_id",
  "idempotency_key": "idempotency_key",
  "metadata": {
    "key": {}
  },
  "metric_key": "metric_key",
  "price_key": "price_key",
  "pricing_vars": {
    "key": 0
  },
  "product_id": "product_id",
  "quantity": 0,
  "subscription_id": "subscription_id",
  "timestamp": "timestamp",
  "wallet_currency": "wallet_currency"
}
'

shell

Example Request Body

{
  "customer_id": "customer_id",
  "dimension_vars": {
    "key": "string"
  },
  "external_cost_amount": 0,
  "external_cost_currency": "external_cost_currency",
  "hold_id": "hold_id",
  "idempotency_key": "idempotency_key",
  "metadata": {
    "key": {}
  },
  "metric_key": "metric_key",
  "price_key": "price_key",
  "pricing_vars": {
    "key": 0
  },
  "product_id": "product_id",
  "quantity": 0,
  "subscription_id": "subscription_id",
  "timestamp": "timestamp",
  "wallet_currency": "wallet_currency"
}

json

Example Responses

{}

json

application/json

Capture (settle) a wallet hold

POST

https://api.kontorion.eu/v1

/transaction/{id}/capture

Settles a pending hold by debiting the reserved funds. Use after the work that triggered the reserve has succeeded.

Capture (settle) a wallet hold › path Parameters

id

string · required

Hold UUID

Capture (settle) a wallet hold › Request Body

amount

number

nil = capture full hold amount

reference

string

optional capture reference

Capture (settle) a wallet hold › Responses

Wrapped in data envelope

object

captured_at

string

created_at

string

currency

string

expires_at

string

id

string

metric_key

string

organization_id

string

reason

string

reference_id

string

reference_type

string

resolved_at

string

reverse_charge

boolean

status

string · enum

Enum values:

PENDING

CAPTURED

VOIDED

EXPIRED

subscription_id

string

SubscriptionID and MetricKey identify the usage stream this hold reserves capacity for. Set by the reserve service so the usage event ingest path can detect overlap (Phase D dedup); nil for non-subscription holds like deposits.

tax_rate

number

tax_rule_id

string

voided_at

string

wallet_id

string

POST/transaction/{id}/capture

curl --request POST \
  --url https://api.kontorion.eu/v1/transaction/:id/capture \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 0,
  "reference": "reference"
}
'

shell

Example Request Body

{
  "amount": 0,
  "reference": "reference"
}

json

Example Responses

{
  "key": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "captured_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "captured_at": "captured_at",
    "created_at": "created_at",
    "currency": "currency",
    "expires_at": "expires_at",
    "id": "id",
    "metric_key": "metric_key",
    "organization_id": "organization_id",
    "reason": "reason",
    "reference_id": "reference_id",
    "reference_type": "reference_type",
    "resolved_at": "resolved_at",
    "reverse_charge": true,
    "status": "PENDING",
    "subscription_id": "subscription_id",
    "tax_rate": 0,
    "tax_rule_id": "tax_rule_id",
    "voided_at": "voided_at",
    "wallet_id": "wallet_id"
  }
}

json

application/json

Release a wallet hold

POST

https://api.kontorion.eu/v1

/transaction/{id}/release

Releases a pending hold, returning reserved funds to available balance. Use when the work that triggered the reserve was cancelled or failed.

Release a wallet hold › path Parameters

id

string · required

Hold UUID

Release a wallet hold › Responses

Wrapped in data envelope

object

captured_at

string

created_at

string

currency

string

expires_at

string

id

string

metric_key

string

organization_id

string

reason

string

reference_id

string

reference_type

string

resolved_at

string

reverse_charge

boolean

status

string · enum

Enum values:

PENDING

CAPTURED

VOIDED

EXPIRED

subscription_id

string

tax_rate

number

tax_rule_id

string

voided_at

string

wallet_id

string

POST/transaction/{id}/release

curl --request POST \
  --url https://api.kontorion.eu/v1/transaction/:id/release

shell

Example Responses

{
  "key": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "captured_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "captured_at": "captured_at",
    "created_at": "created_at",
    "currency": "currency",
    "expires_at": "expires_at",
    "id": "id",
    "metric_key": "metric_key",
    "organization_id": "organization_id",
    "reason": "reason",
    "reference_id": "reference_id",
    "reference_type": "reference_type",
    "resolved_at": "resolved_at",
    "reverse_charge": true,
    "status": "PENDING",
    "subscription_id": "subscription_id",
    "tax_rate": 0,
    "tax_rule_id": "tax_rule_id",
    "voided_at": "voided_at",
    "wallet_id": "wallet_id"
  }
}

json

application/json

List unified financial transactions

GET

https://api.kontorion.eu/v1

/transactions

Returns the org's money-movement ledger across manual payments, gateway payment attempts, wallet transactions, and credit notes - newest first, cursor-paginated. Each row is normalized into the same shape so the dashboard can mix kinds in one list.

List unified financial transactions › query Parameters

limit

integer

Page size (default 25, max 100)

cursor

string

Pagination cursor

kind

string[] · explode: true

Filter by transaction kind (manual_payment, payment_attempt, wallet_transaction, wallet_hold, credit_note). Repeatable or comma-separated.

status

string[] · explode: true

Filter by unified status (succeeded, pending, failed, refunded, voided, applied, draft). Repeatable or comma-separated.

direction

string

Filter by money direction: in | out | internal

customer_id

string

Filter by customer UUID

invoice_id

string

Filter by invoice UUID (skips wallet transactions, which don't reference invoices)

occurred_after

string

Filter by occurred_at >= timestamp (RFC3339)

occurred_before

string

Filter by occurred_at < timestamp (RFC3339)

List unified financial transactions › Responses

Paginated list with data and pagination envelope

object[]

object

customer_id

string

direction

string · enum

Enum values:

out

internal

id

string

invoice_id

string

kind

string · enum

Enum values:

manual_payment

payment_attempt

wallet_transaction

wallet_hold

credit_note

occurred_at

string

raw_id

string

reference

string

source

string

status

string · enum

Enum values:

succeeded

pending

failed

refunded

voided

applied

draft

subscription_id

string

summary

string

wallet_id

string

TaxRules Usage

Start a wallet hold for a transaction

POST

https://api.kontorion.eu/v1

/transaction/reserve

Start a wallet hold for a transaction › Request Body

customer_id

string

object

external_cost_amount

number

external_cost_currency

string

hold_expires_at

string

idempotency_key

string

object

metric_key

string

price_key

string

object

product_id

string

quantity

number

subscription_id

string

wallet_currency

string

Start a wallet hold for a transaction › Responses

Hold created

blocked_reasons

string[]

can_proceed

boolean

expires_at

string

fx_rate_id

string

hold_id

string

object

resolved_currency

string

object

tax_rate

number

tax_rule_id

string

wallet_id

string

Phase F: cross-flow reconciliation handles. Callers persist these alongside their internal record so preview/reserve/invoice numbers can be tied back to the same tax rule and FX rate snapshot.

Ingest a usage event (fire-and-forget billing)

POST

https://api.kontorion.eu/v1

/transaction/usage-event

Ingest a usage event (fire-and-forget billing) › Request Body

customer_id

string

object

external_cost_amount

number

external_cost_currency

string

hold_id

string

idempotency_key

string

object

metric_key

string

price_key

string

M186 - required for keyed products

object

product_id

string

quantity

number

subscription_id

string

timestamp

string

wallet_currency

string

Ingest a usage event (fire-and-forget billing) › Responses

Created event or batch result wrapped in data envelope

Capture (settle) a wallet hold

POST

https://api.kontorion.eu/v1

/transaction/{id}/capture

Settles a pending hold by debiting the reserved funds. Use after the work that triggered the reserve has succeeded.

Capture (settle) a wallet hold › path Parameters

id

string · required

Hold UUID

Capture (settle) a wallet hold › Request Body

amount

number

nil = capture full hold amount

reference

string

optional capture reference

Capture (settle) a wallet hold › Responses

Wrapped in data envelope

object

captured_at

string

created_at

string

currency

string

expires_at

string

id

string

metric_key

string

organization_id

string

reason

string

reference_id

string

reference_type

string

resolved_at

string

reverse_charge

boolean

status

string · enum

Enum values:

PENDING

CAPTURED

VOIDED

EXPIRED

subscription_id

string

tax_rate

number

tax_rule_id

string

voided_at

string

wallet_id

string

Release a wallet hold

POST

https://api.kontorion.eu/v1

/transaction/{id}/release

Releases a pending hold, returning reserved funds to available balance. Use when the work that triggered the reserve was cancelled or failed.

Release a wallet hold › path Parameters

id

string · required

Hold UUID

Release a wallet hold › Responses

Wrapped in data envelope

object

captured_at

string

created_at

string

currency

string

expires_at

string

id

string

metric_key

string

organization_id

string

reason

string

reference_id

string

reference_type

string

resolved_at

string

reverse_charge

boolean

status

string · enum

Enum values:

PENDING

CAPTURED

VOIDED

EXPIRED

subscription_id

string

tax_rate

number

tax_rule_id

string

voided_at

string

wallet_id

string

List unified financial transactions

GET

https://api.kontorion.eu/v1

/transactions

List unified financial transactions › query Parameters

limit

integer

Page size (default 25, max 100)

cursor

string

Pagination cursor

kind

string[] · explode: true

Filter by transaction kind (manual_payment, payment_attempt, wallet_transaction, wallet_hold, credit_note). Repeatable or comma-separated.

status

string[] · explode: true

Filter by unified status (succeeded, pending, failed, refunded, voided, applied, draft). Repeatable or comma-separated.

direction

string

Filter by money direction: in | out | internal

customer_id

string

Filter by customer UUID

invoice_id

string

Filter by invoice UUID (skips wallet transactions, which don't reference invoices)

occurred_after

string

Filter by occurred_at >= timestamp (RFC3339)

occurred_before

string

Filter by occurred_at < timestamp (RFC3339)

List unified financial transactions › Responses

Paginated list with data and pagination envelope

object[]

object

customer_id

string

direction

string · enum

Enum values:

out

internal

id

string

invoice_id

string

kind

string · enum

Enum values:

manual_payment

payment_attempt

wallet_transaction

wallet_hold

credit_note

occurred_at

string

raw_id

string

reference

string

source

string

status

string · enum

Enum values:

succeeded

pending

failed

refunded

voided

applied

draft

subscription_id

string

summary

string

wallet_id

string