Wallets

Endpointhttps://api.kontorion.eu/v1

A wallet is a prepaid credit balance associated with a customer. Wallets allow customers to pre-fund their account, receive credits (promotional or otherwise), and have charges automatically deducted from their balance before falling back to a payment method.

Each customer has a primary wallet created automatically, and can have additional wallets in different currencies.

Key operations:

Credit - add funds to the wallet (from a payment, promotion, or manual adjustment)
Debit - remove funds (applied automatically during invoicing, or manually)
Hold - reserve an amount for a pending charge (released or captured later)
Transfer - move funds between wallets (e.g., currency conversion)
Adjust - correct the balance without a formal credit/debit (e.g., migration adjustment)

List wallets

GET

https://api.kontorion.eu/v1

/wallets

Returns wallets for the org, newest first, cursor-paginated. All filters AND together; multi-value currency is OR within itself. Pass customer_id to scope to one customer; omit to browse org-wide.

List wallets › query Parameters

limit

integer

Page size (default 25, max 100)

cursor

string

Pagination cursor

customer_id

string

Filter by customer UUID

currency

string[] · explode: true

Filter by ISO 4217 currency code (repeatable or comma-separated)

is_primary

boolean

true=only primary wallets, false=only secondary; omit for both

auto_topup_enabled

boolean

Filter by auto-topup state

created_after

string

Filter by created_at >= timestamp (RFC3339)

created_before

string

Filter by created_at < timestamp (RFC3339)

List wallets › Responses

Paginated list with data and pagination envelope

object[]

object

auto_topup_enabled

boolean

object

created_at

string

object

currency

string

customer_id

string

object

id

string

is_primary

boolean

object

mode

string · enum

Enum values:

PREPAID

POSTPAID

organization_id

string

object

promotional_balance_expires_at

string

updated_at

string

GET/wallets

curl --request GET \
  --url https://api.kontorion.eu/v1/wallets

shell

Example Responses

{
  "key": [
    {
      "auto_topup_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "auto_topup_enabled": true,
      "cash_balance": {
        "currency": "EUR",
        "value": "49.5"
      },
      "created_at": "created_at",
      "credit_limit": {
        "currency": "EUR",
        "value": "49.5"
      },
      "currency": "currency",
      "customer_id": "customer_id",
      "held_balance": {
        "currency": "EUR",
        "value": "49.5"
      },
      "id": "id",
      "is_primary": true,
      "low_balance_threshold": {
        "currency": "EUR",
        "value": "49.5"
      },
      "max_balance": {
        "currency": "EUR",
        "value": "49.5"
      },
      "max_single_credit": {
        "currency": "EUR",
        "value": "49.5"
      },
      "metadata": {
        "key": {}
      },
      "mode": "PREPAID",
      "organization_id": "organization_id",
      "promotional_balance": {
        "currency": "EUR",
        "value": "49.5"
      },
      "promotional_balance_expires_at": "promotional_balance_expires_at",
      "updated_at": "updated_at"
    }
  ]
}

json

application/json

Create a wallet

POST

https://api.kontorion.eu/v1

/wallets

Creates a secondary wallet for the specified customer

Create a wallet › path Parameters

id

string · required

Customer UUID

Create a wallet › Request Body

auto_topup_amount

number

auto_topup_enabled

boolean

credit_limit

number

currency

string

customer_id

string

low_balance_threshold

number

max_balance

number

max_single_credit

number

Create a wallet › Responses

Wrapped in data envelope

object

auto_topup_enabled

boolean

object

created_at

string

object

currency

string

customer_id

string

object

id

string

is_primary

boolean

object

mode

string · enum

Enum values:

PREPAID

POSTPAID

organization_id

string

object

promotional_balance_expires_at

string

updated_at

string

POST/wallets

curl --request POST \
  --url https://api.kontorion.eu/v1/wallets \
  --header 'Content-Type: application/json' \
  --data '
{
  "auto_topup_amount": 0,
  "auto_topup_enabled": true,
  "credit_limit": 0,
  "currency": "currency",
  "customer_id": "customer_id",
  "low_balance_threshold": 0,
  "max_balance": 0,
  "max_single_credit": 0
}
'

shell

Example Request Body

{
  "auto_topup_amount": 0,
  "auto_topup_enabled": true,
  "credit_limit": 0,
  "currency": "currency",
  "customer_id": "customer_id",
  "low_balance_threshold": 0,
  "max_balance": 0,
  "max_single_credit": 0
}

json

Example Responses

