> ## Documentation Index > Fetch the complete documentation index at: https://docs.fynn.eu/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```json theme={null} { "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](#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.** ```json theme={null} { "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 ```json theme={null} { "invoiceIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"], "disposition": "open" } ``` **Response** ```json theme={null} { "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 ```json theme={null} { "invoiceIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "ad8f1b9e-1b9e-4c4c-8f1b-9e1b9e4c4c8f" ], "disposition": "credit_wallet" } ``` **Response** ```json theme={null} { "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"`. ```json theme={null} { "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. |