Eight Tech API v1

Bringing intelligence to your data.

The Eight Tech API gives processors, banks, and analytics teams one consistent interface for merchant, transaction, settlement, refund, and dispute data—even when the source arrives in processor-specific formats.

Use the API to retrieve normalized records, reconcile activity across reporting periods, and power your own dashboards or downstream analytics. Every object preserves its source lineage so you can connect an Eight Tech record to the processor file and record that produced it.

Design preview. This portal represents the proposed Eight Tech API contract. Endpoint names, field definitions, retention periods, and rate limits should be finalized before production release.

Make your first request →Authenticate and retrieve a merchant in minutes.Explore transaction data →Review normalized transaction fields and lineage.Receive webhooks →React when imports and data objects change.Handle errors →Build reliable integrations with predictable responses.

Base URL

APIhttps://api.eight.tech/v1

Core principles

Normalized by default. Stable Eight Tech objects isolate your application from processor-specific file layouts.
Traceable to source. Lineage fields identify the source system, file, record, and ingestion time.
Safe for history. Immutable identifiers and temporal audit fields support reproducible reporting.
Built for scale. Cursor pagination, idempotency, and webhook signatures support production workloads.

Get started

Make your first request

Retrieve a merchant with one authenticated request. The examples use test-mode credentials and return representative data.

Create an API key. Generate a restricted test key in the Eight Tech Console. Test keys begin with eight_test_.
Export the key securely. Store it in your secret manager or development environment. Never expose a secret key in client-side code.
Request a merchant. Send the key as a Bearer token and replace the sample ID with a merchant available to your account.

GET/merchants/mrc_01J8Y6K8P2K7H7KFPDH2M46A9R

What happens next

A successful response returns a stable Eight Tech merchant object. Use its id to filter transactions, settlements, refunds, and disputes. All timestamps are ISO 8601 UTC strings.

Get started

Authentication

Eight Tech authenticates API requests with secret keys sent in the HTTP Authorization header.

HTTPAuthorization: Bearer eight_test_••••••••••••

Key types

Key	Purpose	Access
eight_test_	Development and integration testing	Test-mode data only
eight_live_	Production workloads	Live data within assigned scopes
eight_rk_	Restricted integrations	Explicit resources and actions

Scopes

Grant only the scopes an integration requires, such as merchants:read, transactions:read, or webhooks:write. Rotate keys immediately if they may have been disclosed.

Get started

API conventions

Consistent identifiers, timestamps, monetary values, and request metadata make Eight Tech responses predictable across resources.

Identifiers and time

Object IDs are opaque strings with a readable prefix, such as txn_, mrc_, and rfd_. Do not parse or construct them. Timestamps use ISO 8601 in UTC.

Money

Monetary amounts are integers in the currency’s minor unit. For example, 1099 with usd represents $10.99. This avoids floating-point rounding errors.

Request IDs

Every response includes an EIGHT-Request-Id header. Log it with your internal correlation ID and include it when contacting support.

Idempotency

For supported write operations, send a unique Idempotency-Key. Eight Tech stores the first result and safely returns it for equivalent retries.

Core resource

Merchants

A merchant represents a business location or merchant account normalized from a processor or acquiring platform.

GET/merchants/{merchant_id}

Field	Type	Description
id	string	Stable Eight Tech merchant identifier.
display_name	string	Customer-facing or DBA name.
status	enum	`active`, `inactive`, `closed`, or `unknown`.
processor	object	Processor name, platform, and external merchant identifiers.
mcc	string	Four-digit merchant category code.
created_at	timestamp	Time the merchant was first created in Eight Tech.
source	object	File and record lineage for the latest source representation.

Core resource

Transactions

A transaction is a normalized payment event sourced from processor activity, including sales, credits, reversals, and other financial events.

GET/transactions/{transaction_id}

List transactions

GET/transactions?merchant_id={id}&created_at[gte]={timestamp}

Parameter	Type	Description
merchant_idoptional	string	Return transactions for one merchant.
created_at[gte]optional	timestamp	Include records created on or after this time.
processed_at[gte]optional	timestamp	Filter by processor event time.
typeoptional	enum	Filter by `sale`, `refund`, `credit`, or `reversal`.
limitoptional	integer	Number of objects to return, from 1 to 100.

Processor lineage. The source object can reference a TSYS TDDF report, transaction code, file date, and record position without exposing those processor-specific details as the canonical transaction model.

Core resource

Refunds

A refund represents money returned to a cardholder and tracks the event from processor receipt through settlement.

GET/refunds/{refund_id}

Field	Type	Description
status	enum	`pending`, `processed`, `settled`, `failed`, or `canceled`.
amount	integer	Refund amount in minor currency units.
original_transaction_id	string	Eight Tech ID of the original transaction when matched.
processed_at	timestamp	Time the processor accepted or recorded the refund.
settled_at	timestamp	Time the refund was included in settlement, if known.

Core resource

Settlements

A settlement groups financial activity that contributes to a merchant’s expected or completed funding event.

GET/settlements/{settlement_id}

Use settlement totals and balance components to reconcile gross sales, refunds, disputes, interchange, assessments, processor fees, adjustments, and net funding.

Core resource

Disputes

A dispute tracks a challenged transaction and its lifecycle, financial impact, reason code, evidence dates, and source-network references.

GET/disputes/{dispute_id}

Dispute records remain distinct from fraud notifications such as TC40 reports. When Eight Tech can associate related fraud or network events, it exposes them through typed references instead of treating them as the same object.

Platform

Pagination

List endpoints use cursor-based pagination so integrations can traverse changing datasets without relying on unstable page numbers.

Set limit from 1 to 100. When has_more is true, pass next_cursor as the next request’s cursor. Treat cursors as opaque and do not reuse them with different filters.

Platform

Errors

Eight Tech uses standard HTTP status codes and a consistent error envelope with a machine-readable code, clear message, and request identifier.

Status	Meaning	Typical action
400	Invalid request	Correct a parameter or request body.
401	Authentication failed	Verify the API key and environment.
403	Permission denied	Request the required scope or resource access.
404	Resource not found	Verify the ID and account context.
409	Conflict	Resolve the resource state or idempotency mismatch.
429	Rate limited	Retry with exponential backoff and jitter.
500	Eight Tech internal error	Retry safely and contact support if persistent.

Platform

Webhooks

Webhooks notify your application when imports complete or Eight Tech objects change, without requiring continuous polling.

Example events

data_import.completed
merchant.updated
transaction.created
refund.settled
dispute.updated

Verify signatures

Use the raw request body, the timestamp, and your endpoint secret to verify the EIGHT-Signature header. Reject stale timestamps and compare signatures using a constant-time function.

Delivery behavior

Return a 2xx response promptly. Eight Tech retries failed deliveries with exponential backoff. Event consumers should deduplicate by the event id because delivery is at least once.

Platform

Versioning

The major API version appears in the URL. Compatible additions can ship within v1; breaking changes require a new major version.

Eight Tech may add optional fields, new enum values, resources, and webhook event types without changing the major version. Integrations should ignore unknown response fields and handle unrecognized enum values safely.

Help

Support

For integration help, provide the environment, endpoint, approximate timestamp, and EIGHT-Request-Id. Never send secret API keys or full cardholder data.

Before production

Use least-privilege restricted keys.
Store secrets outside source control.
Implement timeouts, retries, and idempotency.
Verify webhook signatures before processing events.
Confirm PCI DSS responsibilities for your data flow.