Utility bill payment via PayAmerica, LLC's Electronic Bill Payment System — biller lookup, bill scanning, payment posting and daily reconciliation. Served by the pointskash-api-facade, not by this service.
Upstream, this is not an HTTP API. Every operation below is one XML document
written to a raw TLS socket and terminated with a NUL byte, answered the same way
on the same connection. Access is two things: the sending host's egress IP on PayAmerica's
allowlist, and an Agent ID inside every document — their server does not request a client
certificate. The facade holds the Agent ID, frames the document, and parses the reply back
to JSON — so from here it is an ordinary REST surface.
Test and production differ only by port. PayAmerica serves both from one
hostname — 10007 is the test system, 20007 is production — so a
single mistyped digit is the difference between a test payment and a real utility bill. The
facade treats any non-test port as production and refuses to boot on it unless
PAYAMERICA_ALLOW_PRODUCTION=true is set deliberately.
/health
reports the resolved port and environment.
Testing: the facade defaults to a deterministic stub that models
all seven operations, so the whole journey runs with no credentials — search a
biller, scan, post a payment, cancel it, reconcile the day. Switch to the real service with
PAYAMERICA_MODE=live plus PAYAMERICA_AGENT_ID, from a host whose
egress IP PayAmerica has allowlisted.
/api/payamerica/operations
lists every operation and serves PayAmerica's full error-code table.
Worth knowing before you integrate: the normal sequence is Retrieve Biller
(or Biller Search) → Pre-Transaction → Post-Transaction, and Pre-Transaction is skipped
entirely when there is no bill to scan. ClientTranID is the idempotency key —
reusing one is a 409 — and it is also the handle Cancel needs afterwards, so
derive it from the business event and persist it before calling. (Spec v1.0 calls
it AgentTranID; that spelling is still accepted.) Post-Transaction is what bills the agent; transactions are charged
the morning after they are entered, which is also when Cancel stops working. Amounts are
decimal strings ("110.58"), not minor units. Do not send
AgentID — it chooses who gets billed, so the facade injects its own and rejects
any you supply.
Provenance: request shapes match PayAmerica's own validated sample documents; response shapes are read from "PointKash API ver 1.0" and confirmed only as far as live calls have exercised them.