> For the complete documentation index, see [llms.txt](https://docs.omni.integratedcommerce.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omni.integratedcommerce.io/get-started/conventions.md).

# Request conventions

Identifier prefixes, amounts in minor units, and the shared filter, sort, and paging syntax.

These conventions apply across every endpoint. Learning them once removes most of the guesswork from the rest of the API.

## Identifiers

Resource identifiers are prefixed so that the kind of thing an ID refers to is readable at a glance. Everything after the prefix is a [ULID](https://github.com/ulid/spec).

| Prefix     | Resource                                                      |
| ---------- | ------------------------------------------------------------- |
| `pmt_trm_` | A physical terminal payment method                            |
| `pmt_vrt_` | A virtual terminal payment method (a Hosted Payment Form)     |
| `pmt_ach_` | An ACH payment method                                         |
| `pmt_tkn_` | A tokenized (stored) payment method                           |
| `trx_`     | A transaction                                                 |
| `ifr_`     | A hosted session request (the session-creation response `id`) |
| `ops_`     | A token removal operation                                     |
| `evt_`     | A transaction or token webhook event                          |
| `aho_`     | An account holder assigned by the API                         |
| `stl_`     | A settlement, meaning one deposit to your bank account        |
| `mfc_`     | A merchant fee charge                                         |

The `sessionId` returned for the Hosted Payment Form and SDK is an opaque, unprefixed token. Use it unchanged. Merchant lifecycle event IDs are also opaque and need not have the `evt_` prefix.

Identifiers you supply yourself - `referenceId`, `orderNumber`, `invoiceNumber`, and an account holder's `externalId` - are free-form strings that you choose. The examples throughout these docs use prefixes such as `ref_`, `ord_`, and `inv_` purely as a readable convention; the API does not require them.

{% hint style="info" %}
An account holder can be addressed either by the ID assigned by the API (`aho_01JRZPRGFF4J2SZC3HMDBYEN2J`) or by the external ID your system assigns (for example `usr_1757945457790`). Both work wherever an `accountHolderId` is accepted.
{% endhint %}

## Amounts

All amounts are integers expressed in the smallest denomination of the currency - cents for both USD and CAD. An amount of `1000` is $10.00.

Sale and authorization request amounts are positive. Response amounts can be `0`, including virtual tokenization, declines, and transactions still in progress. Settlement reporting amounts are signed, because a deposit can net out negative; see [the reporting model](/settlement-reporting/reporting.md#signed-amounts).

## Currencies and regions

The API operates in the United States and Canada, in USD and CAD. A payment method carries its own currency, and the transaction inherits it - you do not pass a currency on the transaction itself.

## Timestamps

Timestamps are ISO 8601 in UTC, for example `2025-06-02T23:56:18.2102020Z`.

## Filtering, sorting, and paging

List endpoints share one query syntax.

### filters

Filter criteria in the format `field==value,field!=value`. Multiple filters can be separated by commas. Use `|` for OR conditions within a field.

```http
GET /transactions?filters=timestamp>=2025-05-21T01:00:00,type==Sale|Capture
```

Available fields on `GET /transactions`: `id`, `timestamp`, `referenceId`, `orderNumber`, `invoiceNumber`, `type`, `amount`, `status`.

### sorts

Sort criteria as comma-separated field names. Use a `-` prefix for descending order.

```http
GET /transactions?sorts=-timestamp,type
```

### page and pageSize

`page` starts at 1. For example, with 100 records and a `pageSize` of 10, `page=2` gives you records 11 to 20.

```http
GET /transactions?page=2&pageSize=10
```

## Next steps

* [Errors and rate limits](/get-started/errors-and-rate-limits.md)
* [Retrieving transactions](/payments/transaction-retrieval.md) - using these filters to resolve an uncertain outcome