{
  "schema": "aaes/capability-pack/1",
  "provider": "checkout",
  "version": "1.0.0",
  "description": "Checkout.com Unified Payments: read payments and disputes, request payments, and refund captured payments.",
  "notes": "Checkout.com requires a Merchant Specific Sub-Domain (MSSD) base URL — https://{prefix}.api.checkout.com for production and https://{prefix}.api.sandbox.checkout.com for sandbox, where {prefix} is the first eight characters of the deployment's client_id, excluding the cli_ prefix, visible in the Dashboard — and documents that a request to a non-MSSD base URL is refused with a 403 and error_type base_url_invalid. The host therefore varies per merchant, so this pack registers the reserved.invalid authority your-mssd.api.checkout.com.invalid, which cannot resolve: replace it with the deployment's MSSD host in the endpoints, the resource locator and the egress allowlist in step before enabling — the pack fails closed until that substitution is made.\n\nThis pack does not register payment captures or voids, the dispute evidence and acceptance endpoints, payment instruments, or the Flow and Sessions APIs. It registers the secret-key bearer credential; Checkout.com also offers OAuth 2.0 client-credentials access keys (tokens expire after four hours per the docs), which this pack does not register. AAES has not been certified by Checkout.com; the endpoints here are configuration to review and test; the vendor has not endorsed it.",
  "credential": {
    "secret_ref_id": "secret-ref-checkout-com-secret-key",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "A Checkout.com secret API key created in the Dashboard under Developers > Keys, held in the client's own secret manager. The stored material must be the complete Authorization header value — Bearer followed by the secret key, scheme included: Checkout.com's API keys documentation explicitly instructs providing the secret API key in the Authorization header with the Bearer prefix (its example is 'Authorization: Bearer sk_sbox_...'), and that documented format is what this pack registers.\n\nCheckout.com's other scheme — OAuth 2.0 client-credentials access keys, whose JWT access tokens are likewise sent with the Bearer prefix and expire after four hours — is a different credential this pack does not register; do not conflate the two. Provisioning and rotation are external: keys are created, viewed and deleted in the Dashboard (any Developer or Admin role can view or create; only the Account owner role can edit or delete existing keys), rotation means creating a replacement key, repointing this reference, then deleting the old key, and secret keys carry no automatic expiry — deleting the key in the Dashboard is the revocation act, so an un-rotated key remains valid until deleted. A key can be scoped to a specific set of APIs, and Checkout.com's own guidance for separate payments and disputes systems is one secret key for the Payments API and a second key exclusively for the Disputes API: this pack declares that separation — the payments capabilities use this reference, and checkout.disputes.read overrides it with secret-ref-checkout-com-disputes-secret-key, which must likewise hold only 'Bearer <disputes-scoped secret key>'.\n\nSandbox keys (prefix sk_sbox_) and production keys are different credentials: point these references at production keys only when the deployment is meant to move real money. At execution time the resolved material exists in the executor process's memory for the moment of injection only — the deployment owns the executor's memory, log, trace and crash hygiene; the agent never receives it."
  },
  "capabilities": [
    {
      "capability_id": "checkout.payments.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "financial",
      "egress_allowlist": [
        "your-mssd.api.checkout.com.invalid"
      ],
      "endpoint": "https://your-mssd.api.checkout.com.invalid/payments/PAYMENT_ID",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-checkout-com-secret-key",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "checkout-merchant-account",
      "description": "Read one payment's record by ID: status, approval, source and the balances block (total authorised, captured, refunded and the available remainders). PAYMENT_ID is a placeholder to replace before enabling, and the host placeholder must be replaced with the deployment's MSSD host — see the pack notes.",
      "requires_review": true
    },
    {
      "capability_id": "checkout.payments.create",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "financial",
      "egress_allowlist": [
        "your-mssd.api.checkout.com.invalid"
      ],
      "endpoint": "https://your-mssd.api.checkout.com.invalid/payments",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-checkout-com-secret-key",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "pay"
      ],
      "resource_id": "checkout-merchant-account",
      "cost_ceiling_usd": 500,
      "description": "Request a payment or authorisation. The response distinguishes an authorization from a confirmed capture: even with the request's capture flag asking for automatic capture on authorisation, the response can come back Authorised (funds reserved, capture scheduled, not yet captured) — a successful HTTP response with approved=true does not by itself confirm capture — as well as Captured, a redirect-pending or otherwise Pending state (for example a 3DS challenge or an asynchronous payment method), or Declined.\n\nRequesting automatic capture schedules capture; it does not guarantee a captured response, and settlement follows capture on acquirer timelines. The caller must inspect the response's status field — and, for final confirmation, the subsequent capture outcome — rather than assume one call completed the payment. The action is pay at the minimum R3 tier, and pay is one of the designated actions requiring human approval.\n\nThe registered cost ceiling is a budget control on the declared amount: the gateway refuses a declared amount above it and commits the ceiling against the task budget; it does not bound the amount the provider request encodes — currency and minor units are the deployment's review.\n\nOn supported AAES-mediated execution paths, the declared irreversible actions require an authorized person’s approval. Observation-only and bypass calls cannot be stopped by this control.",
      "requires_review": true
    },
    {
      "capability_id": "checkout.payments.refund",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "financial",
      "egress_allowlist": [
        "your-mssd.api.checkout.com.invalid"
      ],
      "endpoint": "https://your-mssd.api.checkout.com.invalid/payments/PAYMENT_ID/refunds",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-checkout-com-secret-key",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "pay"
      ],
      "resource_id": "checkout-merchant-account",
      "cost_ceiling_usd": 500,
      "description": "Refund a captured payment: money moves back to the customer. Refunds are asynchronous — a successful request is Checkout.com accepting the refund for processing, not a completed refund: the refund begins Pending and its subsequent outcome (success or failure) arrives via webhook and on the refund and payment records, so the caller must check the final status rather than treat acceptance as completion. A refund may be partial, and omitting the amount requests a refund of the remaining refundable balance of the payment — an amount the caller did not declare — so the registered cost ceiling does not bound an amount-omitted refund.\n\nThe ceiling is a budget control on the declared amount only: the gateway refuses a declared amount above it and commits the ceiling against the task budget; it does not bound the amount the provider request encodes. The action is pay at the minimum R3 tier, and pay is one of the designated actions requiring human approval. PAYMENT_ID is a placeholder to replace before enabling.\n\nOn supported AAES-mediated execution paths, the declared irreversible actions require an authorized person’s approval. Observation-only and bypass calls cannot be stopped by this control.",
      "requires_review": true
    },
    {
      "capability_id": "checkout.disputes.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "financial",
      "egress_allowlist": [
        "your-mssd.api.checkout.com.invalid"
      ],
      "endpoint": "https://your-mssd.api.checkout.com.invalid/disputes",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-checkout-com-disputes-secret-key",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "checkout-merchant-account",
      "description": "Read the collection of disputes (chargebacks) against the business, returned in reverse chronological order and filterable by status, payment id, entity and date range via query parameters. Collection read.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "checkout-merchant-account",
      "kind": "api",
      "locator": "https://your-mssd.api.checkout.com.invalid",
      "data_class": "financial",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-09-22",
    "sources": [
      "https://api-reference.checkout.com/tag/Payments/ (retrieved 2026-09-21)",
      "https://api-reference.checkout.com/tag/Disputes/ (retrieved 2026-09-21)",
      "https://www.checkout.com/docs/developer-resources/api/api-endpoints (retrieved 2026-09-21)",
      "https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys (retrieved 2026-09-21)",
      "https://www.checkout.com/docs/developer-resources/api/manage-api-keys/oauth-2-0-client-credentials (retrieved 2026-09-21)",
      "https://www.checkout.com/docs/payments/manage-payments/get-payment-details (retrieved 2026-09-21)",
      "https://www.checkout.com/docs/payments/accept-payments/request-a-payment (retrieved 2026-09-21)",
      "https://www.checkout.com/docs/payments/manage-payments/refund-a-payment/refund-a-payment-with-a-reference (retrieved 2026-09-21)"
    ],
    "reviewer_id": "aaes-eng"
  }
}