Decionis API
Decionis for DevelopersGitHub
HomeAPI ReferenceSDKsContext Plugin
U C P

Evaluate and bind authority for one UCP checkout completion

POST
/v1/ucp/checkout/authorize

Accepts a complete UCP checkout response envelope negotiated at either 2026-04-08 or 2026-08-25. The seven UCP top-level checkout fields are required and extension members remain open. August responses must also carry ucp.payment_handlers; line items retain their official required fields and quantity floor; checkout totals contain exactly one subtotal and one total. Historical April callers retain the original adapter's optional payment-handler compatibility. Missing, ambiguous, or unsupported material fails before policy evaluation.

Decionis authorizes; the connected merchant system remains responsible for execution. An ALLOW decision is not itself an execution grant. An authoritative response may carry an exact-action grant that must be claimed immediately before the merchant commits the checkout, then finalized as COMMITTED, FAILED, or INDETERMINATE.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

An organization API key. Its scopes decide what it may call; decision:shadow is the narrowest: SHADOW evaluations through POST /v1/authority/grants or its alias POST /v1/authority/enforce-and-bind only (DECISION_SHADOW_MODE_DENIED in any other mode; DECISION_SHADOW_FIELD_DENIED for a body carrying context.decionis_policy, evidence or escalation), with no integration dispatch. A key whose only scope is decision:shadow (an AgentSafe hosted gateway's) reaches exactly those two, POST /v1/auth/credential-context, POST /v1/hosted-gateway/keys/confirm and POST /v1/hosted-gateway/keys/revoke-self; every other route answers 403 HOSTED_GATEWAY_KEY_PATH_DENIED. decision:enforce is an enforced hosted gateway's key: evaluations in SHADOW or ENFORCEMENT through POST /v1/authority/grants or its alias (400 DECISION_ENFORCE_FIELD_DENIED for a body carrying context.decionis_policy; it never holds policy:write), and the grants and managed escalations they bind. A key whose scopes are decision:enforce (with or without decision:shadow) reaches exactly POST /v1/authority/enforce-and-bind, POST /v1/authority/grants, GET /v1/authority/grants/{grant_id}, POST /v1/authority/grants/{grant_id}/claims, POST /v1/authority/grants/{grant_id}/receipts, POST /v1/authority/grants/{grant_id}/reconciliations, POST /v1/execution/verify-token, POST /v1/execution/claim-token, POST /v1/execution/consume-token, POST /v1/execution/finalize-token, GET /v1/authority/escalations/{escalation_id}, DELETE /v1/authority/escalations/{escalation_id}, POST /v1/auth/credential-context, POST /v1/hosted-gateway/keys/confirm and POST /v1/hosted-gateway/keys/revoke-self, each id a UUID; every other route answers 403 HOSTED_GATEWAY_KEY_PATH_DENIED.

In: header

Header Parameters

Idempotency-Key?string

Request Body

application/json

org_id?string

Optional when the authenticated API key is organization-bound.

Formatuuid
checkout*

Validated core checkout response plus any negotiated extensions. The seven top-level required members are common to UCP 2026-04-08 and 2026-08-25; the version conditional below additionally requires the August response payment-handler registry.

agent?
approval_url?string
Match^https://(?![^/?#]*@)
Formaturi
Lengthlength <= 2000
mode?string
Default"ENFORCEMENT"

Value in

  • "SHADOW"
  • "PARALLEL"
  • "ENFORCEMENT"
grant_ttl_seconds?integer
Range1 <= value <= 300
idempotency_key?string
Length1 <= length <= 180
degradation_mode?"fail_closed"

Compatibility field. Execution authority always fails closed; caller-selected fail-open is rejected.

Default"fail_closed"

Value in

  • "fail_closed"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/ucp/checkout/authorize" \  -H "Content-Type: application/json" \  -d '{    "checkout": {      "ucp": {        "version": "2026-04-08"      },      "id": "string",      "line_items": [        {          "id": "string",          "quantity": 1,          "item": {            "id": "string",            "title": "string",            "price": 0          },          "totals": [            {              "amount": -9007199254740991,              "type": "subtotal"            }          ]        }      ],      "status": "incomplete",      "currency": "string",      "totals": [        {          "type": "total"        }      ],      "links": [        {          "type": "string",          "url": "http://example.com"        }      ]    }  }'
{  "service": "decionis",  "ucp": {    "version": "2026-04-08",    "status": "success"  },  "checkout_id": "string",  "mode": "SHADOW",  "enforcing": true,  "authority_classification": "AUTHORITATIVE",  "evaluation_mode": "SHADOW",  "execution_eligible": true,  "dossier_id": "string",  "status": "string",  "continue_url": "http://example.com",  "error": {},  "actions": {    "com.decionis.authority.review": [      {        "id": "string",        "config": {          "continue_url": "http://example.com",          "reason_codes": [            "string"          ],          "expires_at": "2019-08-24T14:15:22Z"        }      }    ]  },  "messages": [    {      "type": "info",      "content_type": "plain",      "content": "string"    }  ],  "fallback": {    "degraded": true,    "mode": "fail_closed",    "reason": "string",    "circuit_open": true  },  "com.decionis.commerce.execution_authority": {    "decision": "ALLOW",    "authoritative": true,    "evaluation_id": "string",    "dossier_id": "string",    "policy_version": "string",    "reason_codes": [      "string"    ],    "required_presence": true,    "verification_url": "http://example.com",    "evaluated_at": "2019-08-24T14:15:22Z",    "dossier_sha256": "string"  },  "verification": {    "verified": true,    "status": "VERIFIED",    "checked": [      "string"    ],    "not_checked": [      "string"    ]  },  "escalation": {    "override_id": "string",    "status": "PENDING"  },  "execution_grant": {    "token": "string",    "jti": "string",    "key_id": "string",    "expires_at": "2019-08-24T14:15:22Z",    "intent_hash": "string",    "execution_binding_digest": "string",    "execution_correlation_id": "string",    "claim_path": "/v1/execution/claim-token",    "finalize_path": "/v1/execution/finalize-token",    "intent": {      "protocol_version": "agent-safe.intent/1",      "tenant_id": "34f5c98e-f430-457b-a812-92637d0c6fd0",      "intent_id": "05704cef-194d-4987-b2cb-c2c20c9cd88a",      "captured_at": "2019-08-24T14:15:22Z",      "expires_at": "2019-08-24T14:15:22Z",      "actor": {        "id": "string",        "type": "string",        "runtime": "string",        "trust_level": "string"      },      "action": {        "type": "string",        "resource": "string",        "parameters": {}      },      "context": {        "enforcement_boundary": {          "boundary_id": "string",          "agentsafe_version": "string",          "protocol_version": "agent-safe.intent/1",          "deployment_type": "string",          "environment": "string",          "conformance_version": "string",          "placement": {            "cluster_id": "string",            "namespace": "string",            "region": "string",            "workload_id": "string"          }        },        "workload": {          "runtime": "string",          "artifact_type": "string",          "image": "string",          "digest": "string",          "publisher": "string",          "provenance": {            "source": "string",            "trust_level": "unverified"          }        },        "agent_safe": {          "precondition": {            "version": "string",            "state": "string",            "source": "string",            "read_at": "2019-08-24T14:15:22Z"          }        }      },      "downstream_target": {        "system": "string",        "operation": "string",        "environment": "production",        "endpoint": "string"      },      "policy_projection": {        "decision_type": "string",        "transaction_type": "string",        "workflow_key": "string",        "channel": "string"      },      "expected_effect_digest": "string"    }  },  "requires_human_approval": true,  "reason_codes": [    "string"  ]}

Admit a presence provider for this organisation PUT

From then on an attestation signed under a key the provider's JWKS publishes verifies for this organisation, when the attestation's `iss` is the provider's. The organisation's own registered keys (POST /v1/execution/provider-keys, purpose presence_attestation) are consulted first and remain the way to pin a key by hand. Admitting again clears a revocation. Requires policy:write or org:* scope.

List active and revoked UCP merchant verification keys GET

Next Page