settlementBatchId
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
merchantId
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
runDateUtc
required |
string (date-time)
|
When the settlement run that produced this batch was kicked off (`SettlementBatch.RunDate`).
This is the batch's "Run Date" display value, not its completion time.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
completedAtUtc
required |
string (date-time)
|
When the batch first reached a terminal outcome (`SettlementBatch.CompletedAtUtc`).
Null for legacy batches created before the field existed, or a batch still in flight.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
duration
required |
string (date-span)
|
The settlement-attempt duration: `completedAtUtc` minus the batch's audit
creation time, computed server-side via `SettlementDurationCalculator` (clamped at zero).
Null when `completedAtUtc` is null. Derived from per-batch set-once timestamps so
it is immune to later batch mutations (re-settle, park, backfill, override).
Written as [-][d.]hh:mm:ss[.fffffff], for example 00:00:01.2500000; the seven-digit
fraction of a second appears only when it is non-zero. Not an ISO 8601 duration.
nullablepattern ^-?(\d{1,8}\.)?([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d{7})?$
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
triggerType
required |
SettlementTriggerType
SettlementTriggerType |
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
triggeredByUserId
required |
string (uuid)
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
triggeredByUserName
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
paymentTypes
required |
array of PaymentType
array of PaymentType |
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
CreditCard |
| DebitCard |
| GiftCard |
| EbtSnap |
| EbtCash |
| Ewic |
| LoyaltyCard |
| Cash |
| ACH |
| ECheck |
| Alternative |
|
|
totalTransactionCount
required |
integer (int32)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
settledCount
required |
integer (int32)
|
Number of items that successfully settled. Equals `totalTransactionCount`
for fully successful batches; less for `PartiallyCompleted`.
Null for legacy batches and batches still `Pending`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
netAmount
required |
number (double)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
processor
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
processorBatchId
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
processorKey
required |
string
|
The lower-cased processor key the batch was produced for (the same key the settlement
close fans out on). Needed by the operator retry action to target the re-settle engine
entrypoint at the correct (merchant, processor) counter. Null for legacy batches created
before the key was persisted. Non-sensitive: a short identifier such as `tsys`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
gatewayBatchId
required |
string
|
The gateway batch id this run settled (`SettlementBatch.OpenBatchId`). Identifies the
single batch the operator retry resubmits. Null for legacy batches created before the id
was persisted. Non-sensitive: an internal batch identifier, never PAN/card data.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
correlationId
required |
string (uuid)
|
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|
status
required |
SettlementBatchStatus
SettlementBatchStatus |
Status of a settlement batch through its lifecycle.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Pending |
Batch created, awaiting processor submission. | Completed |
Batch successfully settled with the processor. | Failed |
Batch settlement failed. | PartiallyCompleted |
Some transactions settled, others rejected by the processor. | NothingToSettle |
No transactions were eligible to settle for this (merchant, processor) group. A successful no-op outcome, distinct from Failed (a genuine fault) and from Completed (a real settle). Recorded so a settlement run leaves a history row for every targeted (merchant, processor) even when zero transactions are loaded. The short explanation is carried in SettlementBatch.ErrorMessage as the per-batch outcome detail. | OperatorActionRequired |
The batch could not be settled automatically and is parked for operator action. Distinct from Failed: a Failed closed batch is re-attempted on the next run (transient fault), whereas an OperatorActionRequired batch is deliberately excluded from automatic retry because blindly re-submitting it would just re-fail. Two causes park a batch here: a non-transient duplicate-batch-number processor rejection (the same processor BatchNumber will keep colliding until an operator bumps it), and exhaustion of SettlementConsts.MaxSettlementRetries transient retries. The batch's transactions are moved to SettlementStatus.SettlementOnHold so they stop auto-retrying; the reason is carried in SettlementBatch.ErrorMessage. The operator UI (follow-up story) lists these and can retry with a bumped processor BatchNumber. | TerminalContention |
The batch was not submitted because a concurrent settlement run already held the terminal lock for the same (Fiserv MerchID, TermID) pair (UMF Appendix M 42.1: only one batch at a time per terminal). Distinct from Failed: nothing went wrong, this run simply deferred to the run that already owned the terminal. The next scheduled run retries normally. |
|
errorMessage
required |
string
|
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
|