Wallets

Endpointhttps://api.kontier.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.kontier.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 · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

customer_id

string

Filter by customer UUID

currency

array | null · explode: true

Filter by ISO 4217 currency code (repeatable or comma-separated; OR within itself)

is_primary

string

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

auto_topup_enabled

string

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 › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List wallets › Responses

array | null · required

object · required

GET/wallets

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

shell

Example Responses

{
  "data": [
    {
      "auto_topup_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "auto_topup_enabled": true,
      "cash_balance": {
        "currency": "EUR",
        "value": "49.5"
      },
      "created_at": "2024-08-25T15:00:00Z",
      "credit_limit": {
        "currency": "EUR",
        "value": "49.5"
      },
      "currency": "currency",
      "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "held_balance": {
        "currency": "EUR",
        "value": "49.5"
      },
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "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": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "promotional_balance": {
        "currency": "EUR",
        "value": "49.5"
      },
      "promotional_balance_expires_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a wallet

POST

https://api.kontier.eu/v1

/wallets

Creates a secondary wallet for the specified customer.

Create a wallet › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a wallet › Request Body

currency

string · required

ISO 4217 currency the wallet is denominated in.

customer_id

string · uuid · required

Customer the new wallet belongs to.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

auto_topup_amount

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in this request's currency.

Example: 49.5

auto_topup_enabled

boolean

Whether the wallet auto-tops-up when its balance drops below low_balance_threshold.

credit_limit

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in this request's currency.

Example: 49.5

low_balance_threshold

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in this request's currency.

Example: 49.5

max_balance

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in this request's currency.

Example: 49.5

max_single_credit

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in this request's currency.

Example: 49.5

Create a wallet › Responses

Created

object · required

POST/wallets

curl --request POST \
  --url https://api.kontier.eu/v1/wallets \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "auto_topup_amount": "49.5",
  "auto_topup_enabled": true,
  "credit_limit": "49.5",
  "currency": "currency",
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "low_balance_threshold": "49.5",
  "max_balance": "49.5",
  "max_single_credit": "49.5"
}
'

shell

Example Request Body

{
  "auto_topup_amount": "49.5",
  "auto_topup_enabled": true,
  "credit_limit": "49.5",
  "currency": "currency",
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "low_balance_threshold": "49.5",
  "max_balance": "49.5",
  "max_single_credit": "49.5"
}

json

Example Responses

{
  "data": {
    "auto_topup_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_topup_enabled": true,
    "cash_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "credit_limit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "currency": "currency",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "held_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "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": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "promotional_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "promotional_balance_expires_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Get a wallet by ID

GET

https://api.kontier.eu/v1

/wallets/{id}

Returns a single wallet including its current cash, promotional and held balances, currency, and limit settings.

Get a wallet by ID › path Parameters

id

string · uuid · required

Wallet UUID

Get a wallet by ID › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a wallet by ID › Responses

object · required

GET/wallets/{id}

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

shell

Example Responses

{
  "data": {
    "auto_topup_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_topup_enabled": true,
    "cash_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "credit_limit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "currency": "currency",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "held_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "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": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "promotional_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "promotional_balance_expires_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Adjust a wallet balance

POST

https://api.kontier.eu/v1

/wallets/{id}/adjust

Applies an adjustment to a wallet balance (positive or negative). When the workspace requires human approval for wallet adjustments (checkpoint wallet.adjust), responds 202 with the pending approval request and applies nothing; an API-key caller is refused 409 APPROVAL_REQUIRED_HUMAN instead.

Adjust a wallet balance › path Parameters

id

string · uuid · required

Wallet UUID

Adjust a wallet balance › Headers

Idempotency-Key

string · required

Idempotency key for at-most-once processing

X-Workspace-Id

string

Workspace UUID or slug.

Adjust a wallet balance › Request Body

amount

string · pattern: ^-?\d+(\.\d+)?$ · required

Signed adjustment, MAJOR units, in the addressed wallet's currency.

Example: 49.5

source

string · enum · required

What originates the adjustment: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

currency

string

Optional echo-guard: must equal the wallet's currency when set.

reason

string · maxLength: 2000

Optional free-text explanation stored on the ledger entry.

reference

string · maxLength: 255

Optional external reference; a repeated (source, reference) is treated as an idempotent replay.

Adjust a wallet balance › Responses

required

Outcome-dependent: on 200 the posted WalletTransactionDTO; on 202 an ApprovalPendingDTO because this workspace requires human approval for wallet adjustments — nothing has been applied yet (poll GET /approvals/{id}).

POST/wallets/{id}/adjust

curl --request POST \
  --url https://api.kontier.eu/v1/wallets/:id/adjust \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": "49.5",
  "currency": "currency",
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}
'

shell

Example Request Body

{
  "amount": "49.5",
  "currency": "currency",
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "balance_after": {
      "currency": "EUR",
      "value": "49.5"
    },
    "cash_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "created_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "effect": "effect",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "promo_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "reason": "reason",
    "reference": "reference",
    "reverse_charge": true,
    "source": "PAYMENT",
    "tax_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "tax_rate": "49.5",
    "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "type": "CREDIT",
    "wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Credit a wallet

POST

https://api.kontier.eu/v1

/wallets/{id}/credit

Adds funds to a wallet, creating a credit transaction.

Credit a wallet › path Parameters

id

string · uuid · required

Wallet UUID

Credit a wallet › Headers

Idempotency-Key

string · required

Idempotency key for at-most-once processing

X-Workspace-Id

string

Workspace UUID or slug.

Credit a wallet › Request Body

amount

string · pattern: ^-?\d+(\.\d+)?$ · required

MAJOR units, in the addressed wallet's currency.

Example: 49.5

source

string · enum · required

What originates the credit: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

currency

string

Optional echo-guard: must equal the wallet's currency when set.

expires_at

string · date-time

For PROMOTION credits, when the granted promotional balance expires; null = never.

reason

string · maxLength: 2000

Optional free-text explanation stored on the ledger entry.

reference

string · maxLength: 255

Optional external reference; a repeated (source, reference) is treated as an idempotent replay.

Credit a wallet › Responses

object · required

POST/wallets/{id}/credit

curl --request POST \
  --url https://api.kontier.eu/v1/wallets/:id/credit \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": "49.5",
  "currency": "currency",
  "expires_at": "2024-08-25T15:00:00Z",
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}
'

shell

Example Request Body

{
  "amount": "49.5",
  "currency": "currency",
  "expires_at": "2024-08-25T15:00:00Z",
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "balance_after": {
      "currency": "EUR",
      "value": "49.5"
    },
    "cash_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "created_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "effect": "effect",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "promo_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "reason": "reason",
    "reference": "reference",
    "reverse_charge": true,
    "source": "PAYMENT",
    "tax_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "tax_rate": "49.5",
    "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "type": "CREDIT",
    "wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Debit a wallet

POST

https://api.kontier.eu/v1

/wallets/{id}/debit

Withdraws funds from a wallet, creating a debit transaction.

Debit a wallet › path Parameters

id

string · uuid · required

Wallet UUID

Debit a wallet › Headers

Idempotency-Key

string · required

Idempotency key for at-most-once processing

X-Workspace-Id

string

Workspace UUID or slug.

Debit a wallet › Request Body

amount

string · pattern: ^-?\d+(\.\d+)?$ · required

MAJOR units, in the addressed wallet's currency.

Example: 49.5

source

string · enum · required

What originates the debit: one of PAYMENT, REFUND, PROMOTION, INVOICE, CHARGE, FEE, MANUAL, TRANSFER.

Enum values:

PAYMENT

REFUND

PROMOTION

INVOICE

CHARGE

FEE

MANUAL

TRANSFER

currency

string

Optional echo-guard: must equal the wallet's currency when set.

reason

string · maxLength: 2000

Optional free-text explanation stored on the ledger entry.

reference

string · maxLength: 255

Optional external reference; a repeated (source, reference) is treated as an idempotent replay.

Debit a wallet › Responses

object · required

POST/wallets/{id}/debit

curl --request POST \
  --url https://api.kontier.eu/v1/wallets/:id/debit \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": "49.5",
  "currency": "currency",
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}
'

shell

Example Request Body

{
  "amount": "49.5",
  "currency": "currency",
  "reason": "reason",
  "reference": "reference",
  "source": "PAYMENT"
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "balance_after": {
      "currency": "EUR",
      "value": "49.5"
    },
    "cash_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "created_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "effect": "effect",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "promo_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "reason": "reason",
    "reference": "reference",
    "reverse_charge": true,
    "source": "PAYMENT",
    "tax_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "tax_rate": "49.5",
    "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "type": "CREDIT",
    "wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

List wallet holds

GET

https://api.kontier.eu/v1

/wallets/{id}/holds

Lists pending holds for a wallet.

List wallet holds › path Parameters

id

string · uuid · required

Wallet UUID

List wallet holds › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List wallet holds › Responses

array | null · required

object · required

GET/wallets/{id}/holds

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

shell

Example Responses

{
  "data": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "captured_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "captured_at": "2024-08-25T15:00:00Z",
      "created_at": "2024-08-25T15:00:00Z",
      "currency": "currency",
      "exchange_rate_base_leg_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "exchange_rate_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "expires_at": "2024-08-25T15:00:00Z",
      "fx_policy_applied": "fx_policy_applied",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "metric_key": "metric_key",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "promo_discounts": [
        {
          "amount": "49.5",
          "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
        }
      ],
      "reason": "reason",
      "reference_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "reference_type": "reference_type",
      "resolved_at": "2024-08-25T15:00:00Z",
      "reverse_charge": true,
      "status": "PENDING",
      "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "tax_rate": "49.5",
      "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "voided_at": "2024-08-25T15:00:00Z",
      "wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a wallet hold

POST

https://api.kontier.eu/v1

/wallets/{id}/holds

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

Create a wallet hold › path Parameters

id

string · uuid · required

Wallet UUID

Create a wallet hold › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a wallet hold › Request Body

amount

string · pattern: ^-?\d+(\.\d+)?$ · required

MAJOR units, in the hold's currency (the currency field, else the wallet's).

Example: 49.5

expires_at

string · date-time · required

When the wallet auto-releases the hold if it has not been captured.

reason

string · maxLength: 2000 · required

Free-text explanation of what the hold reserves for.

currency

string

ISO 4217 currency of the hold; when empty the addressed wallet's currency is used.

exchange_rate_base_leg_id

string · uuid

For a triangulated cross-pair rate, the EUR→source FX snapshot the rate was divided by; set by the reserve service, null via the public hold API.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

exchange_rate_id

string · uuid

FX snapshot that supplied the rate this hold was valued at; set by the reserve service, null via the public hold API.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

fx_policy_applied

string

FX timing policy that selected the rate; set by the reserve service, null via the public hold API.

metric_key

string

Metric key of the usage stream this hold reserves capacity for; set by the reserve service, null via the public hold API.

array | null

Promotions that reduced this hold's amount up-front; set by the reserve service, never via the public hold API.

reference_id

string · uuid

Identifier of the record this hold reserves against; paired with reference_type.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

reference_type

string · maxLength: 100

Type of the record this hold reserves against; paired with reference_id.

reverse_charge

boolean

True when the captured amount is subject to VAT reverse-charge.

subscription_id

string · uuid

Subscription whose usage stream this hold reserves capacity for; set by the reserve service, null via the public hold API.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

tax_rate

string · pattern: ^-?\d+(\.\d+)?$

Tax rate to apply at capture, as a decimal fraction (0.19 = 19%).

Example: 49.5

tax_rule_id

string · uuid

Tax rule to apply when this hold is captured; null for an untaxed hold.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

Create a wallet hold › Responses

Created

object · required

POST/wallets/{id}/holds

curl --request POST \
  --url https://api.kontier.eu/v1/wallets/:id/holds \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": "49.5",
  "currency": "currency",
  "exchange_rate_base_leg_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "exchange_rate_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "expires_at": "2024-08-25T15:00:00Z",
  "fx_policy_applied": "fx_policy_applied",
  "metric_key": "metric_key",
  "promo_discounts": [
    {
      "amount": "49.5",
      "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "reason": "reason",
  "reference_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "reference_type": "reference_type",
  "reverse_charge": true,
  "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "tax_rate": "49.5",
  "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
'

shell

Example Request Body

{
  "amount": "49.5",
  "currency": "currency",
  "exchange_rate_base_leg_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "exchange_rate_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "expires_at": "2024-08-25T15:00:00Z",
  "fx_policy_applied": "fx_policy_applied",
  "metric_key": "metric_key",
  "promo_discounts": [
    {
      "amount": "49.5",
      "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "reason": "reason",
  "reference_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "reference_type": "reference_type",
  "reverse_charge": true,
  "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "tax_rate": "49.5",
  "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

json

Example Responses

{
  "data": {
    "amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "captured_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "captured_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z",
    "currency": "currency",
    "exchange_rate_base_leg_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "exchange_rate_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "expires_at": "2024-08-25T15:00:00Z",
    "fx_policy_applied": "fx_policy_applied",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "metric_key": "metric_key",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "promo_discounts": [
      {
        "amount": "49.5",
        "promotion_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
      }
    ],
    "reason": "reason",
    "reference_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "reference_type": "reference_type",
    "resolved_at": "2024-08-25T15:00:00Z",
    "reverse_charge": true,
    "status": "PENDING",
    "subscription_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "tax_rate": "49.5",
    "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "voided_at": "2024-08-25T15:00:00Z",
    "wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Make a wallet the customer's primary

POST

https://api.kontier.eu/v1

/wallets/{id}/primary

Promotes this wallet to be its customer's primary wallet and demotes the previous one, atomically. The primary wallet is what invoice settlement falls back to when the customer holds no wallet in the invoice's currency, the preferred funding source when cross-currency settlement is enabled, and the wallet the customer portal shows billing settings for. A customer whose billing currency has changed will still hold a primary wallet in the old currency until this is called - opening a wallet in the new currency does not promote it. Promoting the wallet that is already primary succeeds and changes nothing.

Make a wallet the customer's primary › path Parameters

id

string · uuid · required

Wallet UUID

Make a wallet the customer's primary › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Make a wallet the customer's primary › Responses

object · required

POST/wallets/{id}/primary

curl --request POST \
  --url https://api.kontier.eu/v1/wallets/:id/primary \
  --header 'Idempotency-Key: <string>'

shell

Example Responses

{
  "data": {
    "auto_topup_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_topup_enabled": true,
    "cash_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "credit_limit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "currency": "currency",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "held_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "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": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "promotional_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "promotional_balance_expires_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Update wallet settings

PATCH

https://api.kontier.eu/v1

/wallets/{id}/settings

Updates wallet limit and settings fields.

Update wallet settings › path Parameters

id

string · uuid · required

Wallet UUID

Update wallet settings › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update wallet settings › Request Body

auto_topup_amount

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in the wallet's currency.

Example: 49.5

auto_topup_enabled

boolean

Whether the wallet auto-tops-up when it drops below low_balance_threshold.

auto_topup_payment_method_id

string · uuid

Payment method charged for auto-topups.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

credit_limit

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in the wallet's currency.

Example: 49.5

currency

string

Optional echo-guard: must equal the wallet's currency when set.

low_balance_threshold

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in the wallet's currency.

Example: 49.5

max_balance

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in the wallet's currency.

Example: 49.5

max_single_credit

string · pattern: ^-?\d+(\.\d+)?$

MAJOR units, in the wallet's currency.

Example: 49.5

Update wallet settings › Responses

object · required

PATCH/wallets/{id}/settings

curl --request PATCH \
  --url https://api.kontier.eu/v1/wallets/:id/settings \
  --header 'Content-Type: application/json' \
  --data '
{
  "auto_topup_amount": "49.5",
  "auto_topup_enabled": true,
  "auto_topup_payment_method_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "credit_limit": "49.5",
  "currency": "currency",
  "low_balance_threshold": "49.5",
  "max_balance": "49.5",
  "max_single_credit": "49.5"
}
'

shell

Example Request Body

{
  "auto_topup_amount": "49.5",
  "auto_topup_enabled": true,
  "auto_topup_payment_method_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "credit_limit": "49.5",
  "currency": "currency",
  "low_balance_threshold": "49.5",
  "max_balance": "49.5",
  "max_single_credit": "49.5"
}

json

Example Responses

{
  "data": {
    "auto_topup_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "auto_topup_enabled": true,
    "cash_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "credit_limit": {
      "currency": "EUR",
      "value": "49.5"
    },
    "currency": "currency",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "held_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "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": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "promotional_balance": {
      "currency": "EUR",
      "value": "49.5"
    },
    "promotional_balance_expires_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Admin-side wallet top-up

POST

https://api.kontier.eu/v1

/wallets/{id}/topup

Tops up a customer's wallet via a Stripe charge. Accepts mode=hosted_checkout (returns a Stripe Checkout URL) or mode=off_session (charges a saved card synchronously). The wallet is credited asynchronously when Stripe reports the payment succeeded.

Admin-side wallet top-up › path Parameters

id

string · uuid · required

Wallet UUID

Admin-side wallet top-up › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Admin-side wallet top-up › Request Body

object · required

mode

string

hosted_checkout (default) or off_session

payment_method_id

string · uuid

Required for mode=off_session

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

Admin-side wallet top-up › Responses

Created

object · required

POST/wallets/{id}/topup

curl --request POST \
  --url https://api.kontier.eu/v1/wallets/:id/topup \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "mode": "mode",
  "payment_method_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "mode": "mode",
  "payment_method_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

json

Example Responses

{
  "data": {
    "client_secret": "client_secret",
    "decline_code": "decline_code",
    "failure_code": "failure_code",
    "failure_message": "failure_message",
    "mode": "mode",
    "next_action": {},
    "payment_intent_id": "payment_intent_id",
    "session_id": "session_id",
    "state": "state",
    "url": "url"
  }
}

json

application/json

List wallet transactions

GET

https://api.kontier.eu/v1

/wallets/{id}/transactions

Lists transactions for a wallet with cursor-based pagination.

List wallet transactions › path Parameters

id

string · uuid · required

Wallet UUID

List wallet transactions › query Parameters

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

List wallet transactions › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List wallet transactions › Responses

array | null · required

object · required

GET/wallets/{id}/transactions

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

shell

Example Responses

{
  "data": [
    {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "balance_after": {
        "currency": "EUR",
        "value": "49.5"
      },
      "cash_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "created_at": "2024-08-25T15:00:00Z",
      "created_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "effect": "effect",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "promo_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "reason": "reason",
      "reference": "reference",
      "reverse_charge": true,
      "source": "PAYMENT",
      "tax_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "tax_rate": "49.5",
      "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "type": "CREDIT",
      "wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Transfer funds between wallets

POST

https://api.kontier.eu/v1

/wallets/{id}/transfer

Moves funds from the path wallet (source) into the body's target_wallet_id atomically: one database transaction locks both wallets and records a debit transaction on the source and a credit transaction on the target, linked by a shared transfer_id. amount is in the source wallet's currency and is drawn from promotional balance first; cross-currency transfers convert through the org's FX rate (the snapshot used is returned) and fail when no rate is configured. Transfers to the same wallet are rejected, and replaying an Idempotency-Key yields an already-processed conflict rather than a second transfer.

Transfer funds between wallets › path Parameters

id

string · uuid · required

Source wallet UUID

Transfer funds between wallets › Headers

Idempotency-Key

string · required

Idempotency key for at-most-once processing

X-Workspace-Id

string

Workspace UUID or slug.

Transfer funds between wallets › Request Body

object · required

Transfer amount as {value, currency}. currency must equal the SOURCE (path) wallet's currency; the target leg converts via the org's FX rate when currencies differ.

target_wallet_id

string · uuid · required

Wallet that receives the transfer; must belong to the same organization as the source wallet.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

reason

string · maxLength: 2000

Optional free-text explanation stored on both ledger legs of the transfer.

Transfer funds between wallets › Responses

object · required

POST/wallets/{id}/transfer

curl --request POST \
  --url https://api.kontier.eu/v1/wallets/:id/transfer \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "reason": "reason",
  "target_wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}
'

shell

Example Request Body

{
  "amount": {
    "currency": "EUR",
    "value": "49.5"
  },
  "reason": "reason",
  "target_wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

json

Example Responses

{
  "data": {
    "converted_amount": {
      "currency": "EUR",
      "value": "49.5"
    },
    "credit_transaction": {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "balance_after": {
        "currency": "EUR",
        "value": "49.5"
      },
      "cash_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "created_at": "2024-08-25T15:00:00Z",
      "created_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "effect": "effect",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "promo_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "reason": "reason",
      "reference": "reference",
      "reverse_charge": true,
      "source": "PAYMENT",
      "tax_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "tax_rate": "49.5",
      "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "type": "CREDIT",
      "wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    },
    "debit_transaction": {
      "amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "balance_after": {
        "currency": "EUR",
        "value": "49.5"
      },
      "cash_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "created_at": "2024-08-25T15:00:00Z",
      "created_by": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "effect": "effect",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "promo_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "reason": "reason",
      "reference": "reference",
      "reverse_charge": true,
      "source": "PAYMENT",
      "tax_amount": {
        "currency": "EUR",
        "value": "49.5"
      },
      "tax_rate": "49.5",
      "tax_rule_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "type": "CREDIT",
      "wallet_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    },
    "exchange_rate_used": {
      "created_at": "2024-08-25T15:00:00Z",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "rate": {},
      "snapshot_date": "2026-07-01",
      "source": "source",
      "source_currency": "source_currency",
      "target_currency": "target_currency"
    },
    "transfer_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Plans Credit Notes