ASCI API - Pending Charges

Pending Charges (billing) module page - how the store works, the endpoint reference, the charge fields, the settlement pipeline status, and the settlement writeback feed. See All Forms for the combined surface or Home for the module index.

How it works

Pending-charges store + settlement read-model for the billing pipeline.

Pending Charges

The Pending Charges module is the API-side read-model of the legacy IPCHR pending charges (doc type PCHG), tenant-scoped.

The direction of traffic is:

ASCI → API (push in). ASCI pushes a batch of pending charges via POST /api/Charges/Import. It is an idempotent UPSERT keyed by tenant + (ref_no, seq_no); mode is add (skip existing) or replace (upsert; default). Provider settlement fields are preserved across a re-push.
API → payment provider (send). The outbound billing pipeline sends the charge to the payment provider for settlement (see settlement pipeline below).
API → ASCI (poll writeback). The ASCI side polls GET /api/Charges/Settlements for charges that carry a provider settlement, applies the result onto its IPCHR records, then re-imports with an advanced status to close the loop.

The billing routes and identifiers are deliberately provider-neutral - "charges", not any biller's name - so the payment provider can be swapped without a contract change. The payee is resolved against the A/P Vendors master (vendor_code). This module is ASCI only.

Settlement pipeline

Provider-neutral outbound settlement channel.

Settlement status

Outbound settlement is sent through our payment provider. The send is via a pluggable outbound handler selected by channel, so the route surface does not change when the provider does:

Channel	Handler	Status
`charges.pending`	the outbound payment handler	STUB. The payment-provider client (send + auth) is pending the provider's API spec - not yet wired to a live endpoint.

Pending the payment provider's API spec. The outbound send path is a stub today; the pending-charges store, the /api/Charges/* read model, and the settlement writeback feed are in place and work independently of which provider ultimately settles. The vendor → payee mapping is held in a provider-neutral vendor→payee map.

Endpoints

Pending Charges endpoint family (api/Charges).

Charges endpoints

Method	Path	Scope	Direction	Purpose
POST	`/api/Charges/Import`	`ipjson.submit`	ASCI → API	Push a batch of pending charges. Idempotent UPSERT on (`ref_no`, `seq_no`); `mode` = `add`\|`replace`. Returns `{ mode, inserted, updated, skipped, errors }`.
GET	`/api/Charges`	`queue.read`	read	List pending charges. Filters: `?status=&vendor_code=&customer_id=&limit=`. Returns `{count, rows}`.
GET	`/api/Charges/{refNo}/{seqNo}`	`queue.read`	read	Fetch a single charge by `ref_no` + `seq_no`. `404` if absent.
GET	`/api/Charges/Settlements`	`queue.read`	API → ASCI	Settlement writeback feed the ASCI side polls. Returns charges carrying a provider settlement (default: non-empty `settlement_status`). Filters: `?status=&settlement_status=&limit=`.

Schema

The charges[] element of POST /api/Charges/Import. Batch shape: { mode, charges[] }. The same fields are returned by the GET read endpoints, plus provider-settlement fields.

Charge record

Field	Type	Req?	Description
`ref_no`	string	Yes	`CH_REF_NO` (key).
`seq_no`	string	Yes	`CH_SEQ_NO` (key).
`vendor_code`	string	No	A/P vendor code (payee). Resolves against the Vendors master.
`charge_code`	string	No	Charge code.
`record_type`	string	No	Record type.
`amount`	number	No	Charge amount.
`billed`	string	No	Billed flag.
`customer_id`	string	No	Customer id.
`check_no`	string	No	Check number.
`date`	string	No	Charge date.
`vendor_name`	string	No	Vendor name (denormalized).
`payment_type`	string	No	Payment type.
`awb_bl_no`	string	No	AWB / B-L number.
`status`	string	No	Optional initial status (defaults to `pending`).

Settlement writeback fields (GET /api/Charges/Settlements)
Field	Type	Description
`ref_no` / `seq_no`	string	Charge key, echoed back.
`status`	string	Charge status.
`provider_payment_id`	string	Provider-assigned payment id.
`paid_amount`	number	Amount the provider settled.
`paid_date`	string	Provider settlement date.
`settlement_status`	string	Provider settlement status (the feed filter key).
`settlement_raw`	string	Raw provider settlement payload, stored verbatim.
`updated_at`	string	Last-updated timestamp.