Vendor Payments Realtime-enabled

Record money paid out to a vendor as its own header/line document, a payment with a vendorPaymentApplications child collection (the posted purchase invoices it settles). Same model as Customer Payments on the AP side: backed by a dedicated staging table, so it reads and writes like a document and can be reviewed and approved before it reaches the ledger.

Shape

• Resolve the vendor with vendorNumber or vendorIntegrationId. See Resolver fields.
• Set the cash side with balancingAccountNumber, the bank or G/L account the money was paid from, resolved polymorphically by account type (same pattern as Journals).
• POST applications under vendorPayments(<id>)/vendorPaymentApplications. They may total less than the header amount, and the difference stays on the vendor's account; they may never total more.

Processing is configurable: nothing posts by default

How a staged payment reaches the ledger is set per endpoint in the Journal Wrappers section of the eOne Integration Setup page:

• Manual (default). The payment stays in staging until you call the process action (or a user processes it on the in-product eOne Ledger Documents page). process fans each application into one applied journal line plus a single bank/cash line as an unposted draft for review in Business Central.
• Auto Draft to Journal. A background job builds those draft lines automatically, shortly after the document stops changing.
• Auto Post. The job builds and posts them; the whole distribution commits or rolls back as a unit.

Bound actions

Invoke with POST /vendorPayments(<id>)/Microsoft.NAV.<action>:

• validate: re-runs the document's checks (vendor, balancing account, applications not exceeding the header) without processing it, surfacing any problem into status / errorMessage. An over-applied payment is rejected here, not left for process to discover. The response redirects back to the payment.
• process: turns the staged payment into journal lines (an unposted draft, or posted, per the Setup policy above).
• post: processes the payment and posts it, whatever the Setup policy says. Use it when SmartConnect decides that this one payment goes to the ledger now, rather than an administrator putting the whole endpoint on Auto Post. Only the lines this payment just wrote are posted, so other drafts sitting in the same journal batch are left alone, and the approval gate applies exactly as it does to process.

process and post return no body. The staged payment deletes itself the moment its journal lines exist, so there is nothing to echo, and the outcome lives on the Processed Documents row the same call wrote. Fetch it by the integrationId you sent the payment with - processedDocuments?$filter=integrationId eq '<your id>' - and read postedDocumentNumber, postedPostingDate, glTransactionNumber and status; after post they are already filled in. validate writes nothing and points back at the staged payment. A rejected call returns the error and leaves the payment in staging, with errorMessage describing the problem, ready to correct and retry. See Journal Wrappers.

Dimensions are on the payment, not the line

Set shortcutDimension1Code–8Code on the payment header. A payment is one cash movement, so the codes are applied to every generated journal line, folding into each line's dimension set when it processes. See Dimensions.

Applying to invoices

Applications settle the payment against posted purchase invoices, one row each, pointed at their invoice by your own key or the Business Central number. See Vendor Payment Applications for how a line resolves and applies.

A payment settling several invoices posts one vendor ledger entry for the money paid out, and the invoices close underneath it. The supplier's account shows the one payment you made, not one per invoice. Remittance details on the header ride that single line. See Journal Wrappers.

Part payments leave the difference on account

The rows do not have to add up to the header amount. Pay a supplier 1,000 against an 850 invoice and process moves the whole 1,000 out of the bank, settles the 850 and posts the remaining 150 against the vendor unapplied, ready for their next invoice. Only the reverse is refused, applications totalling more than the payment, and the rejection names both figures.

You can also write that remainder yourself, as an application line with no invoice on it and a comment explaining it. It posts exactly the same way, so use it when the remainder needs a note on the ledger entry.

Pay before the invoice has posted

When the environment allows it (the Allow Payments Before Invoice Posts setting), you can stage a payment whose appliesToInvoiceIntegrationId points at a purchase invoice that has not posted yet: the payment is held with status = Awaiting Invoice and is applied automatically as soon as that invoice posts. With the setting off, an unknown invoice key is rejected on write. A key that resolves to an already-settled invoice is rejected as closed rather than held here.

Reading the outcome from the payload

Four read-only roll-ups come back with every read and every write, so SmartConnect can judge the payment from the response instead of the English text in errorMessage:

• appliedAmount: the sum of the application lines. It may sit below amount, and the difference is left on the vendor's account; above amount the document is rejected. Compare the two yourself when an exact match is what your process requires.
• numberOfApplications: how many application lines the payment has.
• applicationsResolved: how many of them already point at a posted document and are ready to apply.
• applicationsAwaitingInvoice: how many still name a document that has not posted. This is the count behind status = Awaiting Invoice, and it separates "one line of four is waiting" from "all four are".
• reopen: returns a failed payment to Open and clears its error, handing it back to the background job. A payment that hits status = Error is not collected again on its own, so on an Auto endpoint - where by definition nothing calls process - this is how a corrected payment gets moving. It refuses a payment that is pending approval, exactly as the Business Central action does.

appliedAmount is this family's equivalent of the totalAmount on Expenses and Bank / G/L Entries. Both are the sum of the child lines; only a ledger document also carries a header amount to check them against, which is why the name here says what the lines did. See Journal Wrappers.

What a PATCH may do

Two rules apply to every write, on the header and on its lines and applications alike.

A payment under approval cannot be changed. Once status is Pending Approval or Approved, a PATCH, a line append or a delete is rejected. What the approver signed off on is what posts. Call reopen first if the payment genuinely has to change; that is an explicit act rather than a silent revocation, and it leaves no orphaned approval entry behind.

Deleting is also a setup choice. A DELETE of a staged payment is refused when the endpoint's Allow Manual Delete switch is off on the eOne Integration Setup page. It is on by default, so nothing changes until an administrator turns it off to mark the whole document family integration-owned. The approval rule above holds regardless of the switch.

Correcting a failed payment clears its error. Any successful write to a payment whose status is Error returns it to Open and empties errorMessage, so it becomes visible to the background job again - a line or application write counts, because the failure is usually in a line. The full text of every failed attempt is kept separately and is not lost when the live message is cleared. Awaiting Invoice is left alone: that one heals itself when the invoice posts.