feat: Add server-to-server card ingest for Kernel wallets

Stainless-Generated-From: b1128ae3997c8cc46f2bcd3d333a47324fa78cf7

Author: kernel-internal[bot]

src/kernel/resources/vaults/items.py

@@ -9,7 +9,14 @@
 
 class AddPaymentMethodVaultItemOperationRequestParam(TypedDict, total=False):
     """
-    Start hosted enrollment of a card in a connected Kernel wallet, including its first card, only when the wallet advertises add_payment_method. Returns a new payment method in pending_enrollment with a single-use card_enrollment URL for the cardholder. Card details go directly to the card vault and are never accepted by this API. Each call creates a separate link that expires after 30 minutes; a failed or expired enrollment does not affect the wallet's other payment methods. Scoped API keys require vaults:write in addition to vaults:use on this vault; otherwise the operation returns 403.
+    Start enrollment of a card in a connected Kernel wallet, including its first card, only when the wallet advertises add_payment_method. Returns a new payment method in pending_enrollment with a single-use action. Card details go directly to the card vault and are never accepted by this API. With enrollment hosted (the default) the action is a card_enrollment URL for the cardholder, which expires after 30 minutes. With enrollment server the action is a card_ingest URL that the card's issuer posts the card to from its backend, which expires after 5 minutes; server enrollment returns 409 when it is not configured for the organization's card backend. A failed or expired enrollment does not affect the wallet's other payment methods. Scoped API keys require vaults:write in addition to vaults:use on this vault; otherwise the operation returns 403.
     """
 
     type: Required[Literal["add_payment_method"]]
+
+    enrollment: Literal["hosted", "server"]
+    """hosted returns a card_enrollment link for the cardholder.
+
+    server returns a card_ingest URL for the card's issuer to post the card to
+    server to server.
+    """

src/kernel/types/vaults/add_payment_method_vault_item_operation_request_param.py

@@ -11,7 +11,7 @@
 class AddPaymentMethodVaultItemOperationResult(BaseModel):
     """The payment method created in pending_enrollment.
 
-    Deliver action.url to the cardholder; it is a single-use capability and must not be logged. Observe completion through the wallet's payment_methods expansion.
+    Deliver a card_enrollment action.url to the cardholder; it is a single-use capability and must not be logged. A card_ingest action.url is posted to by the card's issuer. Observe completion through the wallet's payment_methods expansion.
     """
 
     payment_method: VaultPaymentMethod

src/kernel/types/vaults/add_payment_method_vault_item_operation_result.py

@@ -314,6 +314,13 @@ class AddPaymentMethodVaultItemOperationRequest(TypedDict, total=False):
 
     type: Required[Literal["add_payment_method"]]
 
+    enrollment: Literal["hosted", "server"]
+    """hosted returns a card_enrollment link for the cardholder.
+
+    server returns a card_ingest URL for the card's issuer to post the card to
+    server to server.
+    """
+
 
 class RemovePaymentMethodVaultItemOperationRequest(TypedDict, total=False):
     id_or_name: Required[str]

src/kernel/types/vaults/item_perform_operation_params.py

@@ -33,15 +33,20 @@ class Display(BaseModel):
 
 
 class Action(BaseModel):
-    name: Literal["card_enrollment"]
+    """The open enrollment of a pending payment method.
+
+    card_enrollment is a single-use hosted link for the cardholder. card_ingest is a single-use URL on a Kernel ingest hostname served by the card vault, which the card's issuer posts the card to from its backend; Kernel never receives the card number or CVC.
+    """
+
+    name: Literal["card_enrollment", "card_ingest"]
 
     url: str
 
     capture_token: Optional[str] = None
     """Secret bearer capability for embedded card capture with @onkernel/vault-react.
 
-    Present only for Kernel wallets; never for AgentCard. Treat it like the
-    enrollment URL and do not log or persist it in browser storage.
+    Present only on card_enrollment for Kernel wallets; never for AgentCard. Treat
+    it like the enrollment URL and do not log or persist it in browser storage.
     """
 
 
@@ -71,20 +76,40 @@ class VaultPaymentMethod(BaseModel):
     """Provider-neutral payment-method type normalized to lowercase."""
 
     action: Optional[Action] = None
+    """The open enrollment of a pending payment method.
+
+    card_enrollment is a single-use hosted link for the cardholder. card_ingest is a
+    single-use URL on a Kernel ingest hostname served by the card vault, which the
+    card's issuer posts the card to from its backend; Kernel never receives the card
+    number or CVC.
+    """
 
     expires_at: Optional[datetime] = None
-    """Expiry of a pending enrollment link."""
+    """Expiry of a pending enrollment link or ingest URL."""
+
+    issuer_reference: Optional[str] = None
+    """Kernel wallets only.
+
+    The issuer's reference for a card it pushed with a card_ingest URL.
+    """
 
     status: Optional[Literal["pending_enrollment", "active", "removal_pending", "recovery_required"]] = None
     """Kernel wallets only.
 
-    pending_enrollment means a card_enrollment link is open; active means the card
-    is stored and can pay when capabilities.single_use_card.eligible is true;
-    removal_pending means removal started but the provider outcome is unknown, so
-    retry remove_payment_method; recovery_required means either an enrollment
-    outcome is unknown (remove the method), or the stored card cannot be read
-    (contact support; removal is refused with 409). Consult status_reason to
-    distinguish these cases. Absent for other providers.
+    pending_enrollment means a card_enrollment link or card_ingest URL is open;
+    active means the card is stored and can pay when
+    capabilities.single_use_card.eligible is true; removal_pending means removal
+    started but the provider outcome is unknown, so retry remove_payment_method;
+    recovery_required means either an enrollment outcome is unknown (remove the
+    method), or the stored card cannot be read (contact support; removal is refused
+    with 409). Consult status_reason to distinguish these cases. Absent for other
+    providers.
     """
 
     status_reason: Optional[str] = None
+
+    valid_until: Optional[datetime] = None
+    """Kernel wallets only.
+
+    When a card pushed with a card_ingest URL stops being usable, as its issuer set.
+    """

src/kernel/types/vaults/vault_payment_method.py

@@ -1947,6 +1947,17 @@ def test_method_perform_operation_overload_17(self, client: Kernel) -> None:
         )
         assert_matches_type(VaultItemOperationResponse, item, path=["response"])
 
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_method_perform_operation_with_all_params_overload_17(self, client: Kernel) -> None:
+        item = client.vaults.items.perform_operation(
+            key="key",
+            id_or_name="id_or_name",
+            type="add_payment_method",
+            enrollment="hosted",
+        )
+        assert_matches_type(VaultItemOperationResponse, item, path=["response"])
+
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     def test_raw_response_perform_operation_overload_17(self, client: Kernel) -> None:
@@ -4630,6 +4641,17 @@ async def test_method_perform_operation_overload_17(self, async_client: AsyncKer
         )
         assert_matches_type(VaultItemOperationResponse, item, path=["response"])
 
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_method_perform_operation_with_all_params_overload_17(self, async_client: AsyncKernel) -> None:
+        item = await async_client.vaults.items.perform_operation(
+            key="key",
+            id_or_name="id_or_name",
+            type="add_payment_method",
+            enrollment="hosted",
+        )
+        assert_matches_type(VaultItemOperationResponse, item, path=["response"])
+
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     async def test_raw_response_perform_operation_overload_17(self, async_client: AsyncKernel) -> None: