---
title: "Create a validation and the link the customer opens"
method: POST
path: "/public/risk-flow-validator-executions"
tags: ["Risk flow validator executions"]
---

# Create a validation and the link the customer opens

`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`

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.

## Request body

- CreatePublicValidatorExecutionPayload: Body the organization sends to mint a validation link, server-to-server with api-key. The only surface where the caller chooses `validator_config`: it is the organization's own validation being configured, not a browser choosing its checks. There is no `risk_flow` here — this creation is not part of a journey, so nothing resolves the config and the caller supplies it.
  - `execution_context` union: Where and under what terms the validation was run. The one context that is not per validator: nothing in it is about what is being validated.
    - ExecutionContext: Where and under what terms the validation was run. Deliberately **not** split per validator, unlike `validation_context`: nothing here is about what is being validated. Every validator records the same two facts for the same reason — a dispute asks where the customer was and which terms they accepted, whichever check they were taking. Both fields are optional because both surfaces that fill them can legitimately have neither: a service-to-service `/run` has no browser to take an IP from, and an organization that publishes no terms has no version to declare.
      - `ip` string, nullable: IP the customer's request arrived from.
      - `version_tc` string, nullable: Version of the terms and conditions the customer accepted.
    - object
  - `external_reference_id` string, 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_url` string, 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.
  - `validation_context` union: What was declared about the customer, frozen into the execution. Which shape applies is decided by the validator: a context that is not what its validator accepts is refused with `INVALID_VALIDATION_CONTEXT`, naming the fields that failed and never their values.
    - ConditionsValidationContext: The selection being evaluated, and the entities it is evaluated against. An entity with a row is named by its id (`CONDITION_ENTITY_IDS`) or listed (`CONDITION_ENTITY_ID_LISTS`), and its fields, aggregates and pending installments are read from there, so no two callers count them differently. `entities` carries only an entity with no row yet, like the transaction before it is charged.
      - `checkout_session_id` string, nullable: The session, which is how a guest with no customer is still counted: the retry limit exists for card testing, and card testing does not sign in.
      - `entities` object: The catalogue's `column` fields of an entity that has no row yet, keyed by entity then by field. An entity named by its id is read off its row and carries no snapshot, and `transaction.operation` is read off `operation`, never off a row or a snapshot.
      - `gateway` string, nullable: Name of the gateway this payment is about to run through, as the catalogue's `transaction.gateway` carries it. The aggregates counted per gateway scope by this.
      - `id_account` integer, nullable: Private id. Scopes every counted aggregate.
      - `id_customer` integer, nullable: Private id of the customer the aggregates are counted for.
      - `id_customer_action_metadata` integer, nullable: Private id of the customer action metadata of the attempt being evaluated, excluded from the counts that ask what came before it.
      - `id_payment_instrument` integer, nullable: Private id of the instrument, on the aggregates counted per instrument.
      - `id_transaction` integer, nullable: Private id of the transaction the `transaction` fields are read off, once it exists.
      - `ids_invoice` integer[]: Private ids of the invoices this checkout is about to charge. An `invoice` condition is read off each of them.
      - `ids_subscription` integer[]: Private ids of the subscriptions the charged invoices belong to. A `subscription` condition is read off each of them.
      - `operation` 'enrollment' | 'payment': What the customer is doing, which decides where an operation is counted.
    - FraudEngineValidationContext: What this evaluation runs over. The caller supplies all of it and the adapter reads no database.
      - `amount` integer, required: In the currency's lowest denomination.
      - `card_reference` string, required: Handle of the card in the cardholder environment's store. Never a card number.
      - `currency` string, required: ISO 4217 code of the amount.
      - `evaluation_type` 'ONETIME_PAYMENT' | 'ENROLLMENT', required: Whether the evaluation is about paying or about enrolling a card.
      - `fraud_session_id` string, required: Device session collected by the provider's SDK.
      - `id_account` integer, required: Private id. The context never crosses a public surface.
      - `id_customer` integer, nullable: Private id of the customer, when there is one.
      - `id_orchestration` string, required: The payment's orchestration id.
      - `id_payment_method` integer, nullable: Private id of the payment method, on an enrolment.
      - `id_transaction` integer, nullable: Private id of the transaction, on a payment.
    - IdentityValidationContext: What was declared about the person whose document is about to be read. One of the two is required by `validator_config.match`, not by this model: with `input` the customer typed it into the form, with `declared_data` the organization supplied it, and with `false` there is no comparison and neither is needed. Which of those applies is the frozen config's to say, so declaring neither is refused by the `identity` adapter — as `NO_DECLARED_DATA` — and not here. What this model *does* refuse is a value that could never match anything: a malformed CURP is caught at creation, before an execution exists and before an OCR is paid for, instead of at `ine-match`, where the code it produces is non-retryable and closes the whole execution.
      - `curp` string, nullable: CURP declared for the person being validated.
      - `rfc` string, nullable: RFC declared for the person being validated. Compared by its first 10 characters — the part it shares with the CURP.
    - SignatureValidationContext: The business object being signed, who signs it, and the contract's own text. ⚠️ **This is the one context that is open on purpose.** Everything the adapter does not consume itself is passed through as the `{{ }}` fields the provider substitutes into the document, so the fields a caller may send depend on the document it sent in `validator_config`. Forbidding extras here would make every new contract a release of this library. What is declared is what the adapter reads structurally: the entity the document is attached to, where the signer is sent afterwards, and the address the signing invitation goes to. `id_entity` is required because an empty one attaches the document to nothing — its owner is the service that receives the provider's notification, so a document with no entity is one nobody is told about. The entity *type* is not here. It is `validator_config`'s, so that the caller of the browser's creation cannot attach the document to a different kind of object.
      - `email` string, nullable: Where the signing invitation is sent. Optional at the provider.
      - `id_entity` string, required: Id of the business object being signed, e.g. the mandate.
      - `redirection_url` string, required: Where the provider sends the signer once the ceremony finishes.
    - ThreeDsValidationContext: What the authentication runs over, declared by the step run at `PRE_TRANSACTION_PROCESSING` that creates the execution: the card, the gateway being charged and the amount to authenticate.
      - `amount` number, nullable: The amount the issuer is asked to authenticate, in the currency's major unit. Required by the steps that authenticate.
      - `card_brand` string, nullable: The card's brand, as the cardholder environment reads it.
      - `card_reference` string, required: Handle of the card in the cardholder environment's store. Never a card number.
      - `currency` string, nullable: ISO 4217 code of the amount.
      - `gateway` union: Which gateway the transaction is charged through: a payment intent gateway on a payment, a payment method gateway on an enrolment. Required by the steps that authenticate.
        - 'transbank_oneclick' | 'klap_oneclick' | 'patpass' | 'toku_onetime' | 'toku_pac' | 'fintoc_pac' | 'universo_pac' | 'ecert_pac' | 'external_pac' | 'manual_pac' | 'internal_psp' | 'domiciliation' | 'mx_banco_bbva' | 'mx_banco_bancomer' | 'payment_orchestration' | 'getnet' | 'getnet_pos' | 'transbank' | 'transbank_webpay_plus' | 'khipu_transfer' | 'fintoc_transfer' | 'floid_transfer' | 'toku_transfer' | 'conciliation' | 'pb_transfer_cl_banco_de_chile' | 'pb_transfer_cl_banco_de_chile-evertec' | 'pb_transfer_cl_banco_santander' | 'pb_transfer_cl_banco_santander-evertec' | 'pb_transfer_cl_banco_santander_direct' | 'pb_transfer_cl_banco_santander-native' | 'pb_transfer_cl_banco_scotiabank' | 'pb_transfer_cl_banco_scotiabank_direct' | 'pb_transfer_cl_banco_scotiabank-native' | 'pb_transfer_cl_banco_bci' | 'pb_transfer_cl_banco_bci-native' | 'pb_transfer_cl_banco_bci_direct' | 'pb_transfer_cl_banco_bci-serviex' | 'pb_transfer_cl_banco_itau' | 'pb_transfer_cl_banco_itau-evertec' | 'pb_transfer_cl_banco_estado' | 'pb_transfer_cl_banco_bice' | 'pb_transfer_cl_banco_falabella' | 'arcus_transfer' | 'stp_transfer' | 'cobre_transfer' | 'monex_transfer' | 'oxxo' | 'paycash' | 'dapp' | 'tapi' | 'puntored' | 'cash_pickup' | 'multigateway_onetime' | 'toku_gateways_conekta' | 'toku_gateways_stripe' | 'toku_gateways_mercado_pago' | 'toku_gateways_open_pay' | 'toku_gateways_pay_u' | 'toku_gateways_paypal' | 'toku_gateways_net_pay' | 'po_open_pay' | 'po_rapyd' | 'po_conekta' | 'po_stripe' | 'po_kushki' | 'po_fiserv' | 'po_evo_payments' | 'po_paypal' | 'po_mit' | 'openpay' | 'rapyd' | 'conekta' | 'stripe' | 'kushki' | 'mit' | 'codi_qr' | 'codi' | 'paypal' | 'br_banco_itau' | 'br_banco_itau_boleto' | 'br_banco_bradesco_boleto' | 'br_banco_bradesco_pix' | 'br_sicredi_boleto' | 'servipag' | 'servipag_portal' | 'servipag_caja_presencial' | 'servipag_caja_express' | 'cards_batch_mx_recurring_pst' | 'amex_batch_mx_recurring_pst' | 'braintree' | 'pagarme' | 'br_paulista_servicios_automatic_debit' | 'mx_banco_santander' | 'mx_banco_bbva_bancomer' | 'mx_banco_banorte' | 'mx_banco_banorte_h2h' | 'mx_banco_scotiabank' | 'mx_banco_hsbc' | 'mx_banco_citibanamex' | 'mx_banco_multiva' | 'mx_amex' | 'mx_banco_banbajio' | 'mx_banco_banregio' | 'mx_banco_sabadell' | 'mx_belvo' | 'mx_bbva_cie' | 'internal_balance' | 'fiserv' | 'cielo' | 'belvo' | 'mx_banco_scotiabank_h2h_external' | 'iniciador' | 'qi_tech' | 'evo_payments' | 'cl_banco_de_chile' | 'cl_banco_bci' | 'cl_banco_santander' | 'cl_banco_scotiabank' | 'cl_banco_security' | 'cl_banco_consorcio_fidi' | 'transdata' | 'br_banco_do_brasil' | 'br_banco_santander' | 'br_banco_citibank' | 'rede' | 'mercadopago' | 'br_caixa_via_accesstage' | 'br_banco_de_brasilia' | 'worldpay' | 'br_banco_de_brasilia_via_accesstage' | 'br_santander_via_accesstage' | 'br_bradesco_via_accesstage' | 'br_banco_do_brasil_via_accesstage' | 'br_c6_via_accesstage' | 'br_sicoob_via_accesstage' | 'br_itau_via_accesstage' | 'external_payment' | 'br_sicoob' | 'br_caixa' | 'br_btg' | 'toku_mx_belvo' | 'toku_mx_banco_bbva_bancomer' | 'servipag_button' | 'servipag_cashier' | 'servipag_web' | 'servipag_express' | 'sencillito_cashier' | 'sencillito_web' | 'scotiabank_cashier' | 'unired': Integración por la que se cursa un intento de cobro: el adquirente, banco o recaudador concreto que lo ejecuta. La mayoría de los valores corresponde a una institución de un solo país; el resto son mecanismos propios de Toku, como `internal_psp`, `manual_pac` o `external_payment`. Es el conjunto más amplio de gateways de Toku y crece cada vez que se habilita una institución nueva, así que conviene leerlo como una lista abierta y no agotar sus valores en el código. Para el gateway con que se inscribió un medio de pago, ver `PaymentMethodGateway`.
        - 'transbank_oneclick' | 'klap_oneclick' | 'patpass' | 'toku_pac' | 'fintoc_pac' | 'universo_pac' | 'external_pac' | 'ecert_pac' | 'manual_pac' | 'internal_psp' | 'domiciliation' | 'mx_banco_bbva' | 'mx_banco_bancomer' | 'mx_banco_banbajio' | 'mx_banco_banorte' | 'mx_banco_banorte_h2h' | 'mx_banco_banregio' | 'mx_banco_bbva_bancomer' | 'mx_banco_citibanamex' | 'mx_banco_santander' | 'mx_banco_scotiabank' | 'mx_banco_scotiabank_h2h_external' | 'evo_payments' | 'conekta' | 'stripe' | 'kushki' | 'openpay' | 'paypal' | 'getnet' | 'fiserv' | 'transbank' | 'toku_gateways' | 'payment_orchestration' | 'cards_batch_mx' | 'cards_batch_mx_recurring_pst' | 'amex_batch_mx_recurring_pst' | 'atoa_batch_mx_recurring_pst' | 'braintree' | 'cielo' | 'pagarme' | 'belvo' | 'iniciador' | 'qi_tech' | 'mit' | 'mit_amex' | 'rede' | 'br_banco_do_brasil' | 'br_banco_itau' | 'br_banco_santander' | 'br_banco_citibank' | 'br_banco_de_brasilia_via_accesstage' | 'br_santander_via_accesstage' | 'br_bradesco_via_accesstage' | 'br_banco_do_brasil_via_accesstage' | 'br_c6_via_accesstage' | 'br_sicoob_via_accesstage' | 'br_caixa_via_accesstage' | 'br_itau_via_accesstage' | 'br_sicoob' | 'worldpay' | 'br_caixa' | 'br_btg' | 'br_banco_itau_boleto' | 'br_banco_bradesco_boleto' | 'br_sicredi_boleto' | 'br_banco_de_brasilia': Integración a través de la cual se inscribió un medio de pago y por la que se cobrará después. Combina el adquirente o banco con la modalidad de inscripción — por ejemplo `transbank_oneclick` es una tarjeta inscrita en Oneclick de Transbank, y `fintoc_pac` un mandato de descuento automático inscrito vía Fintoc. Es un conjunto distinto de `PaymentIntentGateway`, que identifica por dónde sale un cobro puntual: no todo gateway capaz de cobrar sirve para inscribir un medio de pago.
      - `id_orchestration` string, required: The payment's orchestration id.
      - `id_organization` integer, required: Private id of the organization. The context never crosses a public surface.
      - `is_demo` boolean: Whether the payment runs against the provider's testing environment.
      - `organization_name` string, nullable: The merchant name the issuer shows the cardholder.
    - object
  - `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`.
  - `validator_config` union, required: How the validation is set up, frozen into the execution exactly as it arrives — a later edit of wherever it came from cannot change a validation already in flight. Which shape applies is decided by the validator named beside it; one it cannot run is refused with `INVALID_VALIDATOR_CONFIG`.
    - ConditionsValidatorConfig: The plan `conditions` runs: exactly one shape of rule, extras forbidden so a misspelled rule cannot plan as "no rule matched" and PASS everything.
      - `any_of` ConditionGroup[], nullable: The entity rules: groups joined by OR, the conditions inside one by AND. Two levels, which is what `(customer AND invoice) OR (payment method)` needs and no more.
        - `all_of` Condition[], required: Conditions that must all hold for this group to match.
          - `entity` 'customer' | 'invoice' | 'subscription' | 'transaction' | 'payment_method', required
          - `field` string, required: Which field of the entity, as it travels on the wire.
          - `operator` 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in', required
          - `params` ConditionParams: Extra input some fields need before they can be read at all.
            - `final_installments` integer, nullable: How many of the subscription's last pending installments the selection has to pay, on `subscription.completes_with_selection`. A plan with fewer left completes when all of them are selected.
            - `key` string, nullable: Which key to read, on the fields read by key.
            - `window_days` integer, nullable: Window in days, on the aggregates counted over one.
            - `window_seconds` integer, nullable: Window in seconds, on the aggregates counted over one.
          - `value` object, required: The scalar, or the list a set operator reads, under one key.
      - `invoices` InvoicesConditions: The conditions evaluated over the invoice selection.
        - `subscription_completion` SubscriptionCompletionRule, required: The rule: the selection pays the last `n_to_complete` installments of the subscription.
          - `after_action` ConditionsAfterAction, required: What happens when the rule matches. Today the only action is filtering payment products.
            - `type` 'toku_product_filter', required
            - `value` string[], required: The toku products that stay available when the rule filters.
          - `n_to_complete` integer, required: How many final installments count as completing the subscription.
      - `max_attempts` integer: Chances to pass before the execution closes.
    - FraudEngineValidatorConfig: The frozen plan: the provider's channel for this account, and how its answer is read. `mode` and `trial_run_evaluated_percentage` are Toku's policy, kept internal by the collection.
      - `channel` 'HIGH_RISK' | 'MEDIUM_RISK' | 'LOW_RISK' | 'HIGH_RISK_BETA' | 'LOW_RISK_BETA' | 'MEDIUM_RISK_BETA' | 'MEDIUM_RISK_MX' | 'LOW_RISK_MX' | 'LOW_RISK_BR' | 'MEDIUM_RISK_BR', required: Enum for fraud engine channels used in the fraud evaluation process. The channels are defined as n different risk levels associated with the organizations that will use the fraud engine.
      - `max_attempts` integer: Evaluations this execution may spend before it closes.
      - `mode` 'ENABLED' | 'TRIAL_RUN' | 'DISABLED': Enum for how the external fraud engine is applied to an account's transactions. ENABLED evaluates and acts, TRIAL_RUN evaluates a sample without acting, DISABLED never evaluates.
      - `provider` 'KOUNT' | 'TOKU', required: Enum for fraud engine providers used in Toku.
      - `score_threshold` number, nullable: Score at or above which the evaluation passes, replacing the provider's own decision entirely. Null lets that decision stand, and a review counts as a pass.
      - `trial_run_evaluated_percentage` integer: Share of the traffic a trial run evaluates.
    - IdentityValidatorConfig: The plan `identity` runs: which checks, and how many attempts the customer gets. Declared so a caller composing one has a typo refused at its own callsite instead of by the orchestrator's 422. Enforcement stays there: only `plan()` knows what this deploy can run.
      - `biometrics` boolean: Whether the customer is asked for a second, facial capture.
      - `capture` 'ine': The document `identity` captures from the customer.
      - `manual_upload` 'allowed' | 'only': Whether the customer may hand over photographs of the document instead of running the capture SDK, and whether that is the only way they can. Three states out of one field, which is why it is not a boolean: absent is the SDK alone, and the two members below are the ways the upload is on the table. Closed for the same reason as `MatchSource` — the orchestrator has to know what to do with a value before a caller can name it. **The upload is the weaker path and deliberately so.** The provider's capture-quality and anti-spoofing gate never runs on an uploaded photograph, so a photograph of a photograph is read. What still holds is whatever `renapo` and `match` establish about the value read off it.
      - `match` 'input' | 'declared_data': Where the document `identity` compares the card against was declared. Closed because adding a source is a deliberate change on both sides: the orchestrator has to know where to read it from before a caller can name it.
      - `max_attempts` integer: Rejected attempts the customer gets before the execution closes.
      - `ocr` 'in_house' | 'provider': The reader that takes the data off the captured document.
      - `renapo` boolean: Whether the CURP is checked against RENAPO. Billed per call.
    - SignatureValidatorConfig: The plan `signature` runs: the base64 contract itself, and what kind of object it attaches to. `places` stays untyped because its entries are the provider's shape: typing them would make every new kind of signer input a release.
      - `attestation` string, nullable: Seal the provider applies to the signed document, e.g. `mx_nom151`.
      - `document` string, required: The contract to be signed, a base64-encoded DOCX.
      - `entity_type` string, required: Kind of business object the signed document attaches to.
      - `language` string, nullable: Language the ceremony is presented in, e.g. `es`.
      - `max_attempts` integer: Chances to pass before the execution closes.
      - `places` object[], nullable: Inputs the signer fills during the ceremony, positioned by the document's `[[key]]` markers.
      - `title` string, nullable: Title the signer sees for the document.
    - ThreeDsValidatorConfig: The frozen plan: where the authentication can run and how it runs. Whether it runs is the other validators' to ask, through `require_three_ds`, unless `always_authenticate` makes it every payment's. `available_gateways` is Toku's policy, kept internal by the collection.
      - `accept_unavailable_challenge_response` boolean: Whether an authentication the provider could not complete still counts as one.
      - `always_authenticate` boolean: Authenticate every payment, whether or not another validator asked for it. A rejection still ends the journey before the authentication.
      - `always_request_challenge` boolean: Mandate a challenge instead of letting the issuer decide. Off, the issuer chooses frictionless or challenge; on, every payment carries the friction.
      - `available_gateways` union[], required: Gateways this account can run 3DS on. Maintained by Toku and never shown to the webapp; the context's `gateway` is one of them.
        - union
          - 'transbank_oneclick' | 'klap_oneclick' | 'patpass' | 'toku_onetime' | 'toku_pac' | 'fintoc_pac' | 'universo_pac' | 'ecert_pac' | 'external_pac' | 'manual_pac' | 'internal_psp' | 'domiciliation' | 'mx_banco_bbva' | 'mx_banco_bancomer' | 'payment_orchestration' | 'getnet' | 'getnet_pos' | 'transbank' | 'transbank_webpay_plus' | 'khipu_transfer' | 'fintoc_transfer' | 'floid_transfer' | 'toku_transfer' | 'conciliation' | 'pb_transfer_cl_banco_de_chile' | 'pb_transfer_cl_banco_de_chile-evertec' | 'pb_transfer_cl_banco_santander' | 'pb_transfer_cl_banco_santander-evertec' | 'pb_transfer_cl_banco_santander_direct' | 'pb_transfer_cl_banco_santander-native' | 'pb_transfer_cl_banco_scotiabank' | 'pb_transfer_cl_banco_scotiabank_direct' | 'pb_transfer_cl_banco_scotiabank-native' | 'pb_transfer_cl_banco_bci' | 'pb_transfer_cl_banco_bci-native' | 'pb_transfer_cl_banco_bci_direct' | 'pb_transfer_cl_banco_bci-serviex' | 'pb_transfer_cl_banco_itau' | 'pb_transfer_cl_banco_itau-evertec' | 'pb_transfer_cl_banco_estado' | 'pb_transfer_cl_banco_bice' | 'pb_transfer_cl_banco_falabella' | 'arcus_transfer' | 'stp_transfer' | 'cobre_transfer' | 'monex_transfer' | 'oxxo' | 'paycash' | 'dapp' | 'tapi' | 'puntored' | 'cash_pickup' | 'multigateway_onetime' | 'toku_gateways_conekta' | 'toku_gateways_stripe' | 'toku_gateways_mercado_pago' | 'toku_gateways_open_pay' | 'toku_gateways_pay_u' | 'toku_gateways_paypal' | 'toku_gateways_net_pay' | 'po_open_pay' | 'po_rapyd' | 'po_conekta' | 'po_stripe' | 'po_kushki' | 'po_fiserv' | 'po_evo_payments' | 'po_paypal' | 'po_mit' | 'openpay' | 'rapyd' | 'conekta' | 'stripe' | 'kushki' | 'mit' | 'codi_qr' | 'codi' | 'paypal' | 'br_banco_itau' | 'br_banco_itau_boleto' | 'br_banco_bradesco_boleto' | 'br_banco_bradesco_pix' | 'br_sicredi_boleto' | 'servipag' | 'servipag_portal' | 'servipag_caja_presencial' | 'servipag_caja_express' | 'cards_batch_mx_recurring_pst' | 'amex_batch_mx_recurring_pst' | 'braintree' | 'pagarme' | 'br_paulista_servicios_automatic_debit' | 'mx_banco_santander' | 'mx_banco_bbva_bancomer' | 'mx_banco_banorte' | 'mx_banco_banorte_h2h' | 'mx_banco_scotiabank' | 'mx_banco_hsbc' | 'mx_banco_citibanamex' | 'mx_banco_multiva' | 'mx_amex' | 'mx_banco_banbajio' | 'mx_banco_banregio' | 'mx_banco_sabadell' | 'mx_belvo' | 'mx_bbva_cie' | 'internal_balance' | 'fiserv' | 'cielo' | 'belvo' | 'mx_banco_scotiabank_h2h_external' | 'iniciador' | 'qi_tech' | 'evo_payments' | 'cl_banco_de_chile' | 'cl_banco_bci' | 'cl_banco_santander' | 'cl_banco_scotiabank' | 'cl_banco_security' | 'cl_banco_consorcio_fidi' | 'transdata' | 'br_banco_do_brasil' | 'br_banco_santander' | 'br_banco_citibank' | 'rede' | 'mercadopago' | 'br_caixa_via_accesstage' | 'br_banco_de_brasilia' | 'worldpay' | 'br_banco_de_brasilia_via_accesstage' | 'br_santander_via_accesstage' | 'br_bradesco_via_accesstage' | 'br_banco_do_brasil_via_accesstage' | 'br_c6_via_accesstage' | 'br_sicoob_via_accesstage' | 'br_itau_via_accesstage' | 'external_payment' | 'br_sicoob' | 'br_caixa' | 'br_btg' | 'toku_mx_belvo' | 'toku_mx_banco_bbva_bancomer' | 'servipag_button' | 'servipag_cashier' | 'servipag_web' | 'servipag_express' | 'sencillito_cashier' | 'sencillito_web' | 'scotiabank_cashier' | 'unired': Integración por la que se cursa un intento de cobro: el adquirente, banco o recaudador concreto que lo ejecuta. La mayoría de los valores corresponde a una institución de un solo país; el resto son mecanismos propios de Toku, como `internal_psp`, `manual_pac` o `external_payment`. Es el conjunto más amplio de gateways de Toku y crece cada vez que se habilita una institución nueva, así que conviene leerlo como una lista abierta y no agotar sus valores en el código. Para el gateway con que se inscribió un medio de pago, ver `PaymentMethodGateway`.
          - 'transbank_oneclick' | 'klap_oneclick' | 'patpass' | 'toku_pac' | 'fintoc_pac' | 'universo_pac' | 'external_pac' | 'ecert_pac' | 'manual_pac' | 'internal_psp' | 'domiciliation' | 'mx_banco_bbva' | 'mx_banco_bancomer' | 'mx_banco_banbajio' | 'mx_banco_banorte' | 'mx_banco_banorte_h2h' | 'mx_banco_banregio' | 'mx_banco_bbva_bancomer' | 'mx_banco_citibanamex' | 'mx_banco_santander' | 'mx_banco_scotiabank' | 'mx_banco_scotiabank_h2h_external' | 'evo_payments' | 'conekta' | 'stripe' | 'kushki' | 'openpay' | 'paypal' | 'getnet' | 'fiserv' | 'transbank' | 'toku_gateways' | 'payment_orchestration' | 'cards_batch_mx' | 'cards_batch_mx_recurring_pst' | 'amex_batch_mx_recurring_pst' | 'atoa_batch_mx_recurring_pst' | 'braintree' | 'cielo' | 'pagarme' | 'belvo' | 'iniciador' | 'qi_tech' | 'mit' | 'mit_amex' | 'rede' | 'br_banco_do_brasil' | 'br_banco_itau' | 'br_banco_santander' | 'br_banco_citibank' | 'br_banco_de_brasilia_via_accesstage' | 'br_santander_via_accesstage' | 'br_bradesco_via_accesstage' | 'br_banco_do_brasil_via_accesstage' | 'br_c6_via_accesstage' | 'br_sicoob_via_accesstage' | 'br_caixa_via_accesstage' | 'br_itau_via_accesstage' | 'br_sicoob' | 'worldpay' | 'br_caixa' | 'br_btg' | 'br_banco_itau_boleto' | 'br_banco_bradesco_boleto' | 'br_sicredi_boleto' | 'br_banco_de_brasilia': Integración a través de la cual se inscribió un medio de pago y por la que se cobrará después. Combina el adquirente o banco con la modalidad de inscripción — por ejemplo `transbank_oneclick` es una tarjeta inscrita en Oneclick de Transbank, y `fintoc_pac` un mandato de descuento automático inscrito vía Fintoc. Es un conjunto distinto de `PaymentIntentGateway`, que identifica por dónde sale un cobro puntual: no todo gateway capaz de cobrar sirve para inscribir un medio de pago.
      - `max_attempts` integer: Authentications this execution may spend before it closes.
      - `three_ds_unavailable_action` 'reject' | 'proceed'
    - object

## Response `200`

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.

- CreateValidatorExecutionResponse: What the organization gets back when it mints a validation link. Three fields, and narrower than the browser's view on purpose: an api-key caller does not drive the steps, so `next_step`, `validator_status` and `remaining_attempts` would be noise it might start branching on — and the frozen `validator_config` must not travel back out at all.
  - `expires_at` string, 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_execution` string, required: The opaque token identifying the execution, for tracing it afterwards.
  - `url` string, 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.

