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.
| 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 the merchant's 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.
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.
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.
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.
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.
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.
GET /transactions?page=2&pageSize=10
Next steps
- Errors and rate limits
- Retrieving transactions - using these filters to resolve an uncertain outcome