Idempotency

Every Koard payment request carries an event_id that uniquely identifies a single attempt. Use it to make your integration safe to retry on network failures, app crashes, or unclear outcomes — without ever charging a cardholder twice.

Before You Begin

• Read the Payment Lifecycle guide for an overview of how transactions move through their states.
• Have an authenticated API key or SDK session ready so you can call the lookup endpoint described below.

event_id and transaction_id

Koard uses two different identifiers, and they answer different questions.

A single transaction can have multiple event_ids tied to it. For example, a hotel charge might look like:

Each line is a separate API call with a separate event_id. They all carry the same transaction_id so you can correlate them in reports, webhooks, and the dashboard.

Generating event_id

• Format: UUID4 (e.g. b1f4d6a2-9c8e-4af7-b1d2-91a6e8c1f203).
• Generated by your client, before the request leaves the device or your backend.
• Persisted durably by your client until you've confirmed the outcome (don't lose it to an app kill or process restart — it's the only way to look the attempt up later).
• Globally unique — event_id is the primary key for the attempt, so re-using one will be rejected as a duplicate.

If you omit event_id on a request, Koard generates one for you. Don't rely on this — without a client-generated event_id saved before the call, you cannot safely retry or verify the outcome of a lost request.

How retries are protected

Every payment endpoint checks event_id against existing transactions before processing. The two possible outcomes:

This is what makes the SDK retry protocol below safe.

Verifying a transaction's outcome

Whenever your client is unsure whether a previous request reached Koard (network drop, timeout, app killed mid-call), look the attempt up by event_id:

GET /v1/transactions/event/{event_id}
Authorization: Bearer <your_api_key>

Possible responses:

A transaction body returned from this endpoint includes status. Map it as follows:

Once you read a terminal status, the attempt is done — clear your local copy of the event_id and move on.

Alternative: reconcile from your own webhook events

Every transaction Koard processes also fires a webhook to any endpoint you've registered (see Webhooks). The webhook payload carries the same event_id and transaction_id that the API call returns, so you can use the webhook as an independent source of truth.

If your team already operates a backend with its own transaction store and APIs, you can layer a second recovery mechanism on top of the polling protocol above:

• Persist every webhook event into your own database, keyed by event_id.
• Expose a lookup in your own API (e.g., GET /your-backend/transactions?event_id=…).
• When a client device can't reach Koard but can reach your backend, have it poll your API instead — your backend already knows the outcome from the webhook delivery.

This is optional. The GET /v1/transactions/event/{event_id} endpoint described above is the canonical source and is sufficient on its own. The webhook mirror is useful when your client only has connectivity to your own infrastructure, when you want a single reconciliation point that already aggregates other systems, or when you want to give your devices an alternate fallback path that doesn't depend on Koard reachability.

SDK retry protocol

Use this protocol whenever your client doesn't receive a clear 2xx or 4xx response from a payment call:

1. Before every payment call, generate a fresh event_id (UUID4) and store it durably on the device.
2. POST the payment with that event_id.
3. Branch on the response:
   • 2xx — Parse the status field. You're done. Clear the stored event_id.
   • 400 "This event ID already exists" — Your previous attempt already landed. Skip to step 4 to look up the outcome.
   • Other 4xx — A validation or authorization error. Surface to the caller. Clear the stored event_id.
   • 5xx, timeout, or no response at all — The outcome is unknown. Proceed to step 4. Do not re-POST immediately.
4. Poll GET /v1/transactions/event/{event_id} with backoff (suggested: 1 s, 2 s, 5 s, 10 s, 30 s, capped at ~2 minutes total).
   • 200 with a terminal status — Surface that status. Clear the stored event_id.
   • 200 with pending or surcharge_pending — Keep polling; the transaction is still in flight.
   • 404 — The original POST never reached Koard. Re-POST once with the same event_id, then resume polling.

Worked example

A point-of-sale device taps a card. The SDK sends a Sale request with event_id=b1f4d6a2-…. Mid-flight, the device's Wi-Fi drops and the response never returns.

Had step 3 returned 404, the client would have re-POSTed the Sale with the same event_id=b1f4d6a2-…. Koard would have either processed it as a new attempt (if the first POST never landed) or returned the duplicate-event-id error (if it had landed but the response was lost), at which point the client would resume polling.

Best practices

• Generate event_id once per attempt, on the client.
• Persist the event_id durably until you've confirmed a terminal outcome — keychain on iOS, EncryptedSharedPreferences on Android, durable storage on backends.
• Never reuse an event_id for a different attempt. If you want to start over (e.g., the cardholder taps "Cancel" and re-taps), generate a new one.
• Cap your polling window (~2 minutes is a reasonable default) and surface "uncertain" to the merchant if it expires — they can verify in the dashboard.
• Surface the transaction_id in your receipts and merchant tooling so downstream lifecycle calls (capture, refund, etc.) have everything they need.