feat: Read Shop Pay card status one read at a time and report outcome details

Stainless-Generated-From: dd6b6b03f72c1649efbd6b4b8b7271c44ccb2981

Author: kernel-internal[bot]

src/kernel/resources/vaults/items.py

@@ -615,6 +615,9 @@ def perform_operation(
             "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"
         ],
         type: Literal["confirm_transaction"],
+        failure_code: str | Omit = omit,
+        order_id: str | Omit = omit,
+        order_url: str | Omit = omit,
         # 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,
@@ -662,6 +665,17 @@ def perform_operation(
 
           occurred_at: Time the merchant outcome was observed.
 
+          failure_code: Why the purchase did not succeed, for any other outcome, such as 3ds_challenge,
+              captcha, login_required, timeout or site_error. payment_declined goes only with
+              DECLINED, which takes no other code. Shop Pay reports it; other providers ignore
+              it.
+
+          order_id: The merchant's order number, for an APPROVED outcome. Shop Pay reports it; other
+              providers ignore it.
+
+          order_url: The merchant's https order page, for an APPROVED outcome. Shop Pay reports it;
+              other providers ignore it.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -1655,6 +1669,9 @@ def perform_operation(
             "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"
         ]
         | Omit = omit,
+        failure_code: str | Omit = omit,
+        order_id: str | Omit = omit,
+        order_url: str | Omit = omit,
         checkout: VaultCheckoutContextParam | Omit = omit,
         fields: Iterable[VaultFillFieldParam] | Omit = omit,
         timeout_ms: int | Omit = omit,
@@ -1698,6 +1715,9 @@ def perform_operation(
                         "occurred_at": occurred_at,
                         "status": status,
                         "transaction_type": transaction_type,
+                        "failure_code": failure_code,
+                        "order_id": order_id,
+                        "order_url": order_url,
                         "checkout": checkout,
                         "fields": fields,
                         "timeout_ms": timeout_ms,
@@ -2600,6 +2620,9 @@ async def perform_operation(
             "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"
         ],
         type: Literal["confirm_transaction"],
+        failure_code: str | Omit = omit,
+        order_id: str | Omit = omit,
+        order_url: str | Omit = omit,
         # 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,
@@ -2647,6 +2670,17 @@ async def perform_operation(
 
           occurred_at: Time the merchant outcome was observed.
 
+          failure_code: Why the purchase did not succeed, for any other outcome, such as 3ds_challenge,
+              captcha, login_required, timeout or site_error. payment_declined goes only with
+              DECLINED, which takes no other code. Shop Pay reports it; other providers ignore
+              it.
+
+          order_id: The merchant's order number, for an APPROVED outcome. Shop Pay reports it; other
+              providers ignore it.
+
+          order_url: The merchant's https order page, for an APPROVED outcome. Shop Pay reports it;
+              other providers ignore it.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -3640,6 +3674,9 @@ async def perform_operation(
             "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD"
         ]
         | Omit = omit,
+        failure_code: str | Omit = omit,
+        order_id: str | Omit = omit,
+        order_url: str | Omit = omit,
         checkout: VaultCheckoutContextParam | Omit = omit,
         fields: Iterable[VaultFillFieldParam] | Omit = omit,
         timeout_ms: int | Omit = omit,
@@ -3683,6 +3720,9 @@ async def perform_operation(
                         "occurred_at": occurred_at,
                         "status": status,
                         "transaction_type": transaction_type,
+                        "failure_code": failure_code,
+                        "order_id": order_id,
+                        "order_url": order_url,
                         "checkout": checkout,
                         "fields": fields,
                         "timeout_ms": timeout_ms,

src/kernel/types/vaults/authorize_vault_item_operation_request_param.py

@@ -9,7 +9,7 @@
 
 class AuthorizeVaultItemOperationRequestParam(TypedDict, total=False):
     """
-    Authorize a Link, Kernel or Shop Pay card using its existing purchase specification. Use only after explicit user approval and when the item advertises authorize; follow the advertised operation's description. For a Link card, pass browser_id and page_url together while the browser is on the final checkout page: Kernel inspects that checkout, chooses how the credential is delivered, and limits fill to that checkout's origin in any browser with this vault attached. Omitting both issues a virtual card that fills any page on the merchant origin. Once approval has been requested, browser_id and page_url are ignored and authorize only re-checks the request. Browser and checkout inspection errors occur before any provider request and can be retried once the browser is on the checkout page. Kernel and Shop Pay cards do not accept browser_id or page_url.
+    Authorize a Link, Kernel or Shop Pay card using its existing purchase specification. Use only after explicit user approval and when the item advertises authorize; follow the advertised operation's description. For a Link or Shop Pay card, pass browser_id and page_url together while the browser is on the final checkout page: Kernel confirms that checkout is open, sends it to the provider as the merchant, and limits fill to that checkout's origin in any browser with this vault attached. For Link it also chooses how the credential is delivered. Omitting both issues a virtual card that fills any page on the merchant origin. Once approval has been requested, browser_id and page_url are ignored and authorize only re-checks the request. Browser and checkout inspection errors occur before any provider request and can be retried once the browser is on the checkout page. Kernel cards do not accept browser_id or page_url.
     """
 
     type: Required[Literal["authorize"]]

src/kernel/types/vaults/confirm_transaction_vault_item_operation_request_param.py

@@ -32,3 +32,23 @@ class ConfirmTransactionVaultItemOperationRequestParam(TypedDict, total=False):
     ]
 
     type: Required[Literal["confirm_transaction"]]
+
+    failure_code: str
+    """
+    Why the purchase did not succeed, for any other outcome, such as 3ds_challenge,
+    captcha, login_required, timeout or site_error. payment_declined goes only with
+    DECLINED, which takes no other code. Shop Pay reports it; other providers ignore
+    it.
+    """
+
+    order_id: str
+    """The merchant's order number, for an APPROVED outcome.
+
+    Shop Pay reports it; other providers ignore it.
+    """
+
+    order_url: str
+    """The merchant's https order page, for an APPROVED outcome.
+
+    Shop Pay reports it; other providers ignore it.
+    """

src/kernel/types/vaults/item_perform_operation_params.py

@@ -75,6 +75,26 @@ class ConfirmTransactionVaultItemOperationRequest(TypedDict, total=False):
 
     type: Required[Literal["confirm_transaction"]]
 
+    failure_code: str
+    """
+    Why the purchase did not succeed, for any other outcome, such as 3ds_challenge,
+    captcha, login_required, timeout or site_error. payment_declined goes only with
+    DECLINED, which takes no other code. Shop Pay reports it; other providers ignore
+    it.
+    """
+
+    order_id: str
+    """The merchant's order number, for an APPROVED outcome.
+
+    Shop Pay reports it; other providers ignore it.
+    """
+
+    order_url: str
+    """The merchant's https order page, for an APPROVED outcome.
+
+    Shop Pay reports it; other providers ignore it.
+    """
+
 
 class CollectVaultItemOperationRequest(TypedDict, total=False):
     id_or_name: Required[str]

src/kernel/types/vaults/shop_pay_card_state.py

@@ -41,6 +41,8 @@ class ShopPayCardState(BaseModel):
     ]
     """declined covers a request the shopper declined or that was cancelled.
 
+    consumed means the transaction outcome was reported with confirm_transaction;
+    the card is no longer stored and cannot be filled again, whatever the outcome.
     recovery_required means a provider operation has an unresolved outcome and the
     card cannot be used. When status_reason says the provider refused retrieval
     before acceptance, no card was issued and a later read retries. Otherwise follow

src/kernel/types/vaults/shop_pay_card_vault_item_spec.py

@@ -28,16 +28,17 @@ class LineItem(BaseModel):
 class ShopPayCardVaultItemSpec(BaseModel):
     """Shop Pay purchase.
 
-    amount is the limit the shopper approves; totals must include exactly one positive total no higher than it. context is shown to the shopper when they approve. Authorize without checkout context: authorize returns an approval action for the shopper, who approves the purchase in Shop. Share its URL unchanged when present. Once approved, the card becomes ready and fills checkouts on the merchant_url origin. Report the merchant outcome with confirm_transaction.
+    amount is the limit the shopper approves; totals must include exactly one positive total no higher than it. context is shown to the shopper when they approve. Authorize it with the browser at final checkout: Kernel sends that page to Shop as the merchant and the card fills only on its origin. Without browser_id and page_url it authorizes for merchant_url. authorize returns an approval action for the shopper, who approves the purchase in Shop; share its URL unchanged when present. Report the merchant outcome with confirm_transaction, which ends the card.
     """
 
     amount: int
-    """Approval limit in minor currency units."""
+    """Approval limit in minor currency units, at most 1000000."""
 
     context: str
     """What is being bought and why, written for the shopper."""
 
     currency: str
+    """Shop accepts USD spend requests only."""
 
     merchant_name: str
 

src/kernel/types/vaults/shop_pay_card_vault_item_spec_param.py

@@ -28,16 +28,17 @@ class LineItem(TypedDict, total=False):
 class ShopPayCardVaultItemSpecParam(TypedDict, total=False):
     """Shop Pay purchase.
 
-    amount is the limit the shopper approves; totals must include exactly one positive total no higher than it. context is shown to the shopper when they approve. Authorize without checkout context: authorize returns an approval action for the shopper, who approves the purchase in Shop. Share its URL unchanged when present. Once approved, the card becomes ready and fills checkouts on the merchant_url origin. Report the merchant outcome with confirm_transaction.
+    amount is the limit the shopper approves; totals must include exactly one positive total no higher than it. context is shown to the shopper when they approve. Authorize it with the browser at final checkout: Kernel sends that page to Shop as the merchant and the card fills only on its origin. Without browser_id and page_url it authorizes for merchant_url. authorize returns an approval action for the shopper, who approves the purchase in Shop; share its URL unchanged when present. Report the merchant outcome with confirm_transaction, which ends the card.
     """
 
     amount: Required[int]
-    """Approval limit in minor currency units."""
+    """Approval limit in minor currency units, at most 1000000."""
 
     context: Required[str]
     """What is being bought and why, written for the shopper."""
 
     currency: Required[str]
+    """Shop accepts USD spend requests only."""
 
     merchant_name: Required[str]
 

tests/api_resources/vaults/test_items.py

@@ -793,6 +793,24 @@ def test_method_perform_operation_overload_3(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_3(self, client: Kernel) -> None:
+        item = client.vaults.items.perform_operation(
+            key="key",
+            id_or_name="id_or_name",
+            amount=0,
+            currency="SEW",
+            occurred_at=parse_datetime("2019-12-27T18:11:19.117Z"),
+            status="APPROVED",
+            transaction_type="PURCHASE",
+            type="confirm_transaction",
+            failure_code="failure_code",
+            order_id="x",
+            order_url="https://example.com",
+        )
+        assert_matches_type(VaultItemOperationResponse, item, path=["response"])
+
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     def test_raw_response_perform_operation_overload_3(self, client: Kernel) -> None:
@@ -3396,6 +3414,24 @@ async def test_method_perform_operation_overload_3(self, async_client: AsyncKern
         )
         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_3(self, async_client: AsyncKernel) -> None:
+        item = await async_client.vaults.items.perform_operation(
+            key="key",
+            id_or_name="id_or_name",
+            amount=0,
+            currency="SEW",
+            occurred_at=parse_datetime("2019-12-27T18:11:19.117Z"),
+            status="APPROVED",
+            transaction_type="PURCHASE",
+            type="confirm_transaction",
+            failure_code="failure_code",
+            order_id="x",
+            order_url="https://example.com",
+        )
+        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_3(self, async_client: AsyncKernel) -> None: