Batches

4 endpoints. Base URL https://api.paymentsonline.io, sandbox https://api.sandbox-paymentsonline.io.

Every request needs payments-api-key and payments-account.

GET/v1/batches

List Batches

Query parameters

statusstring (open | closing | closed | failed)optional
Filter batches by lifecycle state.
terminal_reader_idstringoptional
Filter batches to those scoped to a specific terminal reader (trm_*). Card-not-present batches are omitted when this is set.
opened_at_gtestring date-timeoptional
Filter batches opened on or after this timestamp.
opened_at_ltestring date-timeoptional
Filter batches opened on or before this timestamp.
offsetnumberoptional
The (zero-based) offset of the first item in the collection to return.
limitnumberoptional
The maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

200PaginatedDto | object

has_morebooleanrequired
Whether or not there are more elements available after this set. If false, this set comprises the end of the list.
limitnumberoptional
The maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.
offsetnumberoptional
The (zero-based) offset of the first item in the collection to return.
totalnumberoptional
The total items count.
itemsarray of BatchDtorequired

GET/v1/batches/{id}

Get a Batch

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

200BatchDto

account_idstringrequired
The merchant account this batch belongs to.
amountnumberoptional
The batch's net total (sales minus refunds) in the smallest currency unit (e.g. cents for USD). Populated by the processor when the batch is closed; null for batches that haven't closed yet, or when the processor doesn't report a settled amount.
close_requested_atstring date-timeoptional
When the close was requested. Set on the first transition out of open.
closed_atstring date-timeoptional
When all underlying settlements reached SUBMITTED.
cutoff_atstring date-timeoptional
Safety-net deadline: if the batch is still open at this time, the platform will auto-close it. null means the platform will not auto-close this batch — the merchant must trigger the close explicitly (via the API or a processor-side mechanism).
failed_atstring date-timeoptional
When the batch terminally failed.
idstringrequired
The unique identifier of the batch.
opened_atstring date-timerequired
When this batch opened (ISO 8601).
statusstring (open | closing | closed | failed)required
Current lifecycle state. open: accepting transactions; closing: close was triggered and submission to the processor is in flight; closed: all underlying settlements were submitted (the merchant-visible "done" signal); failed: at least one settlement exhausted retries — partners may retry by re-issuing close.
terminal_reader_idstringoptional
Terminal reader the batch is scoped to. Set when the merchant uses a processor that operates one batch per physical terminal (card-present). Absent for card-not-present, where the batch aggregates transactions at the merchant level.
transaction_countnumberoptional
Number of transactions (sales + refunds) included in the batch. Populated by the processor when the batch is closed; null for batches that haven't closed yet, or when the processor doesn't report a count.

POST/v1/batches/{id}/close

Close a Batch

Close a single Batch by id. Idempotent on the id — repeat calls on closing/closed batches return current state; calls on failed batches reset and retry.

Path parameters

idstringrequired

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

201BatchDto

account_idstringrequired
The merchant account this batch belongs to.
amountnumberoptional
The batch's net total (sales minus refunds) in the smallest currency unit (e.g. cents for USD). Populated by the processor when the batch is closed; null for batches that haven't closed yet, or when the processor doesn't report a settled amount.
close_requested_atstring date-timeoptional
When the close was requested. Set on the first transition out of open.
closed_atstring date-timeoptional
When all underlying settlements reached SUBMITTED.
cutoff_atstring date-timeoptional
Safety-net deadline: if the batch is still open at this time, the platform will auto-close it. null means the platform will not auto-close this batch — the merchant must trigger the close explicitly (via the API or a processor-side mechanism).
failed_atstring date-timeoptional
When the batch terminally failed.
idstringrequired
The unique identifier of the batch.
opened_atstring date-timerequired
When this batch opened (ISO 8601).
statusstring (open | closing | closed | failed)required
Current lifecycle state. open: accepting transactions; closing: close was triggered and submission to the processor is in flight; closed: all underlying settlements were submitted (the merchant-visible "done" signal); failed: at least one settlement exhausted retries — partners may retry by re-issuing close.
terminal_reader_idstringoptional
Terminal reader the batch is scoped to. Set when the merchant uses a processor that operates one batch per physical terminal (card-present). Absent for card-not-present, where the batch aggregates transactions at the merchant level.
transaction_countnumberoptional
Number of transactions (sales + refunds) included in the batch. Populated by the processor when the batch is closed; null for batches that haven't closed yet, or when the processor doesn't report a count.

POST/v1/batches/close

Close open Batches

Close all open Batches for the caller's account. Retries any failed batches before closing open ones. Returns the list of Batches now in closing state. Optionally scope the close to a single terminal reader with terminal_reader_id. When set, only batches belonging to that terminal are considered — useful for card-present merchants who want to close one terminal's batch without touching others. Naturally idempotent: subsequent calls with no new open or failed batches return current state.

Query parameters

terminal_reader_idstringoptional
Scope the close to a single terminal reader (trm_*). Card-not-present batches are omitted when set.

Header parameters

payments-accountstringrequired
The id of the Paydude Account (usually starting with the prefix acct_) that the request is performed on behalf of. Must be a merchant (connected) account id, not the partner account you signed up with; a partner account passes GET /v1/accounts and then fails with "not enabled for this account" on the first payment call.

Responses

201array of BatchDto