Request contract

Tekmerion sends an HTTP POST to the merchant's registered KYT endpoint for each payment attempt that has completed sanctions screening. The request body is JSON; every request carries HMAC authentication headers.

Request body

{
  "kyt_invocation_id":  "string",
  "payment_attempt_id": "string",
  "payment_intent_id":  "string",
  "merchant_id":        "string",
  "invocation_no":      1,
  "source_address":     "0x...",
  "amount":             "100.000000",
  "token_id":           "0x...",
  "chain_id":           "string",
  "tx_hash":            "string",
  "deposit_address":    "0x...",
  "sanctions_result":   "clean | hit | unavailable",
  "geoblock_result":    "passed | blocked | null",
  "timestamp":          1714000000
}

Field rules

Field	Type	Rules
`kyt_invocation_id`	string	Unique identifier for this specific invocation. Merchants SHOULD log this value for their own invocation audit trail.
`payment_attempt_id`	string	Identifies the payment attempt this decision applies to. Provided for traceability; correlate payments in your system using `payment_intent_id`.
`payment_intent_id`	string	The parent payment intent identifier.
`merchant_id`	string	The merchant identifier on whose behalf this invocation is made.
`invocation_no`	integer	Starts at `1` for the first invocation per `payment_attempt_id`. Increments by `1` on each retry triggered by a prior `hold` decision.
`source_address`	hex string	The wallet address from which the customer transferred funds. This is the ERC-20 Transfer sender address from the on-chain deposit observation.
`amount`	decimal string	Token amount in token-native decimal precision (e.g., `"100.000000"` for 100 USDC). MUST be a decimal string. Floating-point encoding is not used.
`token_id`	hex string	The ERC-20 contract address of the transferred token.
`chain_id`	string	Numeric chain identifier encoded as a string.
`tx_hash`	hex string	Transaction hash of the observed deposit transfer.
`deposit_address`	hex string	The deterministic address to which the customer transferred funds. This is the on-chain correlation anchor for the payment attempt.
`sanctions_result`	enum	Tekmerion's sanctions screening result for `source_address`. `clean` — no match found. `hit` — positive match. `unavailable` — check could not be completed. Present in every request regardless of result.
`geoblock_result`	enum\|null	Session-level geoblock result. `passed` or `blocked` when a browser checkout session exists. `null` when no checkout session is present (direct on-chain transfer without a browser session).
`timestamp`	integer	Unix seconds at which Tekmerion dispatched this request. This value is also used as the HMAC base-string component and in `X-Tekmerion-KYT-Timestamp`.

Invocation numbering

invocation_no starts at 1 for the first KYT invocation on a given payment_attempt_id. Each subsequent re-invocation triggered by a hold decision increments invocation_no by 1. The pair (payment_attempt_id, invocation_no) uniquely identifies an invocation.

Sanctions result delivery

sanctions_result is present in every KYT request regardless of its value. A hit result does not prevent the invocation from being sent; the merchant receives the signal and responds with a decision. The compliance execution path for sanctions hits may differ from a standard approve/reject path independent of the merchant's KYT response.

When this request is sent

The KYT endpoint is called only after sanctions screening has completed. The endpoint is never called before on-chain deposit observation. Geoblock is evaluated at checkout session time, before deposit; geoblock_result carries the result as context but does not gate the invocation.

Request signing

Every outbound KYT request carries X-Tekmerion-KYT-Signature and X-Tekmerion-KYT-Timestamp headers. See Verifying requests for the full verification procedure.