# Vendor Payments _(Realtime-enabled)_

`GET` `POST` `PATCH` `DELETE` _(Table: EONE Transaction)_

```
eOne/core/v1.0/vendorPayments
```

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](https://eonesolutions.github.io/eone-bc-integration/core-customerPayments.md) 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](https://eonesolutions.github.io/eone-bc-integration/resolvers.md).
- 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](https://eonesolutions.github.io/eone-bc-integration/core-journals.md)).
- 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](https://eonesolutions.github.io/eone-bc-integration/core-processedDocuments.md) 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](https://eonesolutions.github.io/eone-bc-integration/journal-wrappers.md).

> **Note:** Approval is not done through the API. When an endpoint has **Requires Approval** set and a Business Central approval workflow is enabled for eOne documents, a payment must be **Approved** before it processes. A licensed user sends it for approval and approves it in Business Central, on the *eOne Ledger Documents* page (**Send Approval Request**, then the standard Approve/Reject/Delegate), backed by Approval User Setup. The read-only `status` (Open → Pending Approval → Approved) and `errorMessage` fields report where the document is; a failed automatic attempt lands `status` = Error with the reason in `errorMessage`.

## 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](https://eonesolutions.github.io/eone-bc-integration/dimensions.md).

## 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](https://eonesolutions.github.io/eone-bc-integration/core-vendorPaymentApplications.md) 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](https://eonesolutions.github.io/eone-bc-integration/journal-wrappers.md).

### 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.

> **Note:** To reconcile which payments have settled which invoices, pull the read-only [`vendorPaymentsQuery`](https://eonesolutions.github.io/eone-bc-integration/reports-queries.md).

## 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](https://eonesolutions.github.io/eone-bc-integration/core-expenses.md) and [Bank / G/L Entries](https://eonesolutions.github.io/eone-bc-integration/core-bankGLEntries.md). 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](https://eonesolutions.github.io/eone-bc-integration/journal-wrappers.md).

### 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.

## Vendor Payments fields

_API column → BC field._

**Legend**

- _(req)_ required on create
- _(res)_ resolver
- _(cur)_ currency-translated
- _(ro)_ read-only
- _(ext)_ added to this endpoint by another extension (BC field name shown; its API column name is not known here)

| API | BC field | Notes |
| --- | --- | --- |
| `id` | SystemId | BC record GUID. _(ro)_ |
| `bcCompanyId` | bcCompanyId | The company this row belongs to - the same GUID that appears in the request URL. Present on every endpoint so a store pooling several companies can keep them apart without relying on which URL it called. _(ro)_ |
| `bcCompanyName` | bcCompanyName | The name of the company this row belongs to. _(ro)_ |
| `vendorId` | vendorId | _(ro)_ |
| `vendorNumber` | vendorNumber | _(res)_ |
| `vendorIntegrationId` | vendorIntegrationId | _(res)_ |
| `vendorName` | vendorName | Name of the vendor the document is for. _(ro)_ |
| `documentNumber` | Document No. | Payment document number. |
| `postingDate` | Posting Date | Date the payment posts to. |
| `pricesIncludeTax` | Prices Include Tax | Whether line amounts already include tax. Off (default): a line's amount is the taxable base and its taxAmount is added on top, so the line costs the document amount + tax. On: the tax is already inside the line amount and is carved back out, so the line costs the document its amount. This says only what the numbers MEAN - the tax figure itself always comes from the line's taxAmount, never from Business Central's own rate. See Journal Wrappers. |
| `documentDate` | Document Date | The document's own date; defaults to the posting date when left blank. |
| `externalDocumentNumber` | External Document No. | Caller's reference number. |
| `yourReference` | Your Reference | The payee's own reference; flows onto the resulting journal line and posted ledger entries. |
| `currencyCode` | currencyCode | ISO code; blank is LCY. _(cur)_ |
| `balancingAccountType` | Bal. Account Type | Cash side: bank or G/L account. |
| `balancingAccountId` | balancingAccountId | GUID of the resolved bank/G/L balancing account. _(ro)_ |
| `balancingAccountNumber` | Bal. Account No. | No. of the bank or G/L account the cash hits. |
| `recipientBankAccount` | Recipient Bank Account | The vendor bank account the payment is remitted to (for payment export/print). |
| `creditorNumber` | Creditor No. | Creditor reference carried on the remittance (e.g. SEPA / ISO20022 credit transfer). |
| `paymentReference` | Payment Reference | Structured payment reference carried on the remittance. |
| `bankPaymentType` | Bank Payment Type | How the payment is made: blank, Computer Check, Manual Check, or Electronic Payment. |
| `amount` | Amount | Header total. The applications may total less than this - the difference is left on the account, unapplied - but never more. |
| `appliedAmount` | Applied Amount | Sum of the application lines. Below amount the difference posts to the account unapplied; above amount the document is rejected. _(ro)_ |
| `numberOfApplications` | No. of Applications | How many application lines the document has. _(ro)_ |
| `applicationsResolved` | Applications Resolved | How many application lines already point at a posted document and are ready to apply. _(ro)_ |
| `applicationsAwaitingInvoice` | Applications Awaiting Invoice | How many application lines name a document by integrationId that has not posted yet. Greater than zero is what puts the document in status Awaiting Invoice. _(ro)_ |
| `description` | Description | Free-text description. |
| `expectedLineCount` | Expected Line Count | How many lines or applications this document will have when it is complete. Set it on the header and the document is not processed until that many have arrived, instead of waiting out the five-minute idle window - so a document built over several calls is never processed half-built, and a complete one goes through on the next cycle. Leave it blank (the default) to keep the idle-window behaviour. |
| `declaredTotalAmount` | Declared Total Amount | Optional second check on top of expectedLineCount: the total you believe the lines add up to. When set and the arrived lines do not match it, the document fails with the difference stated rather than posting. Leave it zero to skip the check. This does not change the header amount, which stays a ceiling. |
| `deductionAmount` | Deduction Amount | Amount a third party withheld from the money before it reached the bank - a card or PSP fee, a marketplace commission. Sent as a positive magnitude, and it must be less than the document amount. Requires deductionAccountNumber. Do NOT use it for realized FX, a payment discount or application rounding: Business Central posts all three itself, and a deduction on top double-posts. |
| `deductionAccountNumber` | Deduction Account No. | G/L account the withheld amount is booked to - typically bank charges or merchant fees. Required when deductionAmount is set, and rejected without it. |
| `integrationId` | EONE Integration Id | Your external key; carried onto the resulting journal lines. |
| `journalTemplateName` | Journal Template Name | General journal template the draft lines are written to. |
| `journalBatchName` | Journal Batch Name | General journal batch the draft lines are written to; must already exist. |
| `status` | Status | Workflow state: Open, Pending Approval, Approved, Awaiting Invoice or Error. _(ro)_ |
| `errorMessage` | Error Message | Why the last automatic processing attempt failed, or which invoice the payment is waiting for. _(ro)_ |
| `shortcutDimension1Code` | Shortcut Dimension 1 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension2Code` | Shortcut Dimension 2 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension3Code` | Shortcut Dimension 3 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension4Code` | Shortcut Dimension 4 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension5Code` | Shortcut Dimension 5 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension6Code` | Shortcut Dimension 6 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension7Code` | Shortcut Dimension 7 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `shortcutDimension8Code` | Shortcut Dimension 8 Code | Dimension applied to every journal line of the payment. See Dimensions. |
| `createdDateTime` | SystemCreatedAt | When the integration imported this document into staging. _(ro)_ |
| `errorDateTime` | Error Date-Time | When the document last entered Error. Cleared when it is approved or reopened. _(ro)_ |
| `lastModifiedDateTime` | SystemModifiedAt | _(ro)_ |

## Related pages

Collections nested under this endpoint:

- [Vendor Payment Applications](https://eonesolutions.github.io/eone-bc-integration/core-vendorPaymentApplications.md)
- [Distributions](https://eonesolutions.github.io/eone-bc-integration/core-distributions.md)