Quickstart

This walkthrough takes one payment from creation to a verified Proof of Payment, using only HTTP. No SDK is required. Each step links to the contract that fixes the exact fields and rules.

The path is: get an API key → create a payment intent → send the customer to checkout → answer the KYT call → receive payment_finalized → retrieve and verify the Proof of Payment.

Step 1 — Get an API key

Complete onboarding to obtain a merchant-scoped API key and to authorize your settlement destinations. The destination whitelist is established by signing an EIP-712 message; any address you later return as a sweep or refund destination must already be whitelisted.

See Notification endpoints and API keys and Factory authorisation.

Step 2 — Create a payment intent

Issue an authenticated POST that creates a payment intent. A payment intent is a business request — the amount you expect to be paid — not a payment. Send the canonical fields as a top-level JSON object; authenticate with your API key as described in Authentication.

Request body:

{
  "order_reference": "order-1042",
  "base_amount": "100.00",
  "base_currency": "USD",
  "expires_at": "2026-06-13T18:00:00Z",
  "metadata": { "cart_id": "c_88f1" }
}

A successful create returns the canonical success envelope. The data object carries the payment_intent_id and the hosted checkout URL for the customer:

{
  "ok": true,
  "data": {
    "payment_intent_id": "pi_...",
    "checkout_url": "https://checkout.tekmerion.xyz/...",
    "expires_at": "2026-06-13T18:00:00Z"
  },
  "error": null,
  "meta": { "result_type": "singleton" }
}

Store the payment_intent_id. It is the correlation key for every later surface — the KYT call, the notification, and the Proof of Payment all carry it.

Step 3 — Send the customer to checkout

Redirect the customer to the checkout_url. The hosted checkout is served by Tekmerion: the customer connects a wallet and pays there. No merchant frontend code runs in this step, and you never handle the customer's funds or wallet session.

The customer's deposit lands at a deterministic deposit address bound to this payment. Once the deposit is observed on-chain and sanctions screening completes, Tekmerion calls your KYT endpoint.

Step 4 — Answer the KYT call

Tekmerion makes a synchronous POST to your registered KYT endpoint and waits for your decision within the SLA window. Verify the request signature before acting — see Verifying requests.

The request carries the on-chain context and Tekmerion's sanctions_result (abbreviated below — the Request contract lists every field):

{
  "kyt_invocation_id": "kyt_...",
  "payment_attempt_id": "att_...",
  "payment_intent_id": "pi_...",
  "source_address": "0x...",
  "amount": "100.000000",
  "token_id": "0x...",
  "chain_id": "8453",
  "tx_hash": "0x...",
  "deposit_address": "0x...",
  "sanctions_result": "clean"
}

You reply on the same HTTP response — there is no separate callback to send — so your decision is already tied to the payment Tekmerion asked about. If you need to look the order up before deciding, match on the payment_intent_id in the request body. The response itself carries only the decision and, where required, the destination address.

To accept the payment, respond approve with the whitelisted destination the funds should sweep to:

{
  "decision": "approve",
  "sweep_to": "0x..."
}

To return the funds instead, respond reject with a refund_to; to defer, respond hold with a retry_after. The decision is yours — Tekmerion relays it and cannot override it. The full rules are in the Response contract.

Step 5 — Receive payment_finalized

After the sweep executes on-chain, Tekmerion delivers a payment_finalized notification to your registered endpoint. For an approved-and-swept payment, finality_outcome is paid:

{
  "payment_intent_id": "pi_...",
  "notification_class": "payment_finalized",
  "finality_outcome": "paid"
}

Verify the signature, deduplicate by delivery_record_id, and acknowledge quickly. Treat this as a prompt to reconcile — not as the truth itself. Delivery is at-least-once and unordered, and a notification is a side effect, not the authoritative record. See Delivery semantics.

Step 6 — Retrieve and verify the Proof of Payment

The authoritative outcome is the signed Proof of Payment for the payment_intent_id. Retrieve it, verify its signature against the published signing key, and cross-check the on-chain transaction it references. A Proof of Payment that verifies is conclusive without trusting Tekmerion.

See Proof of Payment and Verifying a PoP.