TRtrytoku
Risk flow validator executions

Create a validation and the link the customer opens

Changed on

Create a pending validation from the caller's own configuration and return its link.

The organization's own surface, reached server-to-server with an api-key, and the only one where the caller chooses validator_config — there the caller is the organization, so configuring its validation is its call.

The execution starts PENDING and nothing runs here, so the front begins from zero. The customer may open the link hours later, and a session token minted now would already be expired.

Idempotent while the execution is active, so a retried call hands back the same link rather than minting a second one — and a repeat is a 200 while only the first call is a 201.

post/public/risk-flow-validator-executions

Request

  • Base URL
    https://api.trytoku.com
  • URL
    https://api.trytoku.com/public/risk-flow-validator-executions
  • Auth
    API key in header x-api-key

Request body

external_reference_idstring required

The caller's own correlation key. It travels out in the result webhook, so it must be an id the organization is willing to see there.

portal_urlstring required

The organization's portal the customer will be sent to. It has to be one this organization has registered — a portal it does not own is a 422.

validator'conditions' | 'fraud-engine' | 'identity' | 'signature' | 'three-ds' required

Which validator to run. It also decides which shape validator_config and validation_context take: a name this service has no validator for is refused with UNKNOWN_VALIDATOR.

Example request

{
  "external_reference_id": "order-99213",
  "portal_url": "https://pagos.example.com",
  "validator": "identity"
}

Response

An execution was already active for that reference, so this call returned it and its link instead of minting a second one. The link is the frozen one: two calls that differ only in portal_url cannot produce two places to send the same customer, who may already be looking at the first link.

expires_atstring date-time required

When the link stops working: 72 hours after it was minted. Until then it stays usable until the validation is approved or the attempts run out, so a recoverable rejection — a blurry photograph, a mistyped CURP — is retried on this same link. Typed as a datetime rather than a string so the contract carries the format instead of leaving each consumer to guess it.

id_validator_executionstring required

The opaque token identifying the execution, for tracing it afterwards.

urlstring nullable

Where to send the customer: the organization's portal, the validator's own frontend, and the token. Null when no step of the plan ever needs the customer.

Example response

{
  "expires_at": "2026-08-09T14:22:31Z",
  "id_validator_execution": "rve_8f3kd0aQR7yA2sVpLmZ4wE1n",
  "url": "https://pagos.example.com/identity-validator/rve_8f3kd0aQR7yA2sVpLmZ4wE1n"
}

Changes