Core Concepts

The merchant is the top-level business entity in the API. It contains business information and provides the main context for resources such as stores, accounts, applications, subscriptions, and reporting.

A store represents a merchant-owned sales channel or location. Use it to understand where sales happen and how payment activity, terminals, and optional webhooks can be scoped below the merchant level.

A terminal is a payment device used for in-person payments. Terminals belong to stores and are the operational resource for POS payment flows.

An account is the balance resource that holds funds before payout. It includes balances, holder information, payout settings, and the next payout date.

A sale is the primary payment object that represents the amount to collect. It carries the business context for a payment, including amount, customer, allowed payment methods, and related transactions.

A transaction is the payment operation performed within or for a sale. It captures execution details such as status, processor information, amount, settlement information, and terminal details.

Sale Lifetime shows how a sale changes over time as transactions are created, completed, cancelled, failed, refunded, or retried. Use it to understand sale status, transaction status, and the open, paid, refunded, and reversed amounts.

A customer stores the identity and contact details for a person or organization. You can associate customers with sales so you can reuse customer data and track purchases over time.

Metadata is a flat key-value object you can attach to supported resources such as customers and sales. Use it to store your own identifiers and business context without changing the core resource schema.

An application is an integrator-facing resource with its own identity, scopes, type, and OAuth client credentials. It represents the reusable software client that accesses the API.

An installation links an application to a merchant context. It turns the application definition into an active integration instance with its own status, scopes, and optional event subscriptions.

A webhook sends event notifications to an external URL. Use it for event-driven integrations that react to changes in resources such as sales and transactions instead of polling for updates.

A payout is the transfer of funds from an account balance to a bank account. It includes the amount, payout date, status, grouping details, and payout attempts.