{
  "key": {
    "auto_topup_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_topup_enabled": true,
    "cash_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "created_at",
    "credit_limit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "currency": "currency",
    "customer_id": "customer_id",
    "held_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "id": "id",
    "is_primary": true,
    "low_balance_threshold": {
      "currency": "EUR",
      "value": "49.5"
    },
    "max_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "max_single_credit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "metadata": {
      "key": {}
    },
    "mode": "PREPAID",
    "organization_id": "organization_id",
    "promotional_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "promotional_balance_expires_at": "promotional_balance_expires_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Get a wallet by ID

GET

https://api.kontorion.eu/v1

/wallets/{id}

Retrieves a single wallet by its UUID

Get a wallet by ID › path Parameters

id

string · required

Wallet UUID

Get a wallet by ID › Responses

Wrapped in data envelope

object

auto_topup_enabled

boolean

object

created_at

string

object

currency

string

customer_id

string

object

id

string

is_primary

boolean

object

mode

string · enum

Enum values:

PREPAID

POSTPAID

organization_id

string

object

promotional_balance_expires_at

string

updated_at

string

GET/wallets/{id}

curl --request GET \
  --url https://api.kontorion.eu/v1/wallets/:id

shell

Example Responses

{
  "key": {
    "auto_topup_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_topup_enabled": true,
    "cash_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "created_at",
    "credit_limit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "currency": "currency",
    "customer_id": "customer_id",
    "held_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "id": "id",
    "is_primary": true,
    "low_balance_threshold": {
      "currency": "EUR",
      "value": "49.5"
    },
    "max_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "max_single_credit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "metadata": {
      "key": {}
    },
    "mode": "PREPAID",
    "organization_id": "organization_id",
    "promotional_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "promotional_balance_expires_at": "promotional_balance_expires_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Adjust a wallet balance

POST

https://api.kontorion.eu/v1

/wallets/{id}/adjust

Applies an adjustment to a wallet balance (positive or negative)

Adjust a wallet balance › path Parameters

id

string · required

Wallet UUID

Adjust a wallet balance › Request Body

amount

number

positive or negative

reason

string

reference

string

source

string · enum

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

Adjust a wallet balance › Responses

Wrapped in data envelope

object

created_at

string

created_by

string

id

string

organization_id

string

reason

string

reference

string

reverse_charge

boolean

source

string · enum

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

object

tax_rate

number

tax_rule_id

string

type

string · enum

Enum values:

CREDIT

DEBIT

ADJUSTMENT

wallet_id

string

POST/wallets/{id}/adjust

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

shell

Example Request Body

{
  "amount": 0,
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}

json

Example Responses

{
  "key": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "balance_after": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "created_at",
    "created_by": "created_by",
    "id": "id",
    "organization_id": "organization_id",
    "reason": "reason",
    "reference": "reference",
    "reverse_charge": true,
    "source": "PAYMENT",
    "tax_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "tax_rate": 0,
    "tax_rule_id": "tax_rule_id",
    "type": "CREDIT",
    "wallet_id": "wallet_id"
  }
}

json

application/json

Credit a wallet

POST

https://api.kontorion.eu/v1

/wallets/{id}/credit

Adds funds to a wallet, creating a credit transaction

Credit a wallet › path Parameters

id

string · required

Wallet UUID

Credit a wallet › Request Body

amount

number

expires_at

string

reason

string

reference

string

source

string · enum

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

Credit a wallet › Responses

Wrapped in data envelope

object

created_at

string

created_by

string

id

string

organization_id

string

reason

string

reference

string

reverse_charge

boolean

source

string · enum

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

object

tax_rate

number

tax_rule_id

string

type

string · enum

Enum values:

CREDIT

DEBIT

ADJUSTMENT

wallet_id

string

POST/wallets/{id}/credit

curl --request POST \
  --url https://api.kontorion.eu/v1/wallets/:id/credit \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 0,
  "expires_at": "expires_at",
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}
'

shell

Example Request Body

{
  "amount": 0,
  "expires_at": "expires_at",
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}

json

Example Responses

{
  "key": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "balance_after": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "created_at",
    "created_by": "created_by",
    "id": "id",
    "organization_id": "organization_id",
    "reason": "reason",
    "reference": "reference",
    "reverse_charge": true,
    "source": "PAYMENT",
    "tax_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "tax_rate": 0,
    "tax_rule_id": "tax_rule_id",
    "type": "CREDIT",
    "wallet_id": "wallet_id"
  }
}

json

application/json

Debit a wallet

POST

https://api.kontorion.eu/v1

/wallets/{id}/debit

Withdraws funds from a wallet, creating a debit transaction

Debit a wallet › path Parameters

id

string · required

Wallet UUID

Debit a wallet › Request Body

amount

number

reason

string

reference

string

source

string · enum

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

Debit a wallet › Responses

Wrapped in data envelope

object

created_at

string

created_by

string

id

string

organization_id

string

reason

string

reference

string

reverse_charge

boolean

source

string · enum

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

object

tax_rate

number

tax_rule_id

string

type

string · enum

Enum values:

CREDIT

DEBIT

ADJUSTMENT

wallet_id

string

POST/wallets/{id}/debit

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

shell

Example Request Body

{
  "amount": 0,
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}

json

Example Responses

{
  "key": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "balance_after": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "created_at",
    "created_by": "created_by",
    "id": "id",
    "organization_id": "organization_id",
    "reason": "reason",
    "reference": "reference",
    "reverse_charge": true,
    "source": "PAYMENT",
    "tax_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "tax_rate": 0,
    "tax_rule_id": "tax_rule_id",
    "type": "CREDIT",
    "wallet_id": "wallet_id"
  }
}

