Integration surface map

A Tekmerion integration touches four surfaces, plus a fifth that requires no merchant code. Each surface has a fixed call direction and a fixed synchronicity. Knowing which side initiates a call, and whether the call is synchronous, determines where decision authority and reconciliation responsibility sit.

The surfaces at a glance

REST API — merchant to Tekmerion

The REST API is the merchant's inbound surface. It is synchronous request/response over HTTP with JSON bodies, authenticated by a merchant-scoped API key. The merchant calls it to create payment intents, read payment status, and reconcile outcomes.

This is the only surface the merchant initiates. Every other server-to-server surface is Tekmerion calling the merchant.

See API reference.

KYT webhook — Tekmerion to merchant, decision returned

For each payment attempt that reaches post-deposit compliance, Tekmerion makes a synchronous outbound call to the merchant's KYT endpoint and waits for a decision within the SLA window. The merchant returns approve with a sweep_to destination, reject with a refund_to destination, or hold to defer.

Decision authority lives with the merchant. Tekmerion screens the source of funds for sanctions and geoblock before invoking the endpoint, but the approve/reject outcome — whether funds sweep to the merchant or refund to the customer — is structurally the merchant's, and Tekmerion cannot override it.

This is the one inbound call where the merchant's response governs execution. The merchant's endpoint must verify the request signature before acting.

See KYT webhook.

Notification webhooks — Tekmerion to merchant, informational

Tekmerion delivers asynchronous notifications to the merchant's registered endpoints as a payment progresses and finalizes. Delivery is at-least-once with no ordering guarantee.

A notification is a side effect of a payment event, not the authoritative record of it. The receiving endpoint deduplicates by delivery_record_id, acknowledges fast, and reconciles canonical state elsewhere. The terminal class is payment_finalized, carrying finality_outcome of paid, refunded, or failed.

Never gate fulfilment solely on having received a webhook: a missed notification does not mean the event did not occur, and a received one is a delivery-plane signal, not proof.

See Notifications.

Proof of Payment — the authoritative outcome

Proof of Payment is the surface the merchant verifies rather than receives. Every finalized payment yields a signed, self-contained artifact that can be checked against its signing key and cross-checked on-chain without trusting Tekmerion.

Reconciliation runs against the API and the Proof of Payment — not against the notification plane. When an outcome must be relied upon, it is the Proof of Payment, retrieved and verified, that settles the question.

See Proof of Payment.

Hosted checkout — the customer's surface

The hosted checkout is the customer-facing surface, served by Tekmerion. The merchant directs a customer to a checkout URL obtained when the payment intent is created; the customer connects a wallet and pays there. No merchant frontend code runs in this surface, and the merchant never handles the customer's funds or wallet session.

Reconciliation, not webhook receipt

Two surfaces inform; two surfaces are authoritative. The KYT webhook and notification webhooks are calls Tekmerion makes to the merchant — useful, but a signal. The REST API and Proof of Payment are what the merchant queries when an outcome must be trusted.

One consequence worth internalizing early: a payment_finalized notification with finality_outcome failed, or an API status of FAILED carrying finality_outcome duplicate_payment, does not always mean the payment did not go through. A duplicate deposit can lose winner selection while the payment_intent_id is already PAID. Resolve such cases against the API and the Proof of Payment for that intent. See Event catalog.