CHAPAYMENT programmer manual

A Windows x64 C ABI library for deterministic payment-state transitions and amount validation. This developer preview provides five exported functions. It does not perform card reading, EMV processing, network requests, persistent storage or issuer authorization.

APPROVE and RECOVER are simulator events in this release. Never use them to infer that a customer has paid. A production adapter must obtain and verify the processor’s actual result before a sale is finalized.

Package contents and requirements

The ZIP contains CHAPAYMENT.dll, card-cli.exe, these two HTML manuals and SHA256SUMS.txt. No source is included. The runtime is native x64 Windows. The DLL was built with MSVC C17, /MT, /W4 and /WX. The MSVC runtime is statically linked; this component does not require a separate Visual C++ runtime installation. No DLL registration or administrator installation is required. A 32-bit process cannot load this x64 DLL.

Load from C or C++

This binary-only distribution contains no headers, import library, examples or implementation source. Load CHAPAYMENT.dll from a trusted absolute path with LoadLibraryExW and obtain the documented exports with GetProcAddress. All functions use the C ABI and __cdecl; wchar_t arguments are Windows UTF-16. Check CA_ABIVersion returns 1. Allocate buffers in the caller and retain them until each synchronous call returns. Do not free memory across DLL boundaries.

Exported functions

SignatureContract
uint32_t CA_ABIVersion(void)Returns 1. Check this value before relying on the enum values or transition contract.
int CA_ValidateAmount(int64_t amount_minor)Returns 1 for 1 through 99,999,999 inclusive; otherwise 0. Values are integer minor units. This function does not select a currency or compute tax. It cannot validate a processor’s currency-specific rules.
int CA_Transition(int state, int event)Returns the next state. Invalid enum values return -1. Disallowed transitions return the original state; this is not a success indication. No state is saved inside the DLL.

State and event values

StateValueMeaning
CA_WAITING0Awaiting a simulated result.
CA_UNKNOWN1Uncertain outcome. Block a replacement payment until reconciliation.
CA_PAID2Terminal simulated success.
CA_DECLINED3Terminal simulated decline.
CA_CANCELLED4Terminal simulated cancellation.

Event values: APPROVE=0, DECLINE=1, TIMEOUT=2, RECOVER=3, CANCEL=4.

Current stateEventNext state
WAITINGAPPROVE / DECLINE / TIMEOUT / CANCELPAID / DECLINED / UNKNOWN / CANCELLED respectively
WAITINGRECOVERWAITING
UNKNOWNRECOVERPAID, for the simulated recovery scenario only
UNKNOWNAny other valid eventUNKNOWN
PAID, DECLINED, CANCELLEDAny valid eventUnchanged

Native Windows reader diagnostics

SignatureContract
uint32_t CA_ListReaders(wchar_t *buffer, uint32_t *chars)Returns the Windows PC/SC status code; zero means success. First pass NULL for buffer and a pointer to a zero length. Allocate the returned number of UTF-16 characters; call again. Output is MULTI_SZ terminated by two NUL characters. Handle insufficient buffer by resizing and retrying with a bound. The list can change between calls.
uint32_t CA_ProbeReader(const wchar_t *name, uint32_t *protocol)Exact PC/SC reader name and output protocol pointer. Opens a shared T=0/T=1 card connection and disconnects with LEAVE_CARD. Returns Windows status; protocol 1 is T=0, 2 is T=1. Success proves connectivity only. Does not send payment APDUs, retrieve PAN data or authorize payment.

Common result codes: 0x8010002E no readers; 0x8010001D or 0x8010001E service unavailable/stopped; 0x8010000C no card; 0x80100069 removed card; 0x80100017 unavailable reader; 0x8010000B sharing violation. Propagate other errors. Calls establish and release their own Windows context; no context is retained across calls. PC/SC may expose non-USB readers too. HID and serial devices require different adapters.

ICPP integration

The native helper supports fixed commands that ICPP can invoke with icpp_exec or icpp_exec_capture. Check icpp_exec_status after capture. Run from the helper directory or use a trusted absolute path. Never concatenate unvalidated customer data into a command string. ICPP scripts remain private and are not included in this binary download. The public native helper can run without ICPP installed.

card-cli.exe --self-test
card-cli.exe --discover
card-cli.exe --probe "Exact Windows reader name"
card-cli.exe --transition 0 2

The transition command accepts only single digits 0 through 4 for state and event. Exit 0 indicates successful command execution, not payment approval. Exit 2 indicates invalid input or a diagnostic error. Discovery may exit 0 with SERVICE_UNAVAILABLE or NO_READERS as a reported operating condition. Parse the displayed condition rather than treating exit 0 as device readiness.

Application responsibilities

  1. Authenticate the operator and bind each attempt to the restaurant, order revision, amount, currency, reader and processor account.
  2. Persist the request ID and frozen order before dispatch. Serialize writer access and exclude competing attempts for the same reader/order.
  3. Record transition and audit event atomically. The DLL does not supply persistence, retry management or database locking.
  4. Keep UNKNOWN unresolved across restart. Query the original provider payment instead of creating another charge.
  5. Finalize stock and accounting once, then enqueue receipts. Printing failure must not repeat a payment.
  6. Keep processor credentials out of the GUI and keep raw card authentication data out of logs and database records.

EPOS integration

The native EPOS Card reader diagnostics menu loads this DLL directly; it does not need Python or a local HTTP service. The earlier Python-based simulator is a legacy development path and is not part of this binary distribution. Persistent payment workflow migration to ICPP remains incomplete; this release must not be advertised as a full ICPP checkout engine.

Testing and release limits

The native tests cover ABI version, every declared state transition, invalid values and amount boundaries. Integration tests in EPOS cover simulated authorization, duplicate handling, refunds, reader contention and recovery. No physical-reader or acquirer test has passed yet. No EMV or PCI approval is claimed. The binary is unsigned; verify the supplied hash and obtain the release over the site’s HTTPS connection.

User manual