Glossary
Canonical definitions for Koard docs. Hover a linked term in any guide for a short definition, or jump here for the full entry.
Platform
Koard
Payment platform that helps PSPs and ISVs accept Tap to Pay on iPhone and card-present payments via SDKs, REST APIs, and merchant management.
PSP (Payment Service Provider)
Company that serves multiple merchants with payment processing. A primary Koard customer type.
ISV (Independent Software Vendor)
Software company building payment or POS applications that integrate Koard for Tap to Pay and processing.
Partner
Top-level account in the MMS that owns descendant merchant accounts, terminals, and API keys.
MMS (Merchant Management System)
Koard portal for onboarding merchants, terminals, locations, credentials, and API keys.
- UAT: https://app.uat.koard.com
- Production: https://app.koard.com
UAT
Isolated sandbox environment (api.uat.koard.com / app.uat.koard.com). Transactions do not move money or appear in live card or merchant histories.
Sandbox
Koard test environment for exercising features without live funds. Distinct from an Apple Sandbox Apple Account used for Tap to Pay certification.
Production / Live mode
Live environment where activated merchant accounts accept real payments (api.koard.com / app.koard.com).
Accounts & hierarchy
Config inheritance for tax and surcharge (most specific wins): account → location → terminal (null means inherit).
Account
Merchant or partner entity in Koard.
Merchant
Business onboarded under a partner to accept payments. Requires name, Tax ID, MCC, and HQ country. Country cannot be changed after creation.
Location
Physical or logical place under a merchant where terminals accept payments. Can override account-level tax and surcharge settings.
location_id
Unique identifier for a Location. Used in REST paths (/v1/locations/{location_id}), list filters, webhook payloads, and SDKs (for example setActiveLocation(locationId) before enrollDevice / payments).
Terminal
Payment endpoint (often an iPhone running Tap to Pay) tied to processor credentials (MID/TID or Partner ID) and optionally a terminal profile.
Terminal Profile
Reusable settings for terminals: tipping, surcharge flags, receipts, timeouts, and UI preferences.
Merchant Credentials
Credentials merchants use to authenticate the Koard SDK and process payments; scoped to locations and terminals.
MCC (Merchant Category Code)
Four-digit ISO business-type code required at merchant onboarding (for example 5812 for restaurants).
Payment operations
Tap-initiated (card-present): Sale and Preauth require encrypted card data from Tap to Pay or another compliant reader.
Follow-ups (card-not-present): Capture, Incremental Auth, Tip Adjust, Reverse, Refund, and Confirm do not require another tap.
Sale
One-step authorize + capture. Funds are collected immediately; status typically ends as captured.
Preauth (Preauthorization)
Authorization hold without capture. Use when the final total may change; you must later capture or reverse.
Capture
Settle (collect) funds from a prior authorization. Optional amount and breakdown for tips and surcharge reconciliation.
Incremental Auth
Increase an existing authorization hold by a delta amount. Status remains authorized. A declined increment reverts to the last successfully authorized amount.
Tip Adjust
Update gratuity before settlement (for example tip-on-receipt). Does not recompute surcharge.
Reverse / Void
Release uncaptured authorized funds. Use instead of refund when money was never captured.
Refund
Return funds on a captured transaction (full or partial). Distinct from reverse.
Confirm
SDK/API step that finalizes a sale after cardholder surcharge disclosure when the SDK status is surchargePending (webhook/API payloads use surcharge_pending).
PaymentBreakdown
SDK object for subtotal, tax, tip, and nested Surcharge details sent with payment requests.
Surcharge
Fee added to eligible credit-card transactions to offset processing costs. Not applied to debit. Can be automatic (processor) or custom (for example BIN-based).
surchargePending
SDK sale status when automatic surcharge applies and cardholder confirmation is required before finalization.
surcharge_pending
Webhook and REST API transaction status when surcharge confirmation is required (surcharge_pending). Distinct from the SDK enum value surchargePending.
Tip capture mode
How tip was collected: tip_at_sale (on the original sale) or tip_adjust (added or changed after the sale).
Tax rate / Tax basis
Hierarchical configuration defaults for what tax is calculated on and at what percentage. Separate from per-transaction taxAmount / taxRate on the breakdown.
Identifiers
Do not conflate these IDs.
event_id
Client-generated UUID4 idempotency key for a single API attempt. Replays with the same ID are rejected as duplicates. Similar role to RRN for one processor call.
transaction_id
Koard-issued ID for the full payment lifecycle. Shared across capture, tip adjust, incremental auth, reverse, and refund on the same payment.
MID (Merchant ID)
Processor-assigned merchant identifier used for routing and batching (often with TID).
TID (Terminal ID)
Processor-assigned per-terminal identifier. Batches are typically unique per MID/TID combination.
VIN (Vendor ID)
Vendor identifier from some processors, entered with MID/TID at terminal setup. Some processors use Partner ID instead.
Partner ID / Processing Terminal ID
Alternate boarding identifier used by processors like Payroc in place of classic MID/TID/VIN.
processor_batch_id
Batch ID unique per MID/TID used when informing Koard of settlements from an external batching system.
BIN
Bank Identification Number (card prefix). Used for custom BIN-based surcharging and (as Acquirer BIN) on some processor VAR sheets such as TSYS.
DBA
Doing Business As — the trade name shown on cardholder statements and processor records (for example doing_business_as_name on Silverflow).
RRN (Retrieval Reference Number)
Traditional card-network identifier for a single processor attempt; conceptually similar to event_id.
Transaction states
pending
Request accepted; may move to processing or failed.
processing
Gateway evaluating the request; may become authorized, captured, declined, or failed.
authorized
Funds on hold but not collected. Can transition to captured, reversed, or cancelled.
captured
Funds collected. Can transition to refunded or cancelled.
declined
Processor rejected the attempt. Terminal state.
failed
Processing error. Terminal state.
reversed
Authorization hold released. Terminal state.
refunded
Captured funds returned. Terminal state.
cancelled
Flow cancelled. Terminal state.
Boarding & processors
Boarding
Onboarding a merchant or terminal onto a payment processor with credentials from a VAR sheet (via MMS UI or API).
VAR Sheet
Processor-provided parameter packet (MID, TID, MCC, Group ID, and related fields) required to board a terminal. Shape differs by processor (TSYS, Fiserv, Elavon, Worldpay, Payroc, Silverflow, Cybersource).
Processor Config
Koard-side configuration selecting which acquiring platform or flavor a merchant uses (for example Fiserv Rapid Connect front-ends via processor_config_id).
Host capture
Settlement model where the processor host manages the batch and settles on its cutoff (for example Fiserv today). Merchant-driven open/close may be unavailable.
TPPID
Fiserv Rapid Connect ID for the certified integrator/SDK build (owned by Koard), not a merchant VAR-sheet field.
Datawire / DID
Transport/ID used for some Fiserv terminals when Datawire is enabled; may be on the VAR packet or provisioned by Koard.
Passthrough EMV
Flow where Koard only forwards EMV data and later receives the final outcome from the PSP. PUT /v1/transactions/{id} is reserved for this; not for directly managed processors such as TSYS, Elavon, Fiserv, or Worldpay.
Apple & Tap to Pay
Tap to Pay on iPhone
Apple contactless acceptance on iPhone (XS or later, iOS 17.4+) without extra hardware. Requires entitlement, provisioning, and Koard SDK integration.
Tap to Pay on Android
Contactless card acceptance on NFC-enabled Android devices (Android 12+) using the Visa Tap to Pay Ready kernel and Koard SDK — no external reader hardware required.
Tap to Pay Entitlement
Apple Managed Capability that must be requested and approved before building Tap to Pay–enabled apps.
L3 Certification
Apple Level-3 certification path that Koard’s partnership helps PSPs and ISVs bypass for faster time-to-market.
Sandbox Apple Account
Dedicated Apple tester account signed in on a test iPhone for certification and QA. Production Apple IDs cannot run Sandbox Tap to Pay.
Apple CERT environment
Apple certification environment used after development certificate approval when validating Tap to Pay flows.
Apple Business Register
Apple hub for PSP Tap to Pay documentation, registration, and certification resources (PSP access).
Proximity Payment Service
Apple service Koard calls to exchange encrypted Tap to Pay cardholder/PIN data for single-use decryption keys.
KEK exchange
Key-encryption-key setup process referenced in Apple partnership and environment configuration phases.
prepare()
SDK call that prepares the device/session for Tap to Pay before running payments; required for successful taps.
Online PIN
PIN validated in real time by the issuer during authorization. Koard supports online PIN only (not offline PIN).
Settlement
Batch
Collection of transactions grouped for settlement, typically per MID/TID. Can be opened, edited, submitted, accepted, or rejected.
Batch cutoff / Batch window
Time period when transactions are included in a batch, and the time when the batch closes for settlement.
Settlement
Transfer of funds from the payment processor to the merchant account after batch processing.
Automated Batch Scheduling
Koard-managed timing and retries for opening and closing batches when Koard is the authorization layer.
API & security
API Key
Secret header credential for REST calls (x-koard-apikey). v5 keys use explicit scoped permissions (resource:action). Partner keys can manage sub-accounts; merchant keys are limited.
Scoped Permissions
Explicit grants on v5 API keys (for example payments:capture). Holding a write permission does not imply the matching read permission. Macros: all and legacy_all.
Webhook
HTTPS POST callback from Koard when events occur. Verify the HMAC-SHA256 signature, respond with HTTP 200 quickly, and handle deliveries idempotently. Transaction events fire on the attempt — read status and status_reason for the outcome.
SVIX
Webhook infrastructure provisioned with v2 account creation alongside Clerk org and API key in MMS.
Idempotency
Safe retry pattern using a client-generated event_id so network failures do not create duplicate charges. Lookup: GET /v1/transactions/event/{event_id}.
PCI DSS
Payment Card Industry Data Security Standard. Koard is built to meet PCI DSS practices including encryption and tokenization.
Tokenization
Replacing sensitive payment data with tokens to reduce PCI scope and exposure.
