Agentic Challenge

Agentic Challenge lets Trustline pause a transaction and request more context from the submitting agent instead of declining outright. The agent answers with intent, reasoning trace, or supporting artifacts, and Trustline reassesses the same transaction to a final decision. It is an agent-to-platform information request, not a card-network step-up or a merchant dispute flow.

This page is written for agent developers integrating the async underwriting API, who need to detect a paused transaction and answer its challenge in code. For the underwriting model that produces the original decision, see Underwriting and Async Underwriting.

When Trustline Issues a Challenge

A challenge is not an approval. It is a structured request for evidence, issued only when supplemental information could change the outcome. Many declines happen because the original submission lacked context, not because the payment was bad. A challenge recovers those legitimate transactions: the answer is hashed, classified, audited, and fed into a reassessment, so the second decision carries the same compliance-grade evidence as the first.

Trustline opens a challenge when a decline rests on reason codes that more information could resolve. The eligible codes include EVIDENCE_INSUFFICIENT, REASONING_INCONSISTENCY, POLICY_CONSTRAINT_MISMATCH, TRANSACTION_PATTERN_RISK, BEHAVIOR_ANOMALY, PAYMENT_NOT_REQUIRED, AGENT_IDENTITY_MISMATCH, AMOUNT_EXCEEDS_LIMIT, MERCHANT_RISK, AFFORDABILITY_RISK, and INSUFFICIENT_CREDIT_HISTORY, along with triggers such as a missing agent trace or low validator confidence. The security-related codes PROMPT_INJECTION_RISK and SECURITY_RISK qualify only in limited cases.

Several outcomes are final and never produce a challenge:

Not every transaction enters a challenge. Decisions remain APPROVE or DECLINE; review and record postures surface through reason_brief and product posture, not through a separate decision value. A challenge is the narrow path between a clean approval and a hard decline.

The Challenge Object

When a challenge opens, the transaction status moves to requires_information and the poll response embeds a public-safe challenge summary under the agentic_challenge.v1 schema. Poll GET /api/v1/underwriting/transactions/{trustline_transaction_id}; while the transaction is in requires_information, information_submitted, or reassessing, the embedded object is present.

{
  "schema_version": "agentic_challenge.v1",
  "challenge_id": "tl_chal_0f3b9c2a4d6e8f1a2b3c4d5e",
  "status": "open",
  "reason_brief": "Trustline needs additional evidence from the agent before this transaction can be finalized.",
  "required_information": [
    {
      "type": "intent_explanation",
      "description": "Explain why this payment is within the user's stated intent and approved constraints.",
      "required": true
    }
  ],
  "submit_url": "/api/v1/underwriting/transactions/{trustline_transaction_id}/challenge-response",
  "poll_url": "/api/v1/underwriting/transactions/{trustline_transaction_id}",
  "expires_at": "2026-07-09T00:00:00Z"
}

The required_information array tells the agent exactly what to provide. Trustline selects the types from the reason codes and triggers behind the pause — for example, EVIDENCE_INSUFFICIENT may request all three, while PAYMENT_NOT_REQUIRED requests only an intent explanation.

Persist challenge_id and trustline_transaction_id as soon as the challenge appears, and answer well before expires_at. An expired challenge cannot be reopened.

Answering a Challenge

Submit the answer to the challenge-response endpoint. The path is exact:

POST /api/v1/underwriting/transactions/{trustline_transaction_id}/challenge-response

The X-Trustline-Api-Key-Id header is required and must identify the API key that submitted the original transaction. Only the owning key can answer its challenges; other keys receive 401 or 403. The request body uses the agentic_challenge_response.v1 schema.

curl -X POST "https://portal.t54.ai/api/v1/underwriting/transactions/{trustline_transaction_id}/challenge-response" \
  -H "Authorization: Bearer tl_sandbox_{key_id}.{secret}" \
  -H "X-Trustline-Api-Key-Id: {key_id}" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "agentic_challenge_response.v1",
    "challenge_id": "tl_chal_0f3b9c2a4d6e8f1a2b3c4d5e",
    "response_idempotency_key": "resp-2026-06-09-001",
    "agent_id": "agent_123",
    "response": {
      "intent_explanation": "User approved a monthly data subscription up to $30; this renewal is $19.99.",
      "agent_trace_delta": {
        "tool_calls": ["fetch_invoice", "verify_merchant"],
        "reasoning_summary": "Renewal matches the existing subscription and approved budget."
      },
      "supporting_artifacts": [
        {
          "type": "invoice",
          "uri": "https://example.com/invoices/inv_789.pdf",
          "sha256": "sha256:6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
          "content_type": "application/pdf"
        }
      ]
    }
  }'

An accepted answer returns 202 Accepted with an agentic_challenge_submission.v1 body: the transaction id, challenge id, status: "information_submitted", a poll_url, and retry_after_seconds. Responses are idempotent per (challenge_id, response_idempotency_key) — retrying with the same key and payload replays the original acceptance, while reusing a key with a different payload is rejected. Generate a fresh key for each distinct answer.

Challenge responses become audit evidence, so Trustline validates and redacts them on intake. Payloads are limited to 32 KB and individual text fields to 4,000 characters. Only the documented top-level keys are accepted. Values under sensitive key names — password, token, secret, private_key, prompt, raw, and similar — are stripped before storage. Artifacts are passed by reference, not inline, each with an allowed URI scheme, a sha256:-prefixed hash, and a content type. Answer only what required_information asks for, and never attach raw prompts, credentials, or card data.

Challenge Lifecycle

The challenge object carries its own status alongside the transaction status. While a challenge is in flight, the transaction reports requires_information, information_submitted, or reassessing.

Reassessment

A response is evidence, not an approval. Accepting one queues a reassessment job: the transaction moves to information_submitted, then reassessing, then a terminal status, all under the same trustline_transaction_id. The reassessment re-runs the full validator and consensus pipeline with the supplemental information attached and records a separate, linked audit trace, so both the original decision and the reassessed decision remain verifiable.

A transaction is challenged at most once. After a reassessment, it finalizes without issuing a second challenge, and the reassessment always ends in a final decision. Poll the transaction for the outcome: the status reaches completed with the final decision, or expired if the challenge lapses without an accepted answer. Because only the requires_information event is delivered today (see below), polling is the source of truth for reassessment outcomes and terminal statuses.

In the Portal

The Challenges page in the developer portal at portal.t54.ai shows every challenge session in your organization, including its current status, the original reason_brief, submitted responses, related webhook events and delivery attempts, and the reassessment outcome. Any active organization role can read challenges; submitting a response requires the owner, admin, or developer role.

The same surface is available through the portal API, which lets a team respond on behalf of the organization without holding the original submitting key.

Webhooks

The only challenge-related webhook Trustline delivers today is underwriting.transaction.requires_information, sent when a challenge opens and the transaction pauses. Treat it as a hint that a challenge is waiting, then poll the transaction for the embedded challenge object and, later, the reassessment outcome.

The remaining lifecycle events — underwriting.transaction.completed, underwriting.transaction.failed, underwriting.challenge.expired, and underwriting.challenge.reassessment_completed — are reserved. You can subscribe to them now, but they are not emitted yet, so do not build delivery-dependent logic around them. For endpoint setup, signature verification, and the full event catalog, see Webhooks and Monitoring.