json

application/json

Create a wallet hold

POST

https://api.kontorion.eu/v1

/wallets/{id}/hold

Places a hold on wallet funds, reserving the amount for later capture

Create a wallet hold › path Parameters

id

string · required

Wallet UUID

Create a wallet hold › Request Body

amount

number

currency

string

Currency is optional on the public hold API: when empty the wallet's currency is used. Reserve and other internal callers always pass it explicitly so a mismatch with the wallet's currency fails loudly.

expires_at

string

metric_key

string

reason

string

reference_id

string

reference_type

string

reverse_charge

boolean

subscription_id

string

SubscriptionID and MetricKey are populated by the reserve service so the (subscription_id, metric_key) pair becomes queryable. The public hold API leaves them nil - those holds are not subject to the ingest-overlap check.

tax_rate

number

tax_rule_id

string

Create 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/wallets/{id}/hold

curl --request POST \
  --url https://api.kontorion.eu/v1/wallets/:id/hold \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 0,
  "currency": "currency",
  "expires_at": "expires_at",
  "metric_key": "metric_key",
  "reason": "reason",
  "reference_id": "reference_id",
  "reference_type": "reference_type",
  "reverse_charge": true,
  "subscription_id": "subscription_id",
  "tax_rate": 0,
  "tax_rule_id": "tax_rule_id"
}
'

shell

Example Request Body

{
  "amount": 0,
  "currency": "currency",
  "expires_at": "expires_at",
  "metric_key": "metric_key",
  "reason": "reason",
  "reference_id": "reference_id",
  "reference_type": "reference_type",
  "reverse_charge": true,
  "subscription_id": "subscription_id",
  "tax_rate": 0,
  "tax_rule_id": "tax_rule_id"
}

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

List wallet holds

GET

https://api.kontorion.eu/v1

/wallets/{id}/holds

Lists pending holds for a wallet

List wallet holds › path Parameters

id

string · required

Wallet UUID

List wallet holds › Responses

List wrapped in data envelope

object[]

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

GET/wallets/{id}/holds

curl --request GET \
  --url https://api.kontorion.eu/v1/wallets/:id/holds

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

Update wallet settings

PUT

https://api.kontorion.eu/v1

/wallets/{id}/settings

Updates wallet limit and settings fields

Update wallet settings › path Parameters

id

string · required

Wallet UUID

Update wallet settings › Request Body

auto_topup_amount

number

auto_topup_enabled

boolean

auto_topup_payment_method_id

string

credit_limit

number

low_balance_threshold

number

max_balance

number

max_single_credit

number

Update wallet settings › Responses

Wrapped in data envelope

object

auto_topup_enabled

boolean

object

created_at

string

object

currency

string

customer_id

string

object

id

string

is_primary

boolean

object

mode

string · enum

Enum values:

PREPAID

POSTPAID

organization_id

string

object

promotional_balance_expires_at

string

updated_at

string

PUT/wallets/{id}/settings

curl --request PUT \
  --url https://api.kontorion.eu/v1/wallets/:id/settings \
  --header 'Content-Type: application/json' \
  --data '
{
  "auto_topup_amount": 0,
  "auto_topup_enabled": true,
  "auto_topup_payment_method_id": "auto_topup_payment_method_id",
  "credit_limit": 0,
  "low_balance_threshold": 0,
  "max_balance": 0,
  "max_single_credit": 0
}
'

