feat: Complete Visa vault verification and transaction reporting

Stainless-Generated-From: 95755eb52964f48e3ecbcb51119caf08834cc53f

Author: kernel-internal[bot]

api.md

@@ -571,6 +571,7 @@ from kernel.types.vaults import (
     CardVaultItemSpec,
     CardVaultItemState,
     CollectVaultItemOperationRequest,
+    ConfirmTransactionVaultItemOperationRequest,
     CredentialAccountVaultItem,
     CredentialAccountVaultItemRequest,
     CredentialCollectionAction,

src/kernel/resources/vaults/items.py

@@ -440,6 +440,66 @@ def perform_operation(
         """
         ...
 
+    @overload
+    def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        amount: int,
+        currency: str,
+        occurred_at: Union[str, datetime],
+        status: Literal["APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED"],
+        transaction_type: Literal[
+            "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"
+        ],
+        type: Literal["confirm_transaction"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> VaultItemOperationResponse:
+        """
+        Retrieve the item first and invoke only an operation listed in
+        `available_operations`, following its natural-language description. Availability
+        is rechecked at execution time; unavailable operations return 409. Authorization
+        and preparation may call an external provider and return updated state. Link
+        cards advertise authorize without checkout context. Eligible unused AgentCard
+        cards advertise prepare_checkout, which requires checkout context and obtains
+        device approval before native Square Pay. Keep the returned approval page open,
+        poll until ready_to_submit, then submit before preparation.expires_at. Unused
+        preparations expire automatically and cannot be reused. If spend-request
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
+
+        Fill returns a value-free execution result. Validation failures before writing
+        return 400 (invalid request or targets), 403 (access or destination denied), 404
+        (resource not found), or 409 (item or browser not ready). Once writing starts,
+        known partial failures and indeterminate field outcomes return 200 with status
+        `failed` or `unknown`. Fill never submits the page, so it is safe to retry after
+        a failure, an `unknown` outcome, or a transport error.
+
+        Args:
+          amount: Actual transaction amount in minor units, no greater than the approved limit.
+
+          currency: Must match the approved purchase currency.
+
+          occurred_at: Time the merchant outcome was observed.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        ...
+
     @overload
     def perform_operation(
         self,
@@ -928,6 +988,7 @@ def perform_operation(
 
     @required_args(
         ["id_or_name", "type"],
+        ["id_or_name", "amount", "currency", "occurred_at", "status", "transaction_type", "type"],
         ["id_or_name", "checkout", "type"],
         ["id_or_name", "browser_id", "fields", "type"],
         ["id_or_name", "browser_id", "page_url", "type"],
@@ -940,6 +1001,7 @@ def perform_operation(
         *,
         id_or_name: str,
         type: Literal["authorize"]
+        | Literal["confirm_transaction"]
         | Literal["collect"]
         | Literal["prepare_checkout"]
         | Literal["fill"]
@@ -949,6 +1011,14 @@ def perform_operation(
         | Literal["1pw_recover"]
         | Literal["1pw_update_access_token"]
         | Literal["webmcp_invoke"],
+        amount: int | Omit = omit,
+        currency: str | Omit = omit,
+        occurred_at: Union[str, datetime] | Omit = omit,
+        status: Literal["APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED"] | Omit = omit,
+        transaction_type: Literal[
+            "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"
+        ]
+        | Omit = omit,
         checkout: VaultCheckoutContextParam | Omit = omit,
         browser_id: str | Omit = omit,
         fields: Iterable[VaultFillFieldParam] | Omit = omit,
@@ -983,6 +1053,11 @@ def perform_operation(
                 body=maybe_transform(
                     {
                         "type": type,
+                        "amount": amount,
+                        "currency": currency,
+                        "occurred_at": occurred_at,
+                        "status": status,
+                        "transaction_type": transaction_type,
                         "checkout": checkout,
                         "browser_id": browser_id,
                         "fields": fields,
@@ -1614,6 +1689,66 @@ async def perform_operation(
         """
         ...
 
+    @overload
+    async def perform_operation(
+        self,
+        key: str,
+        *,
+        id_or_name: str,
+        amount: int,
+        currency: str,
+        occurred_at: Union[str, datetime],
+        status: Literal["APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED"],
+        transaction_type: Literal[
+            "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"
+        ],
+        type: Literal["confirm_transaction"],
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> VaultItemOperationResponse:
+        """
+        Retrieve the item first and invoke only an operation listed in
+        `available_operations`, following its natural-language description. Availability
+        is rechecked at execution time; unavailable operations return 409. Authorization
+        and preparation may call an external provider and return updated state. Link
+        cards advertise authorize without checkout context. Eligible unused AgentCard
+        cards advertise prepare_checkout, which requires checkout context and obtains
+        device approval before native Square Pay. Keep the returned approval page open,
+        poll until ready_to_submit, then submit before preparation.expires_at. Unused
+        preparations expire automatically and cannot be reused. If spend-request
+        creation is rejected with a non-retryable provider error, the card item is
+        deleted and the provider's error code and message are returned. Rate limits
+        return HTTP 429 and retain the card item; stop, back off, and retry the same
+        authorize operation.
+
+        Fill returns a value-free execution result. Validation failures before writing
+        return 400 (invalid request or targets), 403 (access or destination denied), 404
+        (resource not found), or 409 (item or browser not ready). Once writing starts,
+        known partial failures and indeterminate field outcomes return 200 with status
+        `failed` or `unknown`. Fill never submits the page, so it is safe to retry after
+        a failure, an `unknown` outcome, or a transport error.
+
+        Args:
+          amount: Actual transaction amount in minor units, no greater than the approved limit.
+
+          currency: Must match the approved purchase currency.
+
+          occurred_at: Time the merchant outcome was observed.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        ...
+
     @overload
     async def perform_operation(
         self,
@@ -2102,6 +2237,7 @@ async def perform_operation(
 
     @required_args(
         ["id_or_name", "type"],
+        ["id_or_name", "amount", "currency", "occurred_at", "status", "transaction_type", "type"],
         ["id_or_name", "checkout", "type"],
         ["id_or_name", "browser_id", "fields", "type"],
         ["id_or_name", "browser_id", "page_url", "type"],
@@ -2114,6 +2250,7 @@ async def perform_operation(
         *,
         id_or_name: str,
         type: Literal["authorize"]
+        | Literal["confirm_transaction"]
         | Literal["collect"]
         | Literal["prepare_checkout"]
         | Literal["fill"]
@@ -2123,6 +2260,14 @@ async def perform_operation(
         | Literal["1pw_recover"]
         | Literal["1pw_update_access_token"]
         | Literal["webmcp_invoke"],
+        amount: int | Omit = omit,
+        currency: str | Omit = omit,
+        occurred_at: Union[str, datetime] | Omit = omit,
+        status: Literal["APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED"] | Omit = omit,
+        transaction_type: Literal[
+            "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"
+        ]
+        | Omit = omit,
         checkout: VaultCheckoutContextParam | Omit = omit,
         browser_id: str | Omit = omit,
         fields: Iterable[VaultFillFieldParam] | Omit = omit,
@@ -2157,6 +2302,11 @@ async def perform_operation(
                 body=await async_maybe_transform(
                     {
                         "type": type,
+                        "amount": amount,
+                        "currency": currency,
+                        "occurred_at": occurred_at,
+                        "status": status,
+                        "transaction_type": transaction_type,
                         "checkout": checkout,
                         "browser_id": browser_id,
                         "fields": fields,

src/kernel/types/vaults/__init__.py

@@ -113,6 +113,9 @@
 from .one_password_fill_vault_item_operation_request_param import (
     OnePasswordFillVaultItemOperationRequestParam as OnePasswordFillVaultItemOperationRequestParam,
 )
+from .confirm_transaction_vault_item_operation_request_param import (
+    ConfirmTransactionVaultItemOperationRequestParam as ConfirmTransactionVaultItemOperationRequestParam,
+)
 from .one_password_recover_vault_item_operation_request_param import (
     OnePasswordRecoverVaultItemOperationRequestParam as OnePasswordRecoverVaultItemOperationRequestParam,
 )

src/kernel/types/vaults/confirm_transaction_vault_item_operation_request_param.py

@@ -0,0 +1,35 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Union
+from datetime import datetime
+from typing_extensions import Literal, Required, Annotated, TypedDict
+
+from ..._utils import PropertyInfo
+
+__all__ = ["ConfirmTransactionVaultItemOperationRequestParam"]
+
+
+class ConfirmTransactionVaultItemOperationRequestParam(TypedDict, total=False):
+    """Report a real merchant transaction outcome for an issued Kernel Visa credential.
+
+    Never infer success from filling checkout or receiving a credential. Supply the observed status, transaction type, actual amount, currency and timestamp. Unknown outcomes require manual reconciliation, not retry. Each purchase accepts one report.
+    """
+
+    amount: Required[int]
+    """Actual transaction amount in minor units, no greater than the approved limit."""
+
+    currency: Required[str]
+    """Must match the approved purchase currency."""
+
+    occurred_at: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
+    """Time the merchant outcome was observed."""
+
+    status: Required[Literal["APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED"]]
+
+    transaction_type: Required[
+        Literal["PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"]
+    ]
+
+    type: Required[Literal["confirm_transaction"]]

src/kernel/types/vaults/credential_account_vault_item.py

@@ -32,6 +32,7 @@ class AvailableOperation(BaseModel):
 
     type: Literal[
         "authorize",
+        "confirm_transaction",
         "collect",
         "prepare_checkout",
         "fill",

src/kernel/types/vaults/credential_vault_item.py

@@ -39,6 +39,7 @@ class AvailableOperation(BaseModel):
 
     type: Literal[
         "authorize",
+        "confirm_transaction",
         "collect",
         "prepare_checkout",
         "fill",

src/kernel/types/vaults/item_perform_operation_params.py

@@ -15,6 +15,7 @@
 __all__ = [
     "ItemPerformOperationParams",
     "AuthorizeVaultItemOperationRequest",
+    "ConfirmTransactionVaultItemOperationRequest",
     "CollectVaultItemOperationRequest",
     "PrepareCheckoutVaultItemOperationRequest",
     "FillVaultItemOperationRequest",
@@ -33,6 +34,27 @@ class AuthorizeVaultItemOperationRequest(TypedDict, total=False):
     type: Required[Literal["authorize"]]
 
 
+class ConfirmTransactionVaultItemOperationRequest(TypedDict, total=False):
+    id_or_name: Required[str]
+
+    amount: Required[int]
+    """Actual transaction amount in minor units, no greater than the approved limit."""
+
+    currency: Required[str]
+    """Must match the approved purchase currency."""
+
+    occurred_at: Required[Annotated[Union[str, datetime], PropertyInfo(format="iso8601")]]
+    """Time the merchant outcome was observed."""
+
+    status: Required[Literal["APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED"]]
+
+    transaction_type: Required[
+        Literal["PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"]
+    ]
+
+    type: Required[Literal["confirm_transaction"]]
+
+
 class CollectVaultItemOperationRequest(TypedDict, total=False):
     id_or_name: Required[str]
 
@@ -173,6 +195,7 @@ class WebmcpInvokeVaultItemOperationRequest(TypedDict, total=False):
 
 ItemPerformOperationParams: TypeAlias = Union[
     AuthorizeVaultItemOperationRequest,
+    ConfirmTransactionVaultItemOperationRequest,
     CollectVaultItemOperationRequest,
     PrepareCheckoutVaultItemOperationRequest,
     FillVaultItemOperationRequest,

src/kernel/types/vaults/kernel_card_vault_item_spec.py

@@ -37,6 +37,15 @@ class KernelCardVaultItemSpec(BaseModel):
     wallet: str
     """Key of the Kernel wallet item whose enrolled card pays."""
 
+    merchant_category: Optional[str] = None
+    """Actual merchant category when known. Omit rather than invent a category."""
+
+    merchant_category_code: Optional[str] = None
+    """Actual merchant MCC when known.
+
+    Omit rather than invent a code. 0000 is not accepted.
+    """
+
     merchant_country: Optional[str] = None
     """The merchant's ISO 3166-1 alpha-2 country code.
 

src/kernel/types/vaults/kernel_card_vault_item_spec_param.py

@@ -36,6 +36,15 @@ class KernelCardVaultItemSpecParam(TypedDict, total=False):
     wallet: Required[str]
     """Key of the Kernel wallet item whose enrolled card pays."""
 
+    merchant_category: str
+    """Actual merchant category when known. Omit rather than invent a category."""
+
+    merchant_category_code: str
+    """Actual merchant MCC when known.
+
+    Omit rather than invent a code. 0000 is not accepted.
+    """
+
     merchant_country: str
     """The merchant's ISO 3166-1 alpha-2 country code.
 

src/kernel/types/vaults/vault_item.py

@@ -47,6 +47,7 @@ class WalletVaultItemAvailableOperation(BaseModel):
 
     type: Literal[
         "authorize",
+        "confirm_transaction",
         "collect",
         "prepare_checkout",
         "fill",
@@ -122,6 +123,7 @@ class CardVaultItemAvailableOperation(BaseModel):
 
     type: Literal[
         "authorize",
+        "confirm_transaction",
         "collect",
         "prepare_checkout",
         "fill",