Conventions

Shapes that show up on every endpoint. This page is the canonical reference — other pages link here instead of repeating themselves.

Envelopes

• Single resource — returned as the resource itself, no wrapper.
• List — { "items": [...], "next_cursor": <string|null> }. null means last page.
• Error — { "error": { "type", "message", "fields", "request_id" } }.

Pagination

Two query params on every list endpoint:

• limit — default 25, max 100
• starting_after=<id> — pass the previous response's next_cursor

Loop until next_cursor is null:

curl "https://gateway.pmnts.io/v2/partners/merchants?limit=50" \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN"

{
  "items": [ /* 50 merchants */ ],
  "next_cursor": "mch_042"
}

curl "https://gateway.pmnts.io/v2/partners/merchants?limit=50&starting_after=mch_042" \
  -u "$PARTNER_USERNAME:$PARTNER_TOKEN"

{
  "items": [ /* tail */ ],
  "next_cursor": null
}

IDs

• Merchants and partners are addressed by username.
• Acquirer connection ids are derived, not stored: <merchant-id>-ACQ-<ACQUIRER-CODE> (e.g. 042-ACQ-NAB).
• Wallets and users use <owner-id>-<TYPE>-<random> (e.g. 042-WAL-9f3k2m8q).
• Acquirers are slug codes: nab, cba, anz, etc.

Timestamps

ISO 8601, UTC. Always.

Error types

See Errors and troubleshooting for more.