Integration Catalog

Contract-derived reference for the live Pinrail integration surface published from pinrail-platform.

Source of truth

This page is derived from the integration catalog and feed handlers in pinrail-platform (cmd/tmsd/integrations.go) and reflects the live contract currently exposed by api.pinrail.xyz.

Start with:

curl -sS \
  -H 'X-API-Key: $PINRAIL_API_KEY' \
  https://api.pinrail.xyz/v1/integrations/catalog

The response groups the current surface by service and includes:

portal_surfaces
api_endpoints
webhook_events
rss_feeds
notes

When you need a machine-readable contract instead of the grouped inventory response, fetch the public OpenAPI companion directly:

curl -sS https://api.pinrail.xyz/v1/integrations/public-openapi.json

This route is intentionally public and cacheable so docs, SDK, and contract-diff tooling can ingest the same customer-safe surface without requiring a tenant session.

Live service inventory

Account and fleet snapshot

API: GET /v1/portal, GET /v1/integrations/catalog
Feeds: GET /v1/feeds/account.xml
Webhook events: heartbeat_stale, processor_outage, communication_flapping
Why it matters: safest first integration call for an ISO or sponsor user because it inherits the same account scope as the portal.

Terminals, locations, and telemetry

API: GET /v1/locations, GET /v1/locations/{terminal_id}, GET /v1/terminals/{terminal_id}/status-monitoring, GET /v1/terminals/{terminal_id}/transactions
Feeds: GET /v1/feeds/terminals/{terminal_id}.xml
Webhook events: heartbeat_stale, cash_low, cash_out, dispenser_fault, compliance_expiration, location_risk_change
Notes: inventory write paths stay more privileged than ISO-safe read access.

Transactions and processor activity

API: GET /v1/transactions, GET /v1/transactions/{transaction_id}/timeline
Feeds: GET /v1/feeds/account.xml, GET /v1/feeds/terminals/{terminal_id}.xml
Webhook events: decline_spike, approval_rate_drop, reversal_spike, high_decline_velocity, repeated_same_card_attempt
Notes: responses intentionally avoid PAN, track data, PIN blocks, and raw key material.

RMS, commands, connectors, and provisioning

API: GET /v1/connectors, GET /v1/connectors/{connector_id}/status, GET /v1/terminal-groups, GET /v1/terminals/{terminal_id}/commands, GET /v1/terminals/{terminal_id}/provisioning-payload, GET /v1/terminals/{terminal_id}/provisioning-export
Feeds: GET /v1/feeds/terminals/{terminal_id}.xml
Webhook events: command_failed, provisioning_failed
Notes: read APIs are live; configuration-changing flows remain admin-gated.

Settlements, payouts, and disputes

API: GET /v1/settlements, POST /v1/settlements/derive, GET /v1/disputes, POST /v1/disputes
Feeds: GET /v1/feeds/account.xml
Webhook events: settlement_mismatch
Notes: report reads are customer-facing; writes stay more privileged.

Branding, DNS handoff, and public status

API: GET /v1/public/branding-status
Notes: public-by-design status endpoint for branding and docs-host readiness.

Compliance vault, onboarding, documents, and videos

API: GET /v1/portal
Feeds: GET /v1/feeds/account.xml
Webhook events: compliance_expiration, location_risk_change
Notes: compliance workflows are portal-first today; richer public compliance APIs are the next gap after the catalog.

How to use this page

Use the integration catalog as the safest machine-readable starting point before wiring to narrower feeds, terminal telemetry, webhook subscriptions, or report-specific endpoints.

For implementation details:

On this page