Assign Invoices and Book the Remainder

POST /api/payment/bank-account-transactions/{id}/assign-with-disposition Assigns invoices to a bank account transaction and, in the same request, handles the remaining or overpaid amount according to a chosen disposition. This combines invoice assignment and remainder booking into one atomic operation, eliminating the separate follow-up step. Required permission: BankAccountTransactionWrite

Request

Path parameters

Parameter	Type	Description
`id`	string (UUID)	ID of the bank account transaction.

Request body

{
  "invoiceIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "disposition": "credit_wallet",
  "assignmentAmounts": null
}

Field	Type	Required	Description
`invoiceIds`	array of UUID strings	Yes	Invoices to assign, in assignment order. Must contain at least one entry. All IDs must exist; an unknown ID yields a 422 before anything is booked.
`disposition`	string (enum)	Yes	How to handle the remaining or overpaid amount. See Disposition values below.
`assignmentAmounts`	object (invoice ID → decimal string)	No	Optional per-invoice amount caps. Keys must be invoice IDs from `invoiceIds`. Not supported with `credit_wallet` or `credit_wallet_and_payout`: omit or send `null` when using a wallet disposition.

Disposition values

Value	Behaviour
`open`	Leaves the remainder unbooked. The transaction keeps an outstanding amount and can be assigned to further invoices later. This reproduces the behaviour of the plain assign endpoint.
`credit_wallet`	Overpays the last assigned invoice by the full remaining amount so the transaction is fully booked, then moves that overpayment to the customer’s credit balance (Guthaben). Requires all invoices to belong to a single customer.
`credit_wallet_and_payout`	Currently not available (returns 422 `payout_not_available`). Identical to `credit_wallet`, but would additionally schedule a SEPA payout of the credited amount back to the customer. Disabled pending the outbound ledger leg in the payout subsystem.

credit_wallet_and_payout returns a 422 with reason payout_not_available for every request. The disposition is accepted by the schema but blocked at the service layer until the payout subsystem books its outbound ledger leg. Use credit_wallet if you want to credit the remainder to the customer’s balance without an immediate payout.

Response

HTTP 200: Invoices assigned and remainder disposed.

{
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "STATUS_BOOKED",
  "disposition": "credit_wallet",
  "unassignedAmount": 0,
  "disposedAmount": 1000,
  "currencyCode": "EUR",
  "payoutId": null
}

Field	Type	Description
`transactionId`	string (UUID)	ID of the bank account transaction.
`status`	string	Updated status of the transaction (e.g. `STATUS_BOOKED`, `STATUS_OUTSTANDING_AMOUNT`).
`disposition`	string	The disposition that was applied (`open`, `credit_wallet`, or `credit_wallet_and_payout`).
`unassignedAmount`	integer	Remaining unassigned amount in cents after the operation. `0` when the transaction is fully booked.
`disposedAmount`	integer or null	Amount moved to the customer’s credit balance, in cents. `null` for the `open` disposition.
`currencyCode`	string	ISO 4217 currency code (e.g. `EUR`).
`payoutId`	string (UUID) or null	ID of the initiated payout. `null` unless `credit_wallet_and_payout` was used and a payout was created.

Examples

Assign one invoice and leave the remainder open

{
  "invoiceIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
  "disposition": "open"
}

Response

{
  "transactionId": "a1b2c3d4-0000-4000-8000-000000000001",
  "status": "STATUS_OUTSTANDING_AMOUNT",
  "disposition": "open",
  "unassignedAmount": 2500,
  "disposedAmount": null,
  "currencyCode": "EUR",
  "payoutId": null
}

Assign two invoices and credit the remainder to the customer’s balance

{
  "invoiceIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "ad8f1b9e-1b9e-4c4c-8f1b-9e1b9e4c4c8f"
  ],
  "disposition": "credit_wallet"
}

Response

{
  "transactionId": "a1b2c3d4-0000-4000-8000-000000000001",
  "status": "STATUS_BOOKED",
  "disposition": "credit_wallet",
  "unassignedAmount": 0,
  "disposedAmount": 1000,
  "currencyCode": "EUR",
  "payoutId": null
}

The transaction is fully booked. EUR 10.00 was credited to the customer’s balance (Guthaben).

Assign with per-invoice amount caps (`open` disposition)

Use assignmentAmounts when you want to assign a specific partial amount per invoice rather than the invoice’s full outstanding balance. This is only available with disposition: "open".

{
  "invoiceIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "ad8f1b9e-1b9e-4c4c-8f1b-9e1b9e4c4c8f"
  ],
  "disposition": "open",
  "assignmentAmounts": {
    "3fa85f64-5717-4562-b3fc-2c963f66afa6": "150.00",
    "ad8f1b9e-1b9e-4c4c-8f1b-9e1b9e4c4c8f": "200.00"
  }
}

Errors

All errors follow the standard problem+json format.

HTTP status	`reason`	Description
403	(none)	The API token does not have the `BankAccountTransactionWrite` permission.
404	(none)	No bank account transaction found for the given `id` within the organisation.
422	`assignment_amounts_with_wallet_disposition`	`assignmentAmounts` was provided together with `credit_wallet` or `credit_wallet_and_payout`. Per-invoice amount caps are not supported with wallet dispositions because the remainder must be fully absorbed by the last invoice.
422	`return_transaction`	The transaction is a returned direct debit (Rücklastschrift) and cannot be assigned here.
422	`non_positive_transaction`	Wallet dispositions require an incoming (positive) transaction.
422	`no_single_payment_intent`	The last invoice has no single resolvable payment intent to book the remainder against.
422	`payout_not_available`	`credit_wallet_and_payout` was requested but is not yet available. Use `credit_wallet` instead.
422	(validation)	An invoice ID in `invoiceIds` does not exist, `invoiceIds` is empty, or `disposition` is not a valid enum value.
422	(domain)	The invoices span multiple customers. Wallet dispositions (`credit_wallet`, `credit_wallet_and_payout`) require all invoices to belong to a single customer.

API documentation

User

Tenant

Customer

Catalogue

Subscription

Invoice

Payment

Dunning

Offer

Checkout

Feature & Entitlement

Analytics

Accounting

Settings

Assign Invoices and Book the Remainder

Request

Path parameters

Request body

Disposition values

Response

Examples

Assign one invoice and leave the remainder open

Assign two invoices and credit the remainder to the customer’s balance

Assign with per-invoice amount caps (`open` disposition)

Errors

​Request

​Path parameters

​Request body

​Disposition values

​Response

​Examples

​Assign one invoice and leave the remainder open

​Assign two invoices and credit the remainder to the customer’s balance

​Assign with per-invoice amount caps (open disposition)

​Errors

Request

Path parameters

Request body

Disposition values

Response

Examples

Assign one invoice and leave the remainder open

Assign two invoices and credit the remainder to the customer’s balance

Assign with per-invoice amount caps (`open` disposition)

Errors