Payment Lifecycle

Koard facilitates card acceptance and routes payment requests to the merchant's configured processor. A payment can contain several events: the original sale or preauth, followed by capture, tip adjustment, reversal, or refund.

Before Taking a Payment

Authenticate the merchant, load its locations, and select the active location. Provide a location selector in your app's settings. The location's linked terminal determines the processor configuration and merchant/terminal identifiers used for that merchant. Show the selected location to the operator and block payments until a valid location is selected. See Active location and terminal routing.

Prepare the reader using the relevant iOS or Android guide. Persist an event_id before each operation that exposes one.

Operations

Operation	iOS SDK	Android SDK	REST follow-up
Sale	sale	sale	Initiation is handled by the reader SDK
Preauth	preauth	preauth	Initiation is handled by the reader SDK
Capture	capture	capture	POST /v3/payments/{transaction_id}/capture
Incremental auth	auth	incrementalAuth	POST /v3/payments/{transaction_id}/auth
Tip adjust	tipAdjust	adjust	POST /v1/payments/{transaction_id}/adjust
Reverse	reverse	reverse	POST /v1/payments/{transaction_id}/reverse
Refund	refund, optionally withTap: true	Reference refund, or Activity-based refund(..., withTap = true) / refundEmv	POST /v1/payments/{transaction_id}/refund for a reference refund

The released SDKs do not expose identical arguments for every operation. Use each platform's example. Initial card-present requests use SDK-generated encrypted reader data; a PAN or a generic test-card number cannot replace that data.

Transaction Identifiers

• transaction_id groups a payment's lifecycle and is used for follow-up operations.
• event_id identifies an individual operation. Retain it with your order so an uncertain outcome can be recovered.
• GET /v1/transactions/event/{event_id} reads the event visible to your account using an API key with payments:read.

An HTTP success alone does not establish that funds were captured. Inspect status, the authorized amount, and the processor response, including partial approvals.

REST Status Values

Status	Meaning
pending	Outcome or external input is still pending
surcharge_pending	Cardholder surcharge confirmation is required
authorized	Funds are held; capture or reverse as appropriate
captured	Sale or capture succeeded; settlement follows
settled	Settlement was recorded
declined	Payment was declined
error	An error was recorded; reconcile any uncertain processor outcome
refunded	A refund event succeeded; inspect amounts for partial refunds
reversed	A reversal event succeeded
canceled	The flow was canceled

These are REST values. SDK enums can use platform-specific names, such as iOS surchargePending, and include reader or UI states.

A typical preauth progresses from authorized to captured and then settled. A sale reaches captured directly. Refunds and reversals are separate events on the original transaction; use event history and amounts when reconciling.

Amounts and Breakdowns

Use integer minor currency units for amounts, for example 1000 for USD $10.00. Keep the final subtotal, tax, tip, and surcharge consistent with the total sent to the processor.

For a surcharge, specify one of amount or percentage, or use bypass: true without either. Percentage surcharge values use whole percent units, for example 3.5 for 3.5%. Fixed surcharge amounts avoid ambiguity when you have already calculated the fee. REST tip adjustment is different: its percentage is an integer from 1 through 100.

If the final capture exceeds the current authorized amount, obtain any required incremental authorization first. Processor and card rules govern supported adjustments and settlement cutoffs.

Recovering an Uncertain Outcome

A timeout, lost response, or server error can occur after the processor receives a payment. Do not start a second sale with a new event ID to compensate. Look up the persisted event ID, reconcile the outcome, and follow Idempotency. A lookup returning 404 alone does not prove that an in-flight request never reached the processor.

Webhooks and Settlement

Subscribe to the operation event names documented in Available Events: transaction.create, transaction.authorize, transaction.sale, transaction.capture, transaction.increment, transaction.tip_adjust, transaction.cancel, transaction.reverse, and transaction.refund.

The webhook body is the transaction object; delivery metadata is provided in the webhook headers. Verify signatures and deduplicate deliveries. Event names identify operations, so also inspect the transaction status and amounts.

Settlement is reported separately through batch APIs and events. The supported Fiserv integration manages batches automatically; customers must not manually open, close, or edit those batches.