{"openapi":"3.1.0","info":{"title":"Sharp Trust API","version":"2.0.0","description":"Scores agent payments and checks agent actions before they happen. `POST /v2/score` answers with a 0–100 risk score and a decision under your policy; `POST /v1/score` keeps its original three-part answer. Authenticate with an API key: `Authorization: Bearer <key>`. Card numbers are refused in every field: send the card reference, the scheme agent token or the PSP reference."},"security":[{"bearer":[]}],"tags":[{"name":"Scoring","description":"Inbound payments made by agents."},{"name":"Policy","description":"Your own agents' actions, before they commit."},{"name":"Outcomes","description":"What happened afterwards: the other half of the join."},{"name":"Decisions","description":"Reading a decision back, and reporting what was done with it."},{"name":"Reference","description":"Published, unauthenticated reference data."}],"paths":{"/v2/score":{"post":{"tags":["Scoring"],"operationId":"scoreV2","summary":"Score an agent payment: a 0–100 risk and a decision","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreRequest"}}}},"responses":{"200":{"description":"Scored, and decided under your policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreResponseV2"}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: too many scoring requests for this key, or for your organisation across all its keys. `details` names the scope and the limit; wait the seconds in `Retry-After` and send it again.","headers":{"Retry-After":{"description":"Seconds until a call will be accepted again.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`fail_closed`: your organisation fails closed and the evaluation could not complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/score":{"post":{"tags":["Scoring"],"operationId":"scoreV1","summary":"Score an agent payment (v1: mandate verdict, risk score, recommended action)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreRequest"}}}},"responses":{"200":{"description":"Scored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreResponseV1"}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: too many scoring requests for this key, or for your organisation across all its keys. `details` names the scope and the limit; wait the seconds in `Retry-After` and send it again.","headers":{"Retry-After":{"description":"Seconds until a call will be accepted again.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`fail_closed`: your organisation fails closed and the evaluation could not complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/policy-check":{"post":{"tags":["Policy"],"operationId":"policyCheck","summary":"Check one of your agents' actions against its mandate before it commits","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A retry with the same key and body returns the first answer instead of acting twice.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyCheckRequest"}}}},"responses":{"200":{"description":"ALLOW, ESCALATE (held for a person) or BLOCK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyCheckResponse"}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`fail_closed`: this capability, value or envelope fails closed and the evaluation could not complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/outcomes":{"post":{"tags":["Outcomes"],"operationId":"recordOutcome","summary":"Report a payment outcome from your own feed (settlement, refund, dispute…)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A retry with the same key and body returns the first answer instead of acting twice.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeEvent"}}}},"responses":{"200":{"description":"Already stored: a duplicate event or a replayed key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeIngested"}}}},"201":{"description":"Stored and attributed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcomeIngested"}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/outcomes/batch":{"post":{"tags":["Outcomes"],"operationId":"recordOutcomes","summary":"Report up to 500 outcomes at once; each is answered on its own","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["events"],"properties":{"events":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/OutcomeEvent"}}}}}}},"responses":{"200":{"description":"One result per event, in order: `recorded`, `duplicate` (already received, not counted twice) or `rejected` with the reason. A rejected event does not stop the others.","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"integer"},"recorded":{"type":"integer"},"duplicate":{"type":"integer"},"rejected":{"type":"integer"},"unattributed":{"type":"integer","description":"Recorded, but matched to no agent or decision yet."},"results":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuer/cardholder-agents/lookup":{"post":{"tags":["Issuer"],"operationId":"lookupCardholderAgents","summary":"Banks: the \"My agents\" view for one cardholder, for your own app","description":"Every agent on a card, its limits, what it spent this month and its latest payments, written for the cardholder: no advice, score or fraud flags. Your backend calls this for a customer it has signed in. A POST so the card reference stays out of URLs and logs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Send `card_ref` or `token_refs`, one of the two.","properties":{"card_ref":{"type":"string","description":"Product and last four digits. Never a card number."},"token_refs":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}},"recent_payments":{"type":"integer","minimum":0,"maximum":25,"default":5}}}}}},"responses":{"200":{"description":"The agents on the card; an empty list for a card with none.","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuer/cardholder-agents/{enrolmentId}":{"patch":{"tags":["Issuer"],"operationId":"updateCardholderAgentLimits","summary":"Banks: change one agent's limits or categories","description":"Only the fields sent change. The limits in force before stay on record, because a claim is judged on the limits at the time the agent paid.","parameters":[{"name":"enrolmentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"per_payment_limit_minor":{"type":["integer","null"]},"monthly_limit_minor":{"type":["integer","null"]},"categories":{"type":"array","items":{"type":"string"}},"on_behalf_of":{"type":"string","enum":["cardholder","staff"],"default":"staff","description":"`cardholder` when the change came from your own app. Recorded in the audit log."}}}}}},"responses":{"200":{"description":"`changed` is false when the limits were already these.","content":{"application/json":{"schema":{"type":"object","properties":{"enrolment_id":{"type":"string"},"changed":{"type":"boolean"},"limits":{"type":"object"}}}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revoked`: the agent was revoked and has to be enabled again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuer/cardholder-agents/{enrolmentId}/status":{"post":{"tags":["Issuer"],"operationId":"setCardholderAgentStatus","summary":"Banks: pause, resume or revoke one agent on one card","parameters":[{"name":"enrolmentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","paused","revoked"],"description":"A revoke is final."},"reason":{"type":"string"},"on_behalf_of":{"type":"string","enum":["cardholder","staff"],"default":"staff","description":"`cardholder` when the change came from your own app. Recorded in the audit log."}}}}}},"responses":{"200":{"description":"The new status.","content":{"application/json":{"schema":{"type":"object","properties":{"enrolment_id":{"type":"string"},"status":{"type":"string"}}}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`revoked`: the agent was revoked and has to be enabled again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/issuer/cardholder-agents":{"put":{"tags":["Issuer"],"operationId":"putCardholderAgents","summary":"Banks: send the agents your cardholders enabled, with their limits (up to 500)","description":"Send the current state of each enrolment, keyed by `token_ref`. Sharp creates it or works out what changed, keeps the history a claim is judged on, and audits it. A field left out is left as it is. Never send a card number: `card_ref` is the product and last four digits, and a token shaped like a card number refuses the whole request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enrolments"],"properties":{"enrolments":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["token_ref","card_ref","cardholder","scheme","consent_method","consent_at"],"properties":{"token_ref":{"type":"string","description":"The scheme's reference for the agent's token on this card. One enrolment per token."},"agent_id":{"type":"string","description":"From `GET /v1/issuer/agents`. Or send `agent_provider`."},"agent_provider":{"type":"string","description":"The company running the agent, when exactly one of its agents has been seen on your cards."},"card_ref":{"type":"string","description":"Product and last four digits. Never a card number."},"cardholder":{"type":"string","description":"A name or your own customer reference."},"scheme":{"type":"string","enum":["visa","mastercard"]},"consent_method":{"type":"string"},"consent_at":{"type":"string","format":"date-time"},"per_payment_limit_minor":{"type":["integer","null"]},"monthly_limit_minor":{"type":["integer","null"]},"currency":{"type":"string","minLength":3,"maxLength":3},"categories":{"type":"array","items":{"type":"string"},"description":"Empty or absent means any."},"status":{"type":"string","enum":["active","paused","revoked"],"description":"A revoke is final."},"status_reason":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"One result per enrolment, in order: `created`, `updated`, `unchanged` or `rejected` with the reason. A rejected line does not stop the others.","content":{"application/json":{"schema":{"type":"object","properties":{"received":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"rejected":{"type":"integer"},"results":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request failed validation, or carried something shaped like a card number (`card_number_refused`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/decisions":{"get":{"tags":["Decisions"],"operationId":"listDecisions","summary":"The decision log, newest first","parameters":[{"name":"agent_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["inbound_score","policy_check"]}},{"name":"sub_merchant_id","in":"query","required":false,"description":"Payment providers: only this sub-merchant's decisions. 404 for an id that is not one of yours.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"Decisions as stored.","content":{"application/json":{"schema":{"type":"object","properties":{"decisions":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/decisions/{decisionId}/resolution":{"get":{"tags":["Decisions"],"operationId":"decisionResolution","summary":"How a held decision was settled: the poll behind the signed callback","parameters":[{"name":"decisionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The decision, and the review if it was held.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resolution"}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such decision for this organisation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/decisions/{decisionId}/execution":{"post":{"tags":["Decisions"],"operationId":"reportExecution","summary":"Report whether the permitted action was actually carried out","parameters":[{"name":"decisionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionReport"}}}},"responses":{"200":{"description":"Recorded; a repeat of the same report changes nothing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionRecorded"}}}},"401":{"description":"No credential, or one that is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such decision for this organisation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not permitted, or a different execution was already reported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reason-codes":{"get":{"tags":["Reference"],"operationId":"reasonCodes","summary":"Every reason code, with its meaning","description":"Append-only: codes are never renamed or repurposed.\n\n- `agent_unregistered`: No agent record matched the presented identity.\n- `agent_identity_inferred`: Agent identity was inferred from signals rather than verified.\n- `agent_blocked`: The agent record is in blocked lifecycle state.\n- `agent_paused`: The agent record is in paused lifecycle state.\n- `agent_retired`: The agent record is retired and may not transact.\n- `edge_verification_failed`: The CDN edge reported a failed signed-agent verification.\n- `edge_verification_absent`: No edge verification signal was supplied with the request.\n- `signature_invalid`: The request signature did not verify against the registered public key.\n- `capability_not_granted`: The mandate grants no authority for this capability.\n- `capability_disabled`: The capability is present on the mandate but switched off.\n- `capability_outside_envelope`: The governing authority envelope does not permit this capability.\n- `spend_ceiling_breach`: Transaction amount exceeds max_amount_per_txn.\n- `period_spend_ceiling_breach`: Cumulative spend exceeds max_amount_per_period for the period.\n- `velocity_breach`: Transaction count exceeds velocity_max_txn_per_period.\n- `mcc_not_allowed`: Merchant category code is outside mcc_allowlist.\n- `mcc_blocked`: Merchant category code appears in mcc_blocklist.\n- `merchant_not_allowed`: Counterparty merchant is outside merchant_allowlist.\n- `currency_not_allowed`: Currency is outside currency_allowlist.\n- `discount_floor_breach`: Proposed discount exceeds discount_floor_pct.\n- `concession_ceiling_breach`: Cumulative session concession exceeds max_concession_value_per_session.\n- `contract_term_ceiling_breach`: Proposed contract term exceeds contract_term_ceiling.\n- `walk_away_threshold_breach`: Proposed terms fall below walk_away_threshold.\n- `counterparty_reputation_below_min`: Counterparty reputation is below counterparty_min_reputation.\n- `price_floor_breach`: Proposed price is below the configured price_floor.\n- `inventory_out_of_scope`: SKU is outside inventory_scope.\n- `channel_not_allowed`: Channel is outside channel_allowlist.\n- `refund_authority_ceiling_breach`: Refund amount exceeds refund_authority_ceiling.\n- `refund_velocity_breach`: Refund count exceeds max_refunds_per_period.\n- `refund_reason_not_allowed`: Refund reason is outside refund_reason_allowlist.\n- `credit_issuance_limit_breach`: Credit amount exceeds credit_issuance_limit.\n- `cancel_window_exceeded`: Cancellation requested outside cancel_window_hours.\n- `cancel_value_ceiling_breach`: Cancellation value exceeds max_cancel_value.\n- `subscription_amount_ceiling_breach`: Recurring amount exceeds max_recurring_amount.\n- `subscription_term_ceiling_breach`: Subscription term exceeds max_term_months.\n- `auto_renew_not_permitted`: The mandate does not permit auto-renewing subscriptions.\n- `transfer_ceiling_breach`: Transfer amount exceeds max_transfer_amount.\n- `transfer_destination_not_allowed`: Transfer destination is outside destination_allowlist.\n- `order_modification_delta_breach`: Order value change exceeds max_value_delta.\n- `order_field_not_modifiable`: The requested field is outside allowed_fields.\n- `dispute_accept_ceiling_breach`: Accepting this chargeback concedes more than max_accept_amount.\n- `dispute_contest_below_floor`: Contesting a dispute below contest_min_amount costs more than it can recover.\n- `dispute_evidence_missing`: The mandate requires evidence to contest a dispute, and none was attached.\n- `loyalty_points_ceiling_breach`: Points on this order exceed max_points_value_per_order.\n- `loyalty_bonus_ceiling_breach`: Bonus points exceed bonus_points_ceiling.\n- `loyalty_member_unverified`: Points require a verified member, and the buyer was not verified.\n- `payment_authority_denied`: Agent does not hold authority to move money.\n- `envelope_missing`: The action requires an authority envelope and none was supplied.\n- `envelope_not_active`: The governing envelope is not in active status.\n- `envelope_expired`: The governing envelope is past its end date.\n- `envelope_exhausted`: The governing envelope has no remaining budget.\n- `envelope_budget_breach`: The action would exceed the envelope’s remaining budget.\n- `envelope_category_not_allowed`: Category is outside the envelope’s allowed categories.\n- `envelope_counterparty_not_allowed`: Counterparty is outside the envelope’s allowlist.\n- `envelope_requires_human_approval`: The action exceeds the envelope’s human_approval_threshold and needs sign-off.\n- `delegation_exceeds_parent_authority`: A delegated envelope may never exceed the remaining authority of its parent.\n- `delegation_capability_not_held_by_parent`: The delegating agent cannot grant a capability it does not itself hold.\n- `delegation_depth_exceeded`: The delegation chain is longer than the permitted depth.\n- `delegation_not_permitted`: The mandate does not grant the delegate capability.\n- `autonomy_execution_not_permitted`: The agent’s autonomy level does not permit autonomous economic execution.\n- `autonomy_ceiling_breach`: The action exceeds the ceiling implied by the agent’s autonomy level.\n- `autonomy_capability_denied`: The agent’s autonomy level withholds this capability.\n- `autonomy_requires_human_approval`: The agent’s autonomy level requires human approval at this value.\n- `no_active_mandate`: The agent has no mandate in active status.\n- `mandate_expired`: The active mandate is past effective_until.\n- `mandate_not_yet_effective`: The mandate is not yet effective.\n- `mandate_consistency_unverified`: Consumer mandate consistency is inferred, not verified — the consumer instruction is agent-facing and passkey-authenticated (PRD Q10).\n- `consumer_instruction_absent`: No consumer instruction was presented with the transaction.\n- `consumer_instruction_expired`: The presented consumer instruction is past its expiry.\n- `consumer_instruction_replayed`: A single-use consumer instruction was presented a second time.\n- `consumer_instruction_amount_exceeded`: The action exceeds the amount the consumer authenticated.\n- `consumer_instruction_merchant_not_allowed`: The counterparty is outside the merchants the consumer authorised.\n- `consumer_instruction_mcc_not_allowed`: The category is outside the categories the consumer authorised.\n- `risk_signal_coverage_thin`: The risk score was computed from too few available signals to support an unattended approval.\n- `reputation_low`: Agent reputation is below the merchant policy threshold.\n- `counterparty_trust_low`: The agent–counterparty pair has a low observed trust score.\n- `anomalous_velocity`: Request velocity deviates materially from the agent baseline.\n- `new_agent_low_history`: Agent has insufficient outcome history for a confident score.\n- `shadow_mode`: One or more rules matched but are in shadow mode; the verdict was recorded, not applied.\n- `fail_open`: Evaluation did not complete within the configured timeout; failed open.\n- `fail_closed`: Evaluation did not complete and this capability, value or envelope requires failing closed. The action was refused, not breached.\n- `money_composition_mismatch`: The stated total does not equal the sum of its components. Sharp evaluates against the components.\n- `fx_rate_unavailable`: The action and the limit are in different currencies and no exchange rate was supplied.\n- `fx_rate_mismatch`: The supplied exchange rate does not convert between the two currencies in question.\n- `amount_not_comparable`: The amount could not be made comparable to the limit, so the constraint was not evaluated.\n- `payment_transition_anomaly`: The payment event could not legally follow the previous one. Recorded and counted; the attribution is suspect.\n- `internal_error`: An internal error occurred; see the decision log.\n- `ok`: No adverse signal.\n- `cardholder_agent_not_enabled`: The cardholder has not enabled this agent on this card.\n- `cardholder_agent_paused`: The cardholder or the bank paused this agent on this card.\n- `cardholder_agent_revoked`: The cardholder or the bank revoked this agent on this card.\n- `cardholder_limit_exceeded`: The payment is outside the limits the cardholder set for this agent.\n- `cardholder_confirmation_required`: Ask the cardholder to confirm the payment (for example with a passkey) before approving.\n- `high_value_medium_risk`: A high-value payment with a medium risk score: a person should look at it.\n- `identity_tap_signature_valid`: The agent's Visa TAP request signature verified against the key in Visa's agent directory.\n- `identity_agent_signature_valid`: The agent's request signature verified against the key directory its provider publishes (Web Bot Auth).\n- `identity_signature_not_provided`: No agent request signature was supplied, so the identity could not be verified.\n- `identity_tap_evidence_malformed`: The signature evidence was incomplete or could not be read safely.\n- `identity_tap_signature_invalid`: The agent's request signature did not verify.\n- `identity_tap_signature_expired`: The request signature is outside its permitted validity window.\n- `identity_tap_replay_detected`: The request reused a signature nonce that had already been consumed.\n- `identity_tap_agent_unknown`: The signing key is not in the agent directory: the signature cannot be the agent's.\n- `identity_tap_agent_inactive`: The agent directory reports the agent as inactive.\n- `identity_tap_key_inactive`: The agent directory reports the signing key as inactive or revoked.\n- `identity_tap_key_expired`: The signing key has expired.\n- `identity_tap_directory_unavailable`: The agent directory gave no answer, so the signature could be neither verified nor refuted.\n- `identity_tap_unsupported_algorithm`: The signature uses an unsupported or inconsistent signing algorithm.\n- `identity_agent_infra_corroborated`: The request came from inside the claimed agent provider's published network ranges.\n- `identity_agent_infra_mismatch`: The request came from outside the claimed agent provider's published network ranges: possible impersonation, or a leaked key.\n- `identity_agent_ip_private`: The agent connected from a private or reserved address, unexpected for a remote agent.\n- `identity_agent_ip_invalid`: The agent's reported source address could not be read.\n- `identity_agent_user_agent_declared`: The agent's identity rests on a user-agent string, which anyone can send: declared, not verified.\n- `identity_claim_not_verified`: The caller declared a stronger identity basis than Sharp could verify; the verified basis was used.\n- `mandate_consistent`: The payment matches the consumer's mandate, as verified by Sharp.\n- `mandate_assurance_inferred`: The consumer's mandate was inferred from a natural-language instruction, and carries the least weight.\n- `mandate_assurance_user_confirmed`: The consumer explicitly confirmed the mandate as interpreted.\n- `mandate_assurance_authenticated`: The consumer's mandate was stated by the calling platform over an authenticated channel; it was not independently verified.\n- `mandate_assurance_cryptographic`: The consumer's mandate is cryptographically signed or confirmed by the network.\n- `mandate_not_provided`: No consumer mandate was supplied for verification.\n- `mandate_not_found`: The referenced consumer mandate could not be found.\n- `mandate_invalid`: The consumer's mandate could not be verified.\n- `mandate_provider_unavailable`: The mandate provider could not be reached, so the mandate was not verified.\n- `mandate_provider_unauthorized`: The mandate provider is not authorised for this organisation.\n- `mandate_amount_mismatch`: The amount exceeds what the consumer authorised, beyond the allowed tolerance.\n- `mandate_amount_within_tolerance`: The amount is over the authorised cap but within the allowed tolerance (tax, shipping, tips, exchange or a pre-authorisation).\n- `mandate_currency_mismatch`: The payment currency differs from the currency the consumer authorised.\n- `mandate_counterparty_mismatch`: The merchant is not the one the consumer authorised.\n- `mandate_counterparty_approx`: The merchant matches the one the consumer authorised only approximately (a similar name, not an exact one).\n- `identity_signature_invalid`: The agent presented a request signature that failed verification (invalid, expired, replayed, malformed, or an unknown, inactive or expired key): declined whatever the score or the agent's reputation.\n- `product_human_only`: The merchant keeps this product for humans; agents may not buy it (R40).\n- `product_not_in_catalogue`: The order names a product not in the catalogue Sharp reads, so its agent rules could not be checked.\n- `catalogue_plan_unidentified`: The order does not identify which plan of the product is bought, so its price could not be checked.\n- `quantity_limit_exceeded`: More units in one order than the merchant allows an agent to buy.\n- `agent_daily_limit_exceeded`: This agent has reached the units of this product it may buy in 24 hours.\n- `negotiation_not_allowed`: Below the agent price on a product the merchant does not open to negotiation.\n- `discount_limit_exceeded`: A larger discount than the merchant allows on this product.\n- `agent_buying_requires_verification`: Only verified agents may buy from this merchant (above any small amount it allows).\n- `agent_rules_unchecked`: The order could not be checked against the merchant's rules for agents in time, so a person should look at it.\n- `policy_input_missing`: A rule could not be checked because the action did not include what it needs, so a person decides.","security":[],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonCodesResponse"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key (`sk_…`) issued in the console, or a console session token."}},"schemas":{"ScoreRequest":{"type":"object","properties":{"agent_id":{"type":["string","null"],"default":null},"identity_basis":{"type":"string","enum":["signature_verified","scheme_registration","edge_signed_agent","declared_header","ip_asn_heuristic","none"],"default":"none"},"edge_verification":{"type":"string","enum":["passed","failed","absent"],"default":"absent"},"consumer_instruction":{"type":"object","properties":{"presented":{"type":"boolean","default":false},"basis":{"type":"string","enum":["signature_verified","scheme_assertion","presented_unverified","not_presented"],"default":"not_presented"},"instruction_id":{"type":["string","null"],"default":null},"max_amount":{"anyOf":[{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},{"type":"null"}],"default":null},"merchant_allowlist":{"type":"array","items":{"type":"string"},"default":[]},"mcc_allowlist":{"type":"array","items":{"type":"string"},"default":[]},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"default":null},"single_use":{"type":"boolean","default":false},"already_used":{"type":"boolean","default":false}},"additionalProperties":false},"cart":{"type":"object","properties":{"total":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"item_count":{"type":"integer","minimum":0,"default":1},"mcc":{"type":"string"},"merchant_id":{"type":"string"}},"required":["total"],"additionalProperties":false},"counterparty_ref":{"type":"string"},"sub_merchant":{"type":"object","properties":{"external_ref":{"type":"string","minLength":1,"maxLength":120},"name":{"type":"string","minLength":1,"maxLength":200},"mcc":{"type":"string","pattern":"^\\d{4}$"},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"required":["external_ref"],"additionalProperties":false,"description":"Payment providers only: which of your merchants this payment is for, by your own reference. Created the first time it appears; its policy override, if you set one, applies. Not the same as counterparty_ref."},"session":{"type":"object","properties":{"session_id":{"type":"string"},"txn_count_last_hour":{"type":"integer","minimum":0,"default":0},"baseline_txn_per_hour":{"type":"number","minimum":0},"new_shipping_address":{"type":"boolean","default":false}},"additionalProperties":false},"psp_reference":{"type":"string"},"token_ref":{"type":"string","maxLength":120},"card_ref":{"type":"string","maxLength":80},"authorization_evidence":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["ap2_mandate","shared_payment_token","scheme_allowance","merchant_consent","wallet_permission"]},"proof":{"type":"string","minLength":1,"maxLength":20000},"source":{"type":"string","minLength":1,"maxLength":120},"attested_by":{"type":"string","minLength":1,"maxLength":120},"scope":{"type":"object","properties":{"merchant_id":{"type":"string","maxLength":200},"max_amount":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"items":{"type":"array","items":{"type":"string","maxLength":200},"maxItems":50},"expires_at":{"type":"string","format":"date-time"},"single_use":{"type":"boolean"}},"additionalProperties":false,"default":{}}},"required":["type","proof","source"],"additionalProperties":false},"maxItems":10},"terms":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"product_ref":{"type":"string","minLength":1,"maxLength":200},"price_ref":{"type":"string","maxLength":200},"name":{"type":"string","minLength":1,"maxLength":300},"variant":{"type":"string","maxLength":200},"quantity":{"type":"integer","exclusiveMinimum":0,"default":1},"unit_price":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"billing":{"type":"object","properties":{"interval":{"type":"string","enum":["day","week","month","year"]},"interval_count":{"type":"integer","exclusiveMinimum":0,"default":1},"trial_days":{"type":"integer","minimum":0}},"required":["interval"],"additionalProperties":false},"cancellation_terms":{"type":"string","maxLength":2000},"refund_terms":{"type":"string","maxLength":2000},"delivery_terms":{"type":"string","maxLength":2000}},"required":["product_ref","name","unit_price"],"additionalProperties":false},"minItems":1,"maxItems":50},"terms_url":{"type":"string","format":"uri","maxLength":500},"terms_version":{"type":"string","maxLength":100},"shown_at":{"type":"string","format":"date-time"},"accepted_at":{"type":"string","format":"date-time"}},"required":["items"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"maxLength":200},"offer_id":{"type":"string","minLength":1,"maxLength":200},"plan_id":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":10000,"default":1},"unit_price":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false}},"required":["product_id","unit_price"],"additionalProperties":false},"maxItems":100},"buyer_agent":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"provider":{"type":"string","maxLength":120},"key_id":{"type":"string","maxLength":200}},"additionalProperties":false},"agent_signature":{"anyOf":[{"type":"object","properties":{"signature_input":{"type":"string","minLength":1,"maxLength":20000},"signature":{"type":"string","minLength":1,"maxLength":20000},"method":{"type":"string","minLength":1,"maxLength":16},"authority":{"type":"string","minLength":1,"maxLength":255},"path":{"type":"string","minLength":1,"maxLength":8192},"headers":{"type":"object","additionalProperties":{"type":"string","maxLength":20000},"default":{}},"content_digest":{"type":"string","maxLength":1024},"body":{"type":"string","maxLength":262144},"signature_agent":{"type":"string","maxLength":2048}},"required":["signature_input","signature","method","authority","path"],"additionalProperties":false},{"type":"null"}]},"source_ip":{"type":"string","minLength":1,"maxLength":64},"user_agent":{"type":"string","maxLength":1024},"mandate":{"anyOf":[{"type":"object","additionalProperties":{}},{"type":"null"}]}},"additionalProperties":false},"ScoreResponseV1":{"type":"object","properties":{"decision_id":{"type":"string"},"mandate_verdict":{"type":"object","properties":{"verdict":{"type":"string","enum":["satisfied","violated","unverifiable","absent"]},"basis":{"type":"string","enum":["signature_verified","scheme_assertion","presented_unverified","not_presented"]},"breaches":{"type":"array","items":{"type":"object","properties":{"constraint":{"type":"string"},"reason_code":{"$ref":"#/components/schemas/ReasonCode"},"observed":{"type":["number","string"]},"limit":{"type":["number","string"]},"delta":{"type":"number"}},"required":["constraint","reason_code"],"additionalProperties":false}},"reason_codes":{"type":"array","items":{"$ref":"#/components/schemas/ReasonCode"}},"statement":{"type":"string"}},"required":["verdict","basis","breaches","reason_codes","statement"],"additionalProperties":false,"description":"Deterministic: the action against the consumer instruction."},"risk_score":{"anyOf":[{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100},"confidence":{"type":"number","minimum":0,"maximum":1},"coverage_pct":{"type":"number"},"coverage":{"type":"array","items":{"type":"object","properties":{"signal":{"type":"string"},"present":{"type":"boolean"},"detail":{"type":"string"}},"required":["signal","present","detail"],"additionalProperties":false}},"factors":{"type":"array","items":{"type":"object","properties":{"factor":{"type":"string"},"points":{"type":"number"},"detail":{"type":"string"}},"required":["factor","points","detail"],"additionalProperties":false}},"reason_codes":{"type":"array","items":{"$ref":"#/components/schemas/ReasonCode"}},"identity_basis":{"$ref":"#/components/schemas/IdentityBasis"},"identity_confidence":{"type":"number"},"agent_reputation":{"type":["number","null"]},"counterparty_trust":{"type":["number","null"]}},"required":["score","confidence","coverage_pct","coverage","factors","reason_codes","identity_basis","identity_confidence","agent_reputation","counterparty_trust"],"additionalProperties":false},{"type":"null"}],"description":"Probabilistic. Null when the agent is blocked or retired: nothing was scored."},"recommended_action":{"type":"string","enum":["allow","review","block","challenge"],"description":"The merchant acceptance policy applied; `challenge` only from a bank's lanes."},"action_basis":{"type":"string","enum":["mandate_violated","lifecycle","acceptance_policy","risk_threshold","low_confidence","clean","identity_verification_failed","mandate_verification_failed","agent_channel_rules"]},"reason_codes":{"type":"array","items":{"$ref":"#/components/schemas/ReasonCode"}},"issuer_lane":{"type":"object","properties":{"lane":{"$ref":"#/components/schemas/DecisionV2"},"reason":{"type":"string"},"enrolment_id":{"type":["string","null"]},"within_limits":{"type":["boolean","null"]},"breaches":{"type":"array","items":{}}},"required":["lane","reason","enrolment_id","within_limits","breaches"],"additionalProperties":false,"description":"Banks only."},"authorization":{"type":"object","properties":{"status":{"type":"string"},"items":{"type":"array","items":{}}},"required":["status","items"],"additionalProperties":false},"terms":{"anyOf":[{},{"type":"null"}]},"fail_open":{"type":"boolean"},"channel_rules":{"type":"object","properties":{"ruleset_version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"outcome":{"type":"string","enum":["allow","review","block","not_checked"]},"verified_agent":{"type":"boolean"},"lines":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":["string","null"]},"reference":{"type":"string"},"offer_id":{"type":["string","null"]},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ReasonCode"},"severity":{"type":"string","enum":["block","review"]},"message":{"type":"string","description":"Safe to pass to the agent: names the rule, never a floor or a limit's value."}},"required":["code","severity","message"],"additionalProperties":false}}},"required":["product_id","reference","offer_id","findings"],"additionalProperties":false}},"order_findings":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ReasonCode"},"severity":{"type":"string","enum":["block","review"]},"message":{"type":"string","description":"Safe to pass to the agent: names the rule, never a floor or a limit's value."}},"required":["code","severity","message"],"additionalProperties":false}},"statement":{"type":"string"}},"required":["ruleset_version","outcome"],"additionalProperties":false,"description":"R40: the order lines against the merchant's activated rules for agents. Present only when the call carried order lines (`items` or `terms.items`). `not_checked` when the merchant has activated no rules; `agent_rules_unchecked` when the check did not finish in time and the order is held."},"latency_ms":{"type":"integer"}},"required":["decision_id","mandate_verdict","risk_score","recommended_action","action_basis","reason_codes","fail_open","latency_ms"],"additionalProperties":false,"description":"v1: three results, combined by the caller."},"ScoreResponseV2":{"type":"object","properties":{"decision_id":{"type":"string"},"score":{"anyOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}],"description":"The 0–100 risk, the same for every caller. Null only when the agent is blocked or retired."},"decision":{"$ref":"#/components/schemas/DecisionV2","description":"The caller's policy applied: approve, challenge (ask the customer), review (refer), decline."},"reason_codes":{"type":"array","items":{"$ref":"#/components/schemas/ReasonCode"}},"identity":{"type":"object","properties":{"basis":{"$ref":"#/components/schemas/IdentityBasis"},"confidence":{"type":"number","minimum":0,"maximum":1},"verified":{"type":"boolean","description":"True only when Sharp's own verifier confirmed the identity on this request."}},"required":["basis","confidence","verified"],"additionalProperties":false},"mandate":{"type":"object","properties":{"verdict":{"type":"string","enum":["satisfied","violated","unverifiable","absent"]},"basis":{"type":"string","enum":["signature_verified","scheme_assertion","presented_unverified","not_presented"]},"breaches":{"type":"array","items":{"type":"object","properties":{"constraint":{"type":"string"},"reason_code":{"$ref":"#/components/schemas/ReasonCode"},"observed":{"type":["number","string"]},"limit":{"type":["number","string"]},"delta":{"type":"number"}},"required":["constraint","reason_code"],"additionalProperties":false}},"reason_codes":{"type":"array","items":{"$ref":"#/components/schemas/ReasonCode"}},"statement":{"type":"string"},"verification":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["verified","failed","not_provided","unavailable"]},"assurance":{"type":["string","null"]}},"required":["status","assurance"],"additionalProperties":false},{"type":"null"}],"description":"What the verifier found for a mandate sent with the request; null when it was not asked."}},"required":["verdict","basis","breaches","reason_codes","statement","verification"],"additionalProperties":false},"coverage_pct":{"type":["number","null"]},"fail_open":{"type":"boolean","const":true,"description":"Present only when Sharp could not finish scoring in time and the organisation fails open. The decision then rests on the consumer instruction alone (a violated one is still declined), and the score is not a measurement."},"sub_merchant_id":{"type":"string","description":"Payment providers only, and only when the request named a `sub_merchant`: the sub-merchant the decision was recorded for."},"channel_rules":{"type":"object","properties":{"ruleset_version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"outcome":{"type":"string","enum":["allow","review","block","not_checked"]},"verified_agent":{"type":"boolean"},"lines":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":["string","null"]},"reference":{"type":"string"},"offer_id":{"type":["string","null"]},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ReasonCode"},"severity":{"type":"string","enum":["block","review"]},"message":{"type":"string","description":"Safe to pass to the agent: names the rule, never a floor or a limit's value."}},"required":["code","severity","message"],"additionalProperties":false}}},"required":["product_id","reference","offer_id","findings"],"additionalProperties":false}},"order_findings":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ReasonCode"},"severity":{"type":"string","enum":["block","review"]},"message":{"type":"string","description":"Safe to pass to the agent: names the rule, never a floor or a limit's value."}},"required":["code","severity","message"],"additionalProperties":false}},"statement":{"type":"string"}},"required":["ruleset_version","outcome"],"additionalProperties":false,"description":"R40: the order lines against the merchant's activated rules for agents. Present only when the call carried order lines (`items` or `terms.items`). `not_checked` when the merchant has activated no rules; `agent_rules_unchecked` when the check did not finish in time and the order is held."}},"required":["decision_id","score","decision","reason_codes","identity","mandate","coverage_pct"],"additionalProperties":false,"description":"v2: the score and the decision as separate fields."},"PolicyCheckRequest":{"type":"object","properties":{"agent_id":{"type":"string"},"capability":{"type":"string","enum":["purchase","negotiate","sell","refund","issue_credit","cancel","subscribe","transfer","modify_order","delegate","dispute","loyalty"]},"session_id":{"type":"string"},"envelope_id":{"type":"string"},"proposed_terms":{"type":"object","properties":{"amount":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"amount_composition":{"type":"object","properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"subtotal_minor":{"type":"integer","minimum":0},"tax_minor":{"type":"integer","minimum":0,"default":0},"shipping_minor":{"type":"integer","minimum":0,"default":0},"tip_minor":{"type":"integer","minimum":0,"default":0},"fees_minor":{"type":"integer","minimum":0,"default":0},"discount_minor":{"type":"integer","minimum":0,"default":0},"total_minor":{"type":"integer","minimum":0}},"required":["currency","subtotal_minor","total_minor"],"additionalProperties":false},"fx":{"type":"object","properties":{"presentment_currency":{"type":"string","minLength":3,"maxLength":3},"settlement_currency":{"type":"string","minLength":3,"maxLength":3},"rate":{"type":"number","exclusiveMinimum":0},"markup_minor":{"type":"integer","minimum":0,"default":0},"rate_source":{"type":"string"},"rate_at":{"type":"string","format":"date-time"}},"required":["presentment_currency","settlement_currency","rate"],"additionalProperties":false},"authorized_total":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"currency":{"type":"string","minLength":3,"maxLength":3},"mcc":{"type":"string"},"merchant_id":{"type":"string"},"discount_pct":{"type":"number","minimum":0,"maximum":100},"concession_value":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"contract_term_months":{"type":"integer","exclusiveMinimum":0},"deal_value":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"sku":{"type":"string"},"unit_price":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"channel":{"type":"string"},"refund_amount":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"refund_reason":{"type":"string","enum":["agent_error","customer_changed_mind","item_not_as_described","item_not_received","duplicate_transaction","fraud","price_dispute","merchant_initiated","unknown"]},"credit_amount":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"hours_since_order":{"type":"number","minimum":0},"cancel_value":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"recurring_amount":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"term_months":{"type":"integer","exclusiveMinimum":0},"auto_renew":{"type":"boolean"},"transfer_amount":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"destination":{"type":"string"},"value_delta":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"modified_fields":{"type":"array","items":{"type":"string"}},"delegated_amount":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"delegate_to":{"type":"string"},"delegated_capabilities":{"type":"array","items":{"type":"string","enum":["purchase","negotiate","sell","refund","issue_credit","cancel","subscribe","transfer","modify_order","delegate","dispute","loyalty"]}},"dispute_action":{"type":"string","enum":["accept","contest"]},"dispute_amount":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"evidence_attached":{"type":"boolean"},"points_action":{"type":"string","enum":["earn","redeem","bonus"]},"points_value":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0},"currency":{"type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"member_verified":{"type":"boolean"},"category":{"type":"string"},"counterparty":{"type":"object","properties":{"id":{"type":"string"},"reputation":{"type":"number","minimum":0,"maximum":100}},"additionalProperties":false}},"additionalProperties":false}},"required":["agent_id","capability","proposed_terms"],"additionalProperties":false},"PolicyCheckResponse":{"type":"object","properties":{"decision_id":{"type":"string"},"capability":{"type":"string"},"verdict":{"type":"string","enum":["ALLOW","ESCALATE","BLOCK"]},"reason_codes":{"type":"array","items":{"$ref":"#/components/schemas/ReasonCode"}},"breaches":{"type":"array","items":{}},"shadow_findings":{"type":"array","items":{}},"counterfactual":{},"envelope_usage":{"type":"array","items":{}},"requires_human_approval":{"type":"boolean"},"not_evaluated":{"type":"array","items":{}},"mandate_id":{"type":["string","null"]},"mandate_version":{"type":["number","null"]},"margin_given_away":{"anyOf":[{},{"type":"null"}]},"failure_policy":{"type":"object","properties":{"mode":{"type":"string"},"basis":{"type":"string"},"detail":{"type":"string"},"applied":{"type":"boolean"}},"required":["mode","basis","detail","applied"],"additionalProperties":false},"latency_ms":{"type":"integer"}},"required":["decision_id","capability","verdict","reason_codes","breaches","shadow_findings","envelope_usage","requires_human_approval","not_evaluated","mandate_id","mandate_version","failure_policy","latency_ms"],"additionalProperties":true},"OutcomeEvent":{"type":"object","properties":{"kind":{"type":"string","enum":["authorization","settlement","refund","dispute_opened","dispute_closed","fulfilment"]},"source":{"type":"string","enum":["merchant_feed","manual"],"default":"merchant_feed"},"source_event_id":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"amount_minor":{"type":"integer"},"currency":{"type":"string","minLength":3,"maxLength":3},"agent_id":{"type":"string"},"decision_id":{"type":"string"},"psp_reference":{"type":"string"},"approved":{"type":"boolean"},"decline_reason":{"type":"string"},"refund_reason":{"type":"string","enum":["agent_error","customer_changed_mind","item_not_as_described","item_not_received","duplicate_transaction","fraud","price_dispute","merchant_initiated","unknown"]},"refund_reason_raw":{"type":"string"},"dispute_won":{"type":"boolean"},"dispute":{"type":"object","properties":{"dispute_id":{"type":"string","maxLength":200},"network":{"type":"string","maxLength":40},"reason_code":{"type":"string","maxLength":20},"reason":{"type":"string","maxLength":120},"stage":{"type":"string","enum":["inquiry","chargeback","pre_arbitration","arbitration"]},"status":{"type":"string","enum":["needs_response","under_review","won","lost","accepted","expired"]},"due_by":{"type":"string","format":"date-time"}},"additionalProperties":false}},"required":["kind","source_event_id","occurred_at"],"additionalProperties":false},"OutcomeIngested":{"type":"object","properties":{"outcomeId":{"type":"string"},"duplicate":{"type":"boolean"},"replayed":{"type":"boolean"},"attribution":{"type":"object","properties":{"agentId":{"type":["string","null"]},"decisionId":{"type":["string","null"]},"method":{"type":"string"},"confidence":{"type":"number"},"unattributedReason":{"type":["string","null"]}},"required":["agentId","decisionId","method","confidence","unattributedReason"],"additionalProperties":false},"refundReason":{"type":["string","null"]}},"required":["outcomeId","duplicate","replayed","attribution","refundReason"],"additionalProperties":true,"description":"201 when stored, 200 for a duplicate or a replayed idempotency key."},"Resolution":{"type":"object","properties":{"decision_id":{"type":"string"},"status":{"type":"string","enum":["not_held","awaiting_review","resolved","expired"]},"verdict":{"type":"string","description":"The stored verdict, upper case."},"resolution":{"type":["string","null"]},"next_step":{"anyOf":[{"type":"string","enum":["proceed","stop"]},{"type":"null"}]},"execution":{"anyOf":[{},{"type":"null"}]}},"required":["decision_id","status","verdict","resolution","next_step"],"additionalProperties":true},"ExecutionReport":{"type":"object","properties":{"status":{"type":"string","enum":["executed","not_executed"]},"action_hash":{"type":"string","maxLength":128},"reference":{"type":"string","maxLength":200},"detail":{"type":"string","maxLength":500}},"required":["status"],"additionalProperties":false},"ExecutionRecorded":{"type":"object","properties":{"decision_id":{"type":"string"},"status":{"type":"string","enum":["executed","not_executed"]},"reference":{"type":["string","null"]},"reported_at":{"type":"string"},"duplicate":{"type":"boolean"}},"required":["decision_id","status","reference","reported_at","duplicate"],"additionalProperties":false},"ReasonCodesResponse":{"type":"object","properties":{"reason_codes":{"type":"array","items":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ReasonCode"},"description":{"type":"string"}},"required":["code","description"],"additionalProperties":false}},"stability":{"type":"string"}},"required":["reason_codes","stability"],"additionalProperties":false},"ReasonCode":{"type":"string","enum":["agent_unregistered","agent_identity_inferred","agent_blocked","agent_paused","agent_retired","edge_verification_failed","edge_verification_absent","signature_invalid","capability_not_granted","capability_disabled","capability_outside_envelope","spend_ceiling_breach","period_spend_ceiling_breach","velocity_breach","mcc_not_allowed","mcc_blocked","merchant_not_allowed","currency_not_allowed","discount_floor_breach","concession_ceiling_breach","contract_term_ceiling_breach","walk_away_threshold_breach","counterparty_reputation_below_min","price_floor_breach","inventory_out_of_scope","channel_not_allowed","refund_authority_ceiling_breach","refund_velocity_breach","refund_reason_not_allowed","credit_issuance_limit_breach","cancel_window_exceeded","cancel_value_ceiling_breach","subscription_amount_ceiling_breach","subscription_term_ceiling_breach","auto_renew_not_permitted","transfer_ceiling_breach","transfer_destination_not_allowed","order_modification_delta_breach","order_field_not_modifiable","dispute_accept_ceiling_breach","dispute_contest_below_floor","dispute_evidence_missing","loyalty_points_ceiling_breach","loyalty_bonus_ceiling_breach","loyalty_member_unverified","payment_authority_denied","envelope_missing","envelope_not_active","envelope_expired","envelope_exhausted","envelope_budget_breach","envelope_category_not_allowed","envelope_counterparty_not_allowed","envelope_requires_human_approval","delegation_exceeds_parent_authority","delegation_capability_not_held_by_parent","delegation_depth_exceeded","delegation_not_permitted","autonomy_execution_not_permitted","autonomy_ceiling_breach","autonomy_capability_denied","autonomy_requires_human_approval","no_active_mandate","mandate_expired","mandate_not_yet_effective","mandate_consistency_unverified","consumer_instruction_absent","consumer_instruction_expired","consumer_instruction_replayed","consumer_instruction_amount_exceeded","consumer_instruction_merchant_not_allowed","consumer_instruction_mcc_not_allowed","risk_signal_coverage_thin","reputation_low","counterparty_trust_low","anomalous_velocity","new_agent_low_history","shadow_mode","fail_open","fail_closed","money_composition_mismatch","fx_rate_unavailable","fx_rate_mismatch","amount_not_comparable","payment_transition_anomaly","internal_error","ok","cardholder_agent_not_enabled","cardholder_agent_paused","cardholder_agent_revoked","cardholder_limit_exceeded","cardholder_confirmation_required","high_value_medium_risk","identity_tap_signature_valid","identity_agent_signature_valid","identity_signature_not_provided","identity_tap_evidence_malformed","identity_tap_signature_invalid","identity_tap_signature_expired","identity_tap_replay_detected","identity_tap_agent_unknown","identity_tap_agent_inactive","identity_tap_key_inactive","identity_tap_key_expired","identity_tap_directory_unavailable","identity_tap_unsupported_algorithm","identity_agent_infra_corroborated","identity_agent_infra_mismatch","identity_agent_ip_private","identity_agent_ip_invalid","identity_agent_user_agent_declared","identity_claim_not_verified","mandate_consistent","mandate_assurance_inferred","mandate_assurance_user_confirmed","mandate_assurance_authenticated","mandate_assurance_cryptographic","mandate_not_provided","mandate_not_found","mandate_invalid","mandate_provider_unavailable","mandate_provider_unauthorized","mandate_amount_mismatch","mandate_amount_within_tolerance","mandate_currency_mismatch","mandate_counterparty_mismatch","mandate_counterparty_approx","identity_signature_invalid","product_human_only","product_not_in_catalogue","catalogue_plan_unidentified","quantity_limit_exceeded","agent_daily_limit_exceeded","negotiation_not_allowed","discount_limit_exceeded","agent_buying_requires_verification","agent_rules_unchecked","policy_input_missing"]},"IdentityBasis":{"type":"string","enum":["signature_verified","scheme_registration","edge_signed_agent","declared_header","ip_asn_heuristic","none"]},"EdgeVerification":{"type":"string","enum":["passed","failed","absent"]},"DecisionV2":{"type":"string","enum":["approve","challenge","review","decline"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"A stable machine-readable code, e.g. invalid_score_request, card_number_refused, fail_closed."},"message":{"type":"string"},"details":{"anyOf":[{},{"type":"null"}]}},"required":["error","message"],"additionalProperties":false,"description":"Every refusal has this shape."}}}}