Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Terminal Payments

Retrieve historical payments processed by a single terminal. Use this endpoint for device level reconciliation, in store reporting, or quick troubleshooting at the terminal level.

This endpoint returns a different response schema. Terminal Payments does not return the same payment object as Merchant Payments and Partner Payments. The query parameters are identical across all three, but the response differs: Terminal Payments returns terminal and device oriented fields such as trackingId, pageId, reqCurrencyId, payCurrencyId, emailReceipt, smsReceipt, cartItems, externalId, and merchantLocation, and it does not return batchPeriod, locationId, locationName, merchantId, tenderType, transferType, originalSenderAddress, or the refund lifecycle fields. Do not write one response parser and reuse it across all three scopes.

For settlement lifecycle status, use the settlementId, batchId, and batchStatus fields on each payment together with the Settlement APIs. Note that batchPeriod is not available at terminal scope, read the payment from merchant or partner scope if you need it.

Endpoint

GET /Terminals/{id}/payments

Path parameters

Name
Type
Required
Description

id

string

Yes

The terminalId you want to query

Authentication

X-Api-Key: {apiKey}

Send your API key in the X-Api-Key header. This is the preferred authentication method for Reporting endpoints, including Terminal Payments.

Existing integrations that already authenticate with an OAuth 2.0 bearer token can continue to do so, send Authorization: Bearer <access_token> instead. New integrations should use X-Api-Key.

Request headers

Header
Value

X-Api-Key

{apiKey}

Accept

application/json

Legacy alternative: Authorization: Bearer <access_token> in place of X-Api-Key.

Query parameters

Terminal Payments accepts the same query parameters as Partner Payments and Merchant Payments.

Name
Type
Required
Notes

From

string, date-time

Yes

Start of the payment creation-time window, in UTC. Accepts either a full ISO 8601 timestamp (2025-09-01T00:00:00Z) or a date-only value (2025-09-01).

To

string, date-time

Yes

End of the payment creation-time window, in UTC. Accepts either a full ISO 8601 timestamp or a date-only value, same as From.

Page

integer

Yes

Zero based page number. The first page is 0, not 1. Default 0.

PageSize

integer

Yes

Items per page. Default 50, maximum 100.

StatusCode

array of strings

No

One or more of created, processing, completed, underpaid, overpaid, fullyRefunded, partiallyRefunded, expired, invalid, cancelled

TenderType

array of strings

No

Filter by one or more tender types. See Tender Types. Accepted as a filter, but tenderType is not returned on this endpoint's records.

TrackingId

string

No

Filter by a specific tracking identifier

PageId

string

No

Opaque cursor for continuation, echoed from a prior response

ReqCurrencyId

integer

No

Requested currency id filter

PayCurrencyId

integer

No

Payment currency id filter

CustomerId

string

No

Filter by customer id. Exact match.

DescriptionSearch

string

No

Case sensitive text search over the description

PaymentCode

string

No

Filter by payment code. Case-insensitive substring match.

Reference

string

No

Filter by merchant reference such as invoice number. Exact, case-sensitive match.

LocationName

string

No

Accepted but has no effect at this scope. See the callout below.

TerminalName

string

No

Accepted but has no effect at this scope. See the callout below.

SortBy

string

No

Field to sort by. Allowed values: statusCode, expiration, quoteExpiration, created, updated.

SortDirection

string

No

asc or desc

LocationName and TerminalName do not filter at this scope. Both are accepted and return HTTP 200, but they have no effect on the result set: a value that matches nothing returns the same records as an unfiltered request. Confirmed by direct testing. This differs from Merchant Payments and Partner Payments, where both parameters filter as expected. Do not rely on either one here. This endpoint is already scoped to a single terminal, so filter client-side if you need to narrow further.

Parameter casing: all query parameters on this endpoint are capitalized (From, To, Page, PageSize, and so on).

