Technical guide

TrustedPAI is an independent checking service for payments. It answers two questions. Before a payment happens: should this go through, and why. After it happens: do your own systems actually agree that it did.

It is an HTTP API. It never moves money, never settles, never refunds, and never blocks anything by itself. It returns an answer and a record; what you do with them is yours.

Start where your problem is

Most people arrive with one question, not all of them. Pick yours.

Before the payment

An AI agent is about to pay on someone's behalf. You send us the payment authorization it presented. We check the cryptography, apply the policy you configured, and return approve, hold or reject with the reasons written out. Measure end-to-end latency for your deployment and payment provider during the pilot.

After the payment

Your checkout, your payment provider and your back office each keep their own record. Send us what they say and we tell you where they disagree — a payment with no order behind it, a refund with no payment, the same capture claimed twice.

Your first call

Base URL and one header. There is no SDK to install to get started.

# everything lives under this origin
https://api.trustedpai.com

# every authenticated call carries your key in this header
X-API-Key: tpai_live_...

Check you can reach the service and see which rails your account can call:

curl https://api.trustedpai.com/v1/capabilities

{
  "service": "TrustedPAI",
  "api_version": "v1",
  "protocols": [
    { "id": "acp", "status": "primary", "enabled": true,
      "screening_endpoint": "/v1/screen-transaction-acp" },
    // the other rails, each with its own status
  ]
}

Your API key is created once and shown once. It is never retrievable afterwards, not from us and not from any console — if it is lost, a new one is issued and the old one is revoked.

Keys, tokens and roles

One owner key per account. Everything your team touches day to day should use a restricted token instead.

The owner key can do everything, including creating and revoking tokens. Each token carries a role, and the role decides which endpoints answer it.

curl -X POST https://api.trustedpai.com/v1/access-tokens \
  -H "X-API-Key: $OWNER_KEY" -H "Content-Type: application/json" \
  -d '{"label":"risk-ops","role":"reviewer","expires_in_days":90}'

The token comes back once in the response. Copy it then.

Screening a payment

One call, before you execute. You keep the final decision.

Every rail has its own endpoint because every rail proves authorization differently, but they all return the same answer shape. This example uses ACP. Confirm deployment availability in the protocol table below.

curl -X POST https://api.trustedpai.com/v1/screen-transaction-acp \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "spt_id": "spt_1QeX...",
    "merchant_id": "merchant-a",
    "agent_id": "agent-77",
    "amount": 120.00,
    "currency": "EUR"
  }'

{
  "client": "Acme Payments",
  "recommendation": "HOLD",
  "risk_score": 55,
  "reasons": [
    "Amount 120.00 EUR exceeds the per-transaction limit (100.00 EUR)",
    "No human user present for a transaction of 120.00 EUR (threshold 50.00 EUR)"
  ],
  "processing_time_ms": 84.2,
  "transaction_id": 4471,
  "review_case_id": 218
}

reasons is the whole point. Every line is a rule that fired, written so it can be shown to a customer or an auditor without a translation layer.

Calling it from an agent

Screening exposed as MCP tools, subject to transport-specific protocol coverage.

Everything in this guide is a REST endpoint you call from your own code. If the caller is an AI agent, there is a second way in: TrustedPAI speaks the Model Context Protocol, so the agent sees the screening as a tool it can call directly rather than through an integration somebody built for it first.

Seven tools are published. Five screen a payment, one for each rail:

screen_ap2_transaction
screen_acp_transaction
screen_ucp_transaction
screen_x402_transaction
screen_mpp_transaction

And two cover what happens around a decision:

# what is already known about an agent
get_agent_reputation

# tell us a transaction turned out badly
report_transaction_abuse

Three things are worth knowing before you point an agent at it.

It is the same engine. No risk logic is duplicated behind this transport: a decision reached here and the same decision reached over REST come from one implementation, and both are reproducible from the evidence the same way.

Your key travels with each call. Every tool takes api_key as a parameter, exactly as the REST header does. The server holds no credentials of its own, so it never becomes the one place that knows everyone's keys.

The same ceiling applies. Calls are rate limited per key, on the same limits as every other caller, and refused before the key is looked up.

A decision still means what it means everywhere else: HOLD and REJECT mean the payment must not proceed without a human looking at it. An agent that calls the tool and ignores the answer has not been screened.

The six payment rails

Same answer, different proof. Only what your account has enabled will answer.

Availability and qualification are different. The live check below reads /v1/capabilities. If the request fails, availability remains unknown. Confirm account configuration and supported modes before integrating.

Deployment availability has not been checked. Consult /v1/capabilities and confirm your account configuration.

Experimental is our own word for a rail that is built and tested but has not met the conditions we set for promoting it: an independent interoperability run against a counterparty, and a latency measurement on a real deployment. Both are outstanding for all four. Asking for one switches it on for your account; it does not change what has been established about it. Compatibility means the rail is kept working for integrations written against it, and is not where a new one should start.

Each rail needs its verification material registered once, so screening never fetches a key from a URL the counterparty controls:

Your policy

The limits are yours. We apply them; we do not invent them.

Try a change before making it

Replays your recent decisions against a proposed policy and reports how many would have come out differently. You see the cost of a change before your customers do.

