---
title: "Report bank settlement of observed ERP payments"
method: POST
path: "/v1/guard/payments/settlements"
---

# Report bank settlement of observed ERP payments

`POST /v1/guard/payments/settlements`

## Request

- Base URL: `https://api.decionis.com`
- URL: `https://api.decionis.com/v1/guard/payments/settlements`
- Auth: API key in header `X-Decionis-API-Key`

After posting, the native ERP shell reports whether each observed payment has been matched to a bank statement. Commerce Gate records drift when a payment stays unsettled past the company's window (payment_unsettled, cleared once it settles or is voided) or settles at a different amount than it posted (payment_settled_mismatch, which a person reviews). Business Central uses the same current workspace key and full native_context checks as payment validation. Each item must match a saved posted OBSERVE anchor, including its exact entry_id, payment, vendor, amount and currency. event_id and sequence are immutable per-payment event identity; exact retries do not count twice, stale sequences do not change drift, and settled or voided payments cannot reopen. Reusing an event identity with different facts returns 409; a batch commits atomically. The envelope timestamp is excluded from event identity and is not an independently verified occurrence time. F&SCM retains its existing credential/tenant behavior. Nothing is sent to Decionis, no account data crosses the boundary, and nothing moves money. A 503 means the report was not recorded and the ERP should retry. This is an unreleased source candidate.

## Headers

- `X-ERP-Region` string, required

## Request body

- PaymentSettlementRequest
  - `erp_type` 'D365_BC' | 'D365_FSCM', required
  - `tenant_id` string, uuid, required
  - `native_context` NativeContext: Pinned non-secret expectations from the registered connection. Organization and workspace fields are assertions only; the current workspace key supplies authority. workspace_environment is Core's current classification of its synchronized Accounts workspace, not refreshed provider evidence, and is distinct from environment_name.
    - `version` 'commerce-native-context-v1', required
    - `org_id` string, uuid, required
    - `workspace_environment` 'sandbox' | 'production', required
    - `connection_id` string, uuid, required
    - `expected_revision` integer, required
    - `environment_name` string, required
    - `company_id` string, uuid, required
  - `timestamp` string, date-time, required
  - `settlements` object[], required
    - `event_id` string, uuid
    - `sequence` integer
    - `entry_id` string
    - `transaction_id` string, required
    - `payment_id` string, required
    - `vendor_id` string, required
    - `posted_amount` number, required
    - `currency` string, required
    - `status` 'settled' | 'unsettled' | 'voided', required
    - `days_unsettled` integer
    - `settled_amount` number
    - `settled_at` string, date-time
    - `statement_id` string

## Response `200`

The settlements recorded

- PaymentSettlementResponse
  - `accepted` integer, required
  - `native_context` NativeConnectionContext: Current registered company metadata checked by Core. It does not verify payment facts through Microsoft, refresh provider authority, or grant posting permission.
    - `version` 'commerce-native-context-v1', required
    - `org_id` string, uuid, required
    - `workspace_environment` 'sandbox' | 'production', required
    - `connection_id` string, uuid, required
    - `expected_revision` integer, required
    - `environment_name` string, required
    - `company_id` string, uuid, required
    - `erp_type` 'D365_BC', required
    - `tenant_id` string, uuid, required
    - `basis` 'persisted_connection_and_native_grant', required
    - `provider_read_authority` 'not_checked', required
    - `execution_available` boolean, required
  - `transaction_ids` string[], required

## Other responses

- `400`: Bounded error response
- `401`: Bounded error response
- `409`: Bounded error response
- `429`: Bounded error response
- `502`: Bounded error response
- `503`: Bounded error response

---

[API](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api.md) · [All operations](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api/llms.txt) · [OpenAPI document](https://skmtc.dev/decionis/apis/decionis-commerce-gate-api/revisions/9fecb7109bf8?raw)