shell

Example Request Body

{
  "auto_topup_amount": 0,
  "auto_topup_enabled": true,
  "auto_topup_payment_method_id": "auto_topup_payment_method_id",
  "credit_limit": 0,
  "low_balance_threshold": 0,
  "max_balance": 0,
  "max_single_credit": 0
}

json

Example Responses

{
  "key": {
    "auto_topup_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_topup_enabled": true,
    "cash_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "created_at",
    "credit_limit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "currency": "currency",
    "customer_id": "customer_id",
    "held_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "id": "id",
    "is_primary": true,
    "low_balance_threshold": {
      "currency": "EUR",
      "value": "49.5"
    },
    "max_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "max_single_credit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "metadata": {
      "key": {}
    },
    "mode": "PREPAID",
    "organization_id": "organization_id",
    "promotional_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "promotional_balance_expires_at": "promotional_balance_expires_at",
    "updated_at": "updated_at"
  }
}

json

application/json

Admin-side wallet top-up

POST

https://api.kontorion.eu/v1

/wallets/{id}/topup

Tops up a customer's wallet via a Stripe charge. Accepts mode=hosted_checkout (returns a Stripe Checkout URL the admin can share with the customer) or mode=off_session (charges a saved card synchronously via a confirmed off-session PaymentIntent). The wallet is credited asynchronously via the stripe_webhook handler when Stripe reports the payment succeeded.

Admin-side wallet top-up › path Parameters

id

string · required

Wallet UUID

Admin-side wallet top-up › Request Body

object

mode

string · enum

Enum values:

hosted_checkout

off_session

payment_method_id

string

Admin-side wallet top-up › Responses

Wrapped in data envelope

client_secret

string

decline_code

string

failure_code

string

failure_message

string

mode

string · enum

Enum values:

hosted_checkout

off_session

next_action

integer[]

payment_intent_id

string

Off-session fields - populated when Mode == off_session.

session_id

string

Hosted Checkout fields - populated when Mode == hosted_checkout.

state

string

url

string

POST/wallets/{id}/topup

curl --request POST \
  --url https://api.kontorion.eu/v1/wallets/:id/topup \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "mode": "hosted_checkout",
  "payment_method_id": "payment_method_id"
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "mode": "hosted_checkout",
  "payment_method_id": "payment_method_id"
}

json

Example Responses

{
  "key": {
    "client_secret": "client_secret",
    "decline_code": "decline_code",
    "failure_code": "failure_code",
    "failure_message": "failure_message",
    "mode": "hosted_checkout",
    "next_action": [
      0
    ],
    "payment_intent_id": "payment_intent_id",
    "session_id": "session_id",
    "state": "state",
    "url": "url"
  }
}

json

application/json

List wallet transactions

GET

https://api.kontorion.eu/v1

/wallets/{id}/transactions

Lists transactions for a wallet with cursor-based pagination

List wallet transactions › path Parameters

id

string · required

Wallet UUID

List wallet transactions › query Parameters

limit

integer

Page size

cursor

string

Pagination cursor

List wallet transactions › Responses

Paginated list wrapped in data envelope

object[]

object

created_at

string

created_by

string

id

string

organization_id

string

reason

string

reference

string

reverse_charge

boolean

source

string · enum

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

object

tax_rate

number

tax_rule_id

string

type

string · enum

Enum values:

CREDIT

DEBIT

ADJUSTMENT

wallet_id

string

GET/wallets/{id}/transactions

curl --request GET \
  --url https://api.kontorion.eu/v1/wallets/:id/transactions

shell

Example Responses

{
  "key": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "balance_after": {
        "currency": "EUR",
        "value": "49.5"
      },
      "created_at": "created_at",
      "created_by": "created_by",
      "id": "id",
      "organization_id": "organization_id",
      "reason": "reason",
      "reference": "reference",
      "reverse_charge": true,
      "source": "PAYMENT",
      "tax_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "tax_rate": 0,
      "tax_rule_id": "tax_rule_id",
      "type": "CREDIT",
      "wallet_id": "wallet_id"
    }
  ]
}

json

application/json

Transfer funds between wallets

POST

https://api.kontorion.eu/v1

/wallets/{id}/transfer

Transfers funds from one wallet to another

Transfer funds between wallets › path Parameters

id

string · required

Source Wallet UUID

Transfer funds between wallets › Request Body

amount

number

reason

string

target_wallet_id

string

Transfer funds between wallets › Responses

Transfer result wrapped in data envelope

Plans Products