Customer Payment Applications Realtime-enabled

The application lines of a receivable document. Each row applies part of the amount to one posted document, a sales invoice for a payment and a sales credit memo for a refund. It is a nested collection you address under a parent, not on its own: customerPayments({id})/customerPaymentApplications. The same line collection is reused by customerPayments, customerCreditMemos, customerInvoices, customerRefunds, and employeePayments.

Apply by your own key

Point each line at the document it settles with either appliesToInvoiceNumber (the Business Central posted-document number) or appliesToInvoiceIntegrationId. A resolver that finds the posted document by your store's own Integration Id, so you can settle without a lookup round-trip.

The parent decides which document class your key is looked up in. A payment resolves against posted sales invoices. A refund resolves against posted sales credit memos, because that is what a refund settles. Send a refund the integrationId of a posted credit memo and it resolves when you POST the line, with no trip through Awaiting Invoice.

Invoices and credit memos this API raised itself count too. A customer invoice or customer credit memo posts through the general journal, so no posted sales document exists for it; the key still resolves, from the Processed Documents history, to the document number its ledger entry carries. SmartConnect can settle a receivable it created with the same integrationId it created it with, whichever endpoint raised it.

The document your key resolves to must also belong to the parent's own customer. Another customer's document is rejected as you POST, naming the customer it belongs to, rather than at processing time.

A line with no target is the on-account line

Leave both appliesToInvoiceNumber and appliesToInvoiceIntegrationId off a line and it still posts, against the party with nothing applied to it. That is how you park part of a payment on the customer's account deliberately, with a comment that becomes the journal line description.

The engine writes the same line for you when the applications total less than the parent amount: the shortfall posts on account as one more line, carrying the header description instead of a comment. Both are one mechanism, so a remainder you write and a remainder the engine adds reach the ledger identically. See Journal Wrappers.

Several rows, one ledger entry

Rows that name an invoice are settled together: the payment posts one customer ledger entry for the applied total, and each invoice closes against it. That is why a comment reaches the journal line description only on an unapplied row, or on a payment settling a single invoice. One row's note cannot describe an entry that settles four. Every comment is kept against the processed document in the eOne Processed Documents history.

Application targets must be open

Standard Business Central only ever offers open entries when you register a payment, and these lines hold to the same rule. An application is rejected when the document it names is closed, meaning it has already been fully settled, and when the amount applied to a target is more than the amount still remaining on it.

Several rows may settle one document, and they are added together before that comparison. Sending 60 and 30 against an invoice with 100 left on it is a legitimate split, and posts as one settlement of 90. Sending 60 and 60 is an over-application of the same invoice and is refused, even though each row would fit on its own. Rows naming the document by number and rows naming it by appliesToInvoiceIntegrationId count towards the same total. The rejection names the document, what remains on it and the total your rows applied, so you can see which of them to reduce.

Both checks live in the processing engine, so the API and the Payment Applications page in Business Central reject the same lines, and that page's lookup offers only the payer's open entries with the amount remaining on each. A cross-currency application is converted at the posting exchange rate, so the amount comparison is left to posting in that case.

An appliesToInvoiceIntegrationId that resolves to a closed document reports that it is closed. It is never parked as Awaiting Invoice, which would leave you waiting on an invoice that has already posted and been settled.