Preconditions: credentials satisfies SatimCredentials with
all fields non-empty after trim and within length limits (AN.100 / AN.16).
Merchant credentials from CIBWeb.
OptionalhttpClientService: HttpClientOptions | HttpClientServiceEither a pre-built HttpClientService (for
testing or shared connection pools) or an HttpClientOptions
object configuring the default transport.
SatimInvalidArgumentError / SatimMissingDataError
on invalid credentials (via initFromCredentials).
SatimInvalidArgumentError on invalid timeoutMs
when default transport is built.
ProtectedhttpProtectedtestProtected_Protected_Protected Optional_Protected Optional_Protected Optional_Protected Optional_Protected Optional_Protected Optional_Protected Optional_Protected Optional_Protected_ProtectedusernameMerchant username. Protected — never exposed publicly.
ProtectedpasswordMerchant password. Protected — never exposed publicly.
ProtectedterminalMerchant terminal ID. Protected — never exposed publicly.
Override to rebuild the default HTTP client when testMode changes
(the base URL is baked in at construction). A caller-injected
client is preserved verbatim — switching testMode will not
replace it.
Clone with testMode set and (if applicable) a fresh
default HttpClientService matching the new mode.
ProtectedcloneOverride to copy transport-related state alongside config state.
The base SatimConfig.clone only knows about config fields; the
Satim subclass owns httpClientService and two private flags
that must also propagate. Uses cast-to-any because the fields are
declared readonly — only the clone's constructor-equivalent
(this method) may set them.
Register a new payment order via /register.do.
Preconditions: _returnUrl and _amount are set via the fluent
setters. _amount already validated against assertRegisterAmount.
Postcondition: returns a RegisterResponse whose getOrderId and
getUrl are populated.
Retry: enabled iff _idempotencyKey is set.
Complexity: O(network).
SatimMissingDataError when required fields are absent.
SatimGatewayError on ErrorCode 1, 3, 4, 7.
SatimInvalidCredentialsError on ErrorCode 5.
SatimUnexpectedResponseError on transport failures or other non-zero error codes.
Register a pre-authorization (fund hold) via /registerPreAuth.do.
Holds the funds on the customer's card without capturing. Capture
later via confirm() or release via reverseOrder().
Same preconditions, postconditions, retry semantics, and exceptions as register.
Confirm (deposit) a payment via /public/acknowledgeTransaction.do.
Preconditions: orderId matches the strict order-ID format;
expectedAmount passes assertConfirmAmount (finite, positive,
≤ MAX_SAFE_AMOUNT, ≤ 2 decimal places).
Postcondition: returns a ConfirmResponse. When the response
satisfies isSuccessful(), verifyAmount(expectedAmount) has
already run — a mismatch throws before this method returns.
Retry: disabled. A retry could double-fire merchant side effects derived from observing the success state.
Security: this is the only safe path to confirm a payment. The automatic amount check defends against partial-capture manipulation; the call must happen server-side, never from the customer's browser.
Complexity: O(network).
SatimInvalidArgumentError on malformed orderId
or expectedAmount.
SatimUnexpectedResponseError on amount mismatch (carries the expected vs actual minor-unit values).
Query order status via /getOrderStatus.do.
Idempotent — automatically retried on transient failures (5xx, timeout).
Concurrent calls for the same orderId are collapsed into a single
in-flight request — the second caller receives the first's response
without a second round trip.
Preconditions: orderId matches the strict order-ID format.
Complexity: O(network) — but up to 1 + maxRetries round trips on
transient errors.
SatimInvalidArgumentError on malformed orderId.
Query multiple orders in parallel via concurrent /getOrderStatus.do calls.
Fires all queries simultaneously. Concurrent calls for the same orderId
are deduplicated by HttpClientService — passing duplicates in the array
does not multiply requests.
Rejects with the first error encountered; all in-flight requests still run
to completion (standard Promise.all semantics).
SatimInvalidArgumentError on any malformed orderId.
Pre-warm the TCP+TLS connection to the SATIM gateway.
Call this once during application startup (or just before a checkout flow begins) to avoid paying the TCP handshake + TLS negotiation cost (~50–200 ms) on the first real payment request.
Sends a single probe request to /getOrderStatus.do with a known-unknown
order ID. The gateway responds immediately with ErrorCode 6; the
connection is then established and kept alive for subsequent requests.
This method never throws — if the probe fails (network down, gateway unreachable) the error is silently discarded. The only consequence is that the first real request will incur the normal handshake cost.
Refund a captured payment via /refund.do.
Retry: disabled. A retry could double-refund.
Preconditions: orderId valid; amount passes assertRefundAmount
(finite, positive, ≤ MAX_SAFE_AMOUNT, ≤ 2 decimal places, ≥ 1
minor unit after conversion).
SatimInvalidArgumentError on malformed inputs.
Void a pre-settlement payment via /reverse.do.
Cheaper than refund — cancels the authorization before the acquirer
settles, avoiding processing fees. Applies to status 1
(pre-authorized) and 2 (deposited but not yet settled) orders.
Retry: disabled.
SatimInvalidArgumentError on malformed orderId.
Register with automatic idempotency.
Derives a deterministic externalRequestId and orderNumber from
merchantRef, then calls register. Safe to retry — the
gateway deduplicates on the derived key.
If the gateway returns ErrorCode: "1" (duplicate order with a
conflicting amount/currency for the same merchantRef), the
SatimGatewayError is translated to SatimDuplicateOrderError
so callers can recover via status(originalOrderId) from their
own persistence layer.
Preconditions: merchantRef is a non-empty string after trim;
_returnUrl and _amount set.
Postcondition: same as register.
SatimInvalidArgumentError when merchantRef is empty.
SatimMissingDataError when registration prerequisites missing.
SatimDuplicateOrderError on conflicting prior registration.
Pre-authorization variant of safeRegister.
Domain-separated from safeRegister via the "preauth" mode tag in
the derived key — a register key never collides with a preauth
key for the same merchantRef.
Build a zero-trust webhook handler bound to this Satim instance.
The handler re-verifies state server-to-server on every callback
via this client's confirm() method. See
webhook/README.md for the verification
flow and distributed-deployment requirements.
SatimMissingDataError when onResolveAmount is missing.
SatimInvalidArgumentError on rate-limiter parameter violations.
ProtectedinitBind credentials to this instance via the module-private WeakMap.
Preconditions: this instance has no credentials currently bound;
all three fields are non-empty strings after trim, with username
and password ≤ 100 chars and terminalId ≤ 16 chars.
Runtime type guards reject objects that satisfy SatimCredentials
structurally but carry non-string payloads. Cannot be called twice
on the same instance.
SatimInvalidArgumentError when credentials are already bound, any field is non-string, or length limits (AN.100 / AN.16) are exceeded.
SatimMissingDataError when any field is empty after trim.
Set the payment amount in major currency units (whole DA for register).
Clone with the amount set.
SatimInvalidArgumentError via assertRegisterAmount on shape violations, sub-50-DA values, or fractional dinars.
Set the payment-page description (SATIM AN.600).
SatimInvalidArgumentError on non-string, overlong, or markup-bearing input.
Set the payment currency by ISO 3-letter code.
One of "DZD", "USD", "EUR". Mapped to numeric ISO 4217 internally.
SatimInvalidArgumentError on unsupported currencies.
Set the URL the customer is redirected to on payment failure.
Falls back to returnUrl when sent to the gateway if not set.
SatimInvalidArgumentError via assertSafeUrl.
Set the URL the customer is redirected to after payment.
SatimInvalidArgumentError via assertSafeUrl.
Set the server-to-server webhook URL the gateway POSTs status changes to.
SatimInvalidArgumentError via assertSafeUrl.
Set a custom 1-10 character alphasatim-module order number. Defaults to a CSPRNG-generated 10-digit value if unset at register time.
SatimInvalidArgumentError on format violations.
Set the hosted payment form language.
SatimInvalidArgumentError on unsupported codes.
Set a single jsonParams key/value pair.
Reserved keys (force_terminal_id, __proto__, constructor,
prototype) are rejected here as the first line of defence against
terminal-ID injection and prototype pollution. The Satim.buildData
method strips force_terminal_id again before send, providing
defence in depth.
SatimInvalidArgumentError on reserved keys, malformed keys, non-string values, or values exceeding 20 characters.
Set multiple jsonParams key/value pairs.
Iterates own enumerable properties only; inherited and symbol-keyed properties are ignored. Each pair is validated as if passed to userDefinedField.
Complexity: O(n) where n is the number of fields.
SatimInvalidArgumentError on the first invalid entry.
Set the payment session timeout in seconds ([600, 86400]).
SatimInvalidArgumentError on out-of-range or non-integer input.
Set the idempotency key (externalRequestId).
Setting an idempotency key enables automatic retries for register()
and registerPreAuth() — see Satim.registerAt. Without a key,
registration is not retried because a retry after a timeout could
create a duplicate order on the gateway.
Use deriveIdempotencyKey to derive a stable key from your
internal order reference, or call safeRegister(merchantRef) for
a one-shot wrapper that does the derivation.
SatimInvalidArgumentError on format violations.
Custom JSON serializer that redacts credentials.
Called automatically by JSON.stringify(satim). Returns a snapshot
with username, password, terminalId replaced by "[REDACTED]"
and all other configuration state intact (for debugging).
Stringification — never reveals credentials.
Primitive coercion hook — delegates to toString.
SATIM REST API client.
Construction binds credentials to a module-private
WeakMapentry (see SatimConfig.initFromCredentials). The HTTP client is either caller-injected or built with the provided options.Instances are safe to share across concurrent requests because every fluent setter returns a clone — no caller can mutate state observed by another caller.