Four eyes on a change

A proposal records a snapshot of the policy it was made against. If the live policy moved in the meantime, the approval does not silently apply to something else.

Every change is versioned with who made it and when, so a decision taken last March can be read against the policy that was actually in force then.

Human review

HOLD is not a dead end. It is a queue with a name attached.

curl -X POST https://api.trustedpai.com/v1/reviews/218/resolve \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "decision": "APPROVE",
    "resolution_reason": "Called the customer, purchase confirmed",
    "resolved_by": "risk-ops"
  }'

A resolution without a reason is refused. Months later the question is never what was decided — it is why, and by whom.

Decision evidence

Every decision keeps the complete set of inputs it was made from.

Not a summary of the decision — the inputs themselves:

• the result of the cryptographic verification, and why it passed or failed
• the payment as we normalised it: amount, currency, merchant, whether a human was present
• the policy exactly as it stood at that moment
• the agent's history as it was read, not as it is now
• the instant the decision was taken, and the version of the rules that took it

Fingerprints are off by default on the bulk export. Hashing is cheap for one record and not cheap for a thousand — you should not pay for it while paging through history.

Checking us yourself

You do not have to believe our answer. Reproduce it.

The rules are a pure function of the five inputs above. Given the same inputs, the same answer comes out — so the check runs on your machine, against a file, with no database, no network and no key.

curl "https://api.trustedpai.com/v1/transactions/4471/evidence" \
  -H "X-API-Key: $KEY" > evidence.json

python scripts/evidence/verify_decision_evidence.py evidence.json

Transaction:  4471
Recorded:     HOLD, risk 55
Fingerprint:  b6cf7aca0a6a930f...

MATCH — the recorded decision is the decision these inputs produce.

Telling us what happened

You report a fact about the payment. You never grade our decision.

curl -X PUT https://api.trustedpai.com/v1/transactions/4471/outcome \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"outcome":"fraudulent","notes":"Chargeback received 12 days later"}'

Whether our recommendation was right is derived by comparing the two. That is deliberate: an account cannot mark its own decision quality. Reporting again for the same transaction corrects the record rather than adding a second one, and the correction is written to the audit trail.

Decision quality

Rates always come with the number they were computed from.

{
  "outcome_coverage": 0.31,
  "approved_and_labelled": 160,
  "false_negatives": 23,
  "false_negative_rate": 0.1437,
  "blocked_and_labelled": 30,
  "false_positives": 7,
  "false_positive_rate": 0.2333,
  "synthetic_outcomes": 0
}

• Read outcome_coverage first. A fine accuracy over 2% coverage means very little.
• A rate with no denominator is null, not 0. Zero would read as a perfect score earned on no evidence.
• synthetic_outcomes counts demonstration data. When it equals the labelled total, none of the figures above rest on a real payment — and you can see that rather than being told a shaped number.

Commerce reconciliation

Send what each of your systems says. We tell you where they disagree.

One observation at a time, each carrying which system it came from, which operation it describes, and the amount in minor units.

curl -X POST https://api.trustedpai.com/v1/commerce/sandbox/events \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "journey_id": "order-4471",
    "event_id": "evt_9f3c",
    "operation_id": "cap-1",
    "kind": "payment_captured",
    "currency": "EUR",
    "amount_minor": 12000,
    "occurred_at": "2026-09-10T14:22:05Z"
  }'

{
  "journey_id": "order-4471",
  "result": {
    "status": "anomaly",
    "findings": ["REFUND_WITHOUT_CAPTURE"],
    "missing": ["payment_captured"]
  }
}

The same event arriving twice counts once. Amounts stay exact integers throughout — no floating point ever touches money.

See it running on three orders, no key required.

What a finding means

Three statuses, and a named reason whenever something is wrong.

Webhooks

Signed, retried, and inspectable when they fail.

The secret is returned once. Every delivery is signed with it, so you can tell our call from anyone else's.

The outbox: what was sent, how many attempts, what your endpoint answered. When a delivery fails you can see why instead of guessing.

A disposable endpoint of ours, so you can watch a full signed delivery arrive before pointing us at your own systems.

Usage

Counted when the decision is taken, never used to refuse one.

{
  "current_period": "2026-09",
  "current_period_events": 2500,
  "monthly_event_allowance": 10000,
  "allowance_remaining": 7500,
  "allowance_exceeded": false
}

The count is written in the same database transaction as the decision, so it survives the deletion of the decisions themselves under your retention setting. Going over an agreed volume is a conversation, not an outage: nothing is ever refused because of this figure.

Your data

You set how long we keep it, and you can take it out at any time.

Retention runs automatically at the interval you choose. A hold pins specific records against it — a dispute under investigation should not be deleted by a schedule.

Every configuration change, policy edit, review resolution and purge is recorded with the actor who did it.

Screening receives the protocol-specific authorization material needed for the supported checks. Stored decision evidence is separate from the incoming request. Confirm the fields, credential handling and retention for your integration before sending production data.

Errors and limits

Service status

/v1/health answers if the process is up. /v1/ready answers only if the things it needs to give a real answer are reachable — use that one for your monitor.

A public page lives at api.trustedpai.com/status, and the full OpenAPI document at /docs.