Pagination is zero based. Page=0 returns the first page. Passing Page=1 skips the first page of results, since the request computes skip = page * pageSize.

Exact parameter definitions are also described on the Pagination and Sorting page.

Example request

Successful response 200

Field reference

Field
Type
Description

id

string or null

Unique payment identifier

externalId

string or null

External identifier supplied by the integrator, when provided

terminalId, terminalName

string

Terminal that processed the payment

paymentCode

string

Short code for user facing references

settlementId

string or null

Settlement covering this payment. Null until the payment is included in a settlement.

batchId

string or null

Batch this payment belongs to. Null until the payment is batched.

batchStatus

string or null

Status of the batch containing this payment: open, closed, or hold. This is a batch state, not a settlement state.

trackingId

string or null

Pollable tracking identifier for in flight payments

pageId

string or null

Opaque continuation id that can be echoed to the PageId query parameter

statusCode

string

Current payment status. See Payment Statuses.

reqCurrencyId, payCurrencyId

integer

Currency identifiers for requested and paid amounts

amounts

object

requested, paid, settleableAmount, and partnerFees

reference, description

string or null

Merchant supplied metadata fields

customerId

string or null

Merchant supplied customer id. A string at terminal scope, unlike merchant and partner scope where it is an object.

emailReceipt, smsReceipt

boolean

Whether a receipt was sent by email or SMS

cartItems

array

Line items associated with the payment, when supplied

expiration, quoteExpiration

date-time or null

Payment and quote expiry timestamps

paymentAddress

string or null

Destination address for the payment, where applicable to the tender

redirectUrl

string or null

Redirect target after payment completion, when configured

transactions

array

On chain transactions associated with the payment

conversions

array

Currency conversion details, when applicable

paymentNotifications

array

Notification records for the payment

webhookUrls

array of strings

Webhook targets registered for the payment

refundEmail

string or null

Email used for refund claims

merchantLocation

object or null

id, name, and address for the location

created, updated

date-time or null

ISO 8601 timestamps in UTC. Declared nullable at this scope, unlike merchant and partner scope where both are always present. They were populated in testing, but handle null defensively.

The response envelope is data, total, and page. PageSize is not echoed in the response.

Fields this endpoint does not return. batchPeriod, locationId, locationName, merchantId, tenderType, transferType, originalSenderAddress, refundLifecycleStatus, refundInitiatedAt, refundCompletedAt, and refundFailureReason are not part of this endpoint's response. Use Merchant Payments or Partner Payments when you need any of them.

There is no paymentSettlementStatusCode field. It is not returned here and is not accepted as a filter. For settlement status, use settlementId, batchId, and batchStatus on the payment, together with Settlements, Batches, and Deposits.

Error responses

Code
Condition

401

Missing or invalid X-Api-Key, or missing or invalid bearer token when using the legacy OAuth path

403

Authenticated but not permitted to view payments for this terminal

404

Terminal id does not exist or is not visible to your credentials

Best practices

Recommended patterns when using Terminal Payments

  • Remember that Page starts at 0, not 1. Passing Page=1 first skips the actual first page of results.

  • Use a narrow time window, such as the last 24 hours, when polling for recent terminal activity.

  • Increase PageSize for one time backfills and reduce it for frequent dashboards or troubleshooting views, up to the maximum of 100.

  • Use SortBy=created with SortDirection=desc to see the most recent payments first in device diagnostics.

  • Handle created and updated as nullable at this scope. Merchant and partner scope always return both.

  • Do not use LocationName or TerminalName here. Both are accepted but neither filters at this scope. Narrow client-side instead.

  • Combine terminal scope with partner or merchant scope when investigating issues that may affect multiple devices, and expect a different field set from each.

  • Use settlementId, batchId, and batchStatus together with the Settlement APIs to see how terminal level payments flow into merchant settlement batches and funding.

For portfolio level and store level views, see Partner Payments and Merchant Payments.

PreviousMerchant Payments
NextSplit Funding

Last updated