Assign Invoices and Book the Remainder

Assign one or more invoices to a bank account transaction and immediately dispose of any remaining or overpaid amount in a single request.

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.