## Other responses

- `201`: Successful Response
- `401`: The request identified no organization.
- `403`: The configuration plans a step the provider bills per call (`identity`'s RENAPO or biometric check) and the organization has not contracted it, enforced per organization during rollout (`VALIDATOR_FEATURE_NOT_CONTRACTED`, naming `missing_features`). No link was minted.
- `404`: El recurso solicitado no existe.
- `409`: That reference already has an active execution this call cannot hand a link for — of a different validator, or one the journey surface created.
- `422`: The portal is not one this organization registered (`PORTAL_NOT_FOUND`), no validator is registered under that name (`UNKNOWN_VALIDATOR`), the configuration sent produces no validation (`INVALID_VALIDATOR_CONFIG` — an `identity` with no `match`, no `renapo` and no `biometrics` approves nobody, and a `signature` with no document to sign has nothing to ask for), or the declared validation context is not what that validator accepts (`INVALID_VALIDATION_CONTEXT`, whose `errors` name the fields that failed and never their values). The `error_code` tells them apart.
- `429`: Se superó el límite de peticiones permitidas.

## Changes

- **2026-11-03** `a6ef070075b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/trytoku/apis/toku-api/changes/public/risk-flow-validator-executions/post.md)

---

[API](https://skmtc.dev/trytoku/apis/toku-api.md) - [All operations](https://skmtc.dev/trytoku/apis/toku-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trytoku/apis/toku-api/revisions/a6ef070075b1?raw)