release: 0.124.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.123.0"
+  ".": "0.124.0"
 }

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.124.0](https://github.com/kernel/kernel-go-sdk/compare/v0.123.0...v0.124.0) (2026-10-10)
+
+
+### Features
+
+* Complete Visa vault verification and transaction reporting ([9ac854e](https://github.com/kernel/kernel-go-sdk/commit/9ac854e2d73931cce7e4879b8505b1e11cf1e27c))
+
 ## [0.123.0](https://github.com/kernel/kernel-go-sdk/compare/v0.122.0...v0.123.0) (2026-10-09)
 
 

README.md

@@ -28,7 +28,7 @@ Or to pin the version:
 <!-- x-release-please-start-version -->
 
 ```sh
-go get -u 'github.com/kernel/kernel-go-sdk@v0.123.0'
+go get -u 'github.com/kernel/kernel-go-sdk@v0.124.0'
 ```
 
 <!-- x-release-please-end -->

api.md

@@ -542,6 +542,7 @@ Params Types:
 - <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#AuthorizeVaultItemOperationRequestParam">AuthorizeVaultItemOperationRequestParam</a>
 - <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#CardVaultItemSpecUnionParam">CardVaultItemSpecUnionParam</a>
 - <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#CollectVaultItemOperationRequestParam">CollectVaultItemOperationRequestParam</a>
+- <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#ConfirmTransactionVaultItemOperationRequestParam">ConfirmTransactionVaultItemOperationRequestParam</a>
 - <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#CredentialAccountVaultItemRequestParam">CredentialAccountVaultItemRequestParam</a>
 - <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#CredentialVaultFieldInputParam">CredentialVaultFieldInputParam</a>
 - <a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk">kernel</a>.<a href="https://pkg.go.dev/github.com/kernel/kernel-go-sdk#CredentialVaultFieldType">CredentialVaultFieldType</a>

internal/version.go

@@ -2,4 +2,4 @@
 
 package internal
 
-const PackageVersion = "0.123.0" // x-release-please-version
+const PackageVersion = "0.124.0" // x-release-please-version

vaultitem.go

@@ -442,25 +442,31 @@ type CardVaultItemSpecUnion struct {
 	// This field is from variant [CardVaultItemSpecAgentcard].
 	CheckoutOrigin string `json:"checkout_origin"`
 	// This field is from variant [KernelCardVaultItemSpec].
+	MerchantCategory string `json:"merchant_category"`
+	// This field is from variant [KernelCardVaultItemSpec].
+	MerchantCategoryCode string `json:"merchant_category_code"`
+	// This field is from variant [KernelCardVaultItemSpec].
 	MerchantCountry string `json:"merchant_country"`
 	JSON            struct {
-		Amount          respjson.Field
-		Context         respjson.Field
-		Currency        respjson.Field
-		MerchantName    respjson.Field
-		MerchantURL     respjson.Field
-		PaymentMethodID respjson.Field
-		Provider        respjson.Field
-		Wallet          respjson.Field
-		ExpiresAt       respjson.Field
-		LineItems       respjson.Field
-		Metadata        respjson.Field
-		Totals          respjson.Field
-		Merchant        respjson.Field
-		CardID          respjson.Field
-		CheckoutOrigin  respjson.Field
-		MerchantCountry respjson.Field
-		raw             string
+		Amount               respjson.Field
+		Context              respjson.Field
+		Currency             respjson.Field
+		MerchantName         respjson.Field
+		MerchantURL          respjson.Field
+		PaymentMethodID      respjson.Field
+		Provider             respjson.Field
+		Wallet               respjson.Field
+		ExpiresAt            respjson.Field
+		LineItems            respjson.Field
+		Metadata             respjson.Field
+		Totals               respjson.Field
+		Merchant             respjson.Field
+		CardID               respjson.Field
+		CheckoutOrigin       respjson.Field
+		MerchantCategory     respjson.Field
+		MerchantCategoryCode respjson.Field
+		MerchantCountry      respjson.Field
+		raw                  string
 	} `json:"-"`
 }
 
@@ -792,6 +798,22 @@ func (u CardVaultItemSpecUnionParam) GetCheckoutOrigin() *string {
 	return nil
 }
 
+// Returns a pointer to the underlying variant's property, if present.
+func (u CardVaultItemSpecUnionParam) GetMerchantCategory() *string {
+	if vt := u.OfKernel; vt != nil && vt.MerchantCategory.Valid() {
+		return &vt.MerchantCategory.Value
+	}
+	return nil
+}
+
+// Returns a pointer to the underlying variant's property, if present.
+func (u CardVaultItemSpecUnionParam) GetMerchantCategoryCode() *string {
+	if vt := u.OfKernel; vt != nil && vt.MerchantCategoryCode.Valid() {
+		return &vt.MerchantCategoryCode.Value
+	}
+	return nil
+}
+
 // Returns a pointer to the underlying variant's property, if present.
 func (u CardVaultItemSpecUnionParam) GetMerchantCountry() *string {
 	if vt := u.OfKernel; vt != nil && vt.MerchantCountry.Valid() {
@@ -1278,6 +1300,68 @@ const (
 	CollectVaultItemOperationRequestTypeCollect CollectVaultItemOperationRequestType = "collect"
 )
 
+// 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.
+//
+// The properties Amount, Currency, OccurredAt, Status, TransactionType, Type are
+// required.
+type ConfirmTransactionVaultItemOperationRequestParam struct {
+	// Actual transaction amount in minor units, no greater than the approved limit.
+	Amount int64 `json:"amount" api:"required"`
+	// Must match the approved purchase currency.
+	Currency string `json:"currency" api:"required"`
+	// Time the merchant outcome was observed.
+	OccurredAt time.Time `json:"occurred_at" api:"required" format:"date-time"`
+	// Any of "APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED".
+	Status ConfirmTransactionVaultItemOperationRequestStatus `json:"status,omitzero" api:"required"`
+	// Any of "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL",
+	// "VERIFICATION", "CHARGEBACK", "FRAUD".
+	TransactionType ConfirmTransactionVaultItemOperationRequestTransactionType `json:"transaction_type,omitzero" api:"required"`
+	// Any of "confirm_transaction".
+	Type ConfirmTransactionVaultItemOperationRequestType `json:"type,omitzero" api:"required"`
+	paramObj
+}
+
+func (r ConfirmTransactionVaultItemOperationRequestParam) MarshalJSON() (data []byte, err error) {
+	type shadow ConfirmTransactionVaultItemOperationRequestParam
+	return param.MarshalObject(r, (*shadow)(&r))
+}
+func (r *ConfirmTransactionVaultItemOperationRequestParam) UnmarshalJSON(data []byte) error {
+	return apijson.UnmarshalRoot(data, r)
+}
+
+type ConfirmTransactionVaultItemOperationRequestStatus string
+
+const (
+	ConfirmTransactionVaultItemOperationRequestStatusApproved  ConfirmTransactionVaultItemOperationRequestStatus = "APPROVED"
+	ConfirmTransactionVaultItemOperationRequestStatusDeclined  ConfirmTransactionVaultItemOperationRequestStatus = "DECLINED"
+	ConfirmTransactionVaultItemOperationRequestStatusPending   ConfirmTransactionVaultItemOperationRequestStatus = "PENDING"
+	ConfirmTransactionVaultItemOperationRequestStatusError     ConfirmTransactionVaultItemOperationRequestStatus = "ERROR"
+	ConfirmTransactionVaultItemOperationRequestStatusCancelled ConfirmTransactionVaultItemOperationRequestStatus = "CANCELLED"
+)
+
+type ConfirmTransactionVaultItemOperationRequestTransactionType string
+
+const (
+	ConfirmTransactionVaultItemOperationRequestTransactionTypePurchase      ConfirmTransactionVaultItemOperationRequestTransactionType = "PURCHASE"
+	ConfirmTransactionVaultItemOperationRequestTransactionTypeAuthorization ConfirmTransactionVaultItemOperationRequestTransactionType = "AUTHORIZATION"
+	ConfirmTransactionVaultItemOperationRequestTransactionTypeCapture       ConfirmTransactionVaultItemOperationRequestTransactionType = "CAPTURE"
+	ConfirmTransactionVaultItemOperationRequestTransactionTypeRefund        ConfirmTransactionVaultItemOperationRequestTransactionType = "REFUND"
+	ConfirmTransactionVaultItemOperationRequestTransactionTypeReversal      ConfirmTransactionVaultItemOperationRequestTransactionType = "REVERSAL"
+	ConfirmTransactionVaultItemOperationRequestTransactionTypeVerification  ConfirmTransactionVaultItemOperationRequestTransactionType = "VERIFICATION"
+	ConfirmTransactionVaultItemOperationRequestTransactionTypeChargeback    ConfirmTransactionVaultItemOperationRequestTransactionType = "CHARGEBACK"
+	ConfirmTransactionVaultItemOperationRequestTransactionTypeFraud         ConfirmTransactionVaultItemOperationRequestTransactionType = "FRAUD"
+)
+
+type ConfirmTransactionVaultItemOperationRequestType string
+
+const (
+	ConfirmTransactionVaultItemOperationRequestTypeConfirmTransaction ConfirmTransactionVaultItemOperationRequestType = "confirm_transaction"
+)
+
 type CredentialAccountVaultItem struct {
 	ID                  string                                         `json:"id" api:"required"`
 	AvailableExpansions []CredentialAccountVaultItemAvailableExpansion `json:"available_expansions" api:"required"`
@@ -1344,8 +1428,8 @@ func (r *CredentialAccountVaultItemAvailableExpansion) UnmarshalJSON(data []byte
 // invoking it through the item operations endpoint.
 type CredentialAccountVaultItemAvailableOperation struct {
 	Description string `json:"description" api:"required"`
-	// Any of "authorize", "collect", "prepare_checkout", "fill",
-	// "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
+	// Any of "authorize", "confirm_transaction", "collect", "prepare_checkout",
+	// "fill", "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
 	// "1pw_recover", "1pw_update_access_token", "webmcp_invoke".
 	Type string `json:"type" api:"required"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
@@ -1717,8 +1801,8 @@ func (r *CredentialVaultItemAvailableExpansion) UnmarshalJSON(data []byte) error
 // invoking it through the item operations endpoint.
 type CredentialVaultItemAvailableOperation struct {
 	Description string `json:"description" api:"required"`
-	// Any of "authorize", "collect", "prepare_checkout", "fill",
-	// "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
+	// Any of "authorize", "confirm_transaction", "collect", "prepare_checkout",
+	// "fill", "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
 	// "1pw_recover", "1pw_update_access_token", "webmcp_invoke".
 	Type string `json:"type" api:"required"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
@@ -2496,20 +2580,27 @@ type KernelCardVaultItemSpec struct {
 	Provider KernelCardVaultItemSpecProvider `json:"provider" api:"required"`
 	// Key of the Kernel wallet item whose enrolled card pays.
 	Wallet string `json:"wallet" api:"required"`
+	// Actual merchant category when known. Omit rather than invent a category.
+	MerchantCategory string `json:"merchant_category"`
+	// Actual merchant MCC when known. Omit rather than invent a code. 0000 is not
+	// accepted.
+	MerchantCategoryCode string `json:"merchant_category_code"`
 	// The merchant's ISO 3166-1 alpha-2 country code. Required for Visa cards, whose
 	// one-time code is issued for the merchant's country.
 	MerchantCountry string `json:"merchant_country"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
 	JSON struct {
-		Amount          respjson.Field
-		Currency        respjson.Field
-		MerchantName    respjson.Field
-		MerchantURL     respjson.Field
-		Provider        respjson.Field
-		Wallet          respjson.Field
-		MerchantCountry respjson.Field
-		ExtraFields     map[string]respjson.Field
-		raw             string
+		Amount               respjson.Field
+		Currency             respjson.Field
+		MerchantName         respjson.Field
+		MerchantURL          respjson.Field
+		Provider             respjson.Field
+		Wallet               respjson.Field
+		MerchantCategory     respjson.Field
+		MerchantCategoryCode respjson.Field
+		MerchantCountry      respjson.Field
+		ExtraFields          map[string]respjson.Field
+		raw                  string
 	} `json:"-"`
 }
 
@@ -2561,6 +2652,11 @@ type KernelCardVaultItemSpecParam struct {
 	Provider KernelCardVaultItemSpecProvider `json:"provider,omitzero" api:"required"`
 	// Key of the Kernel wallet item whose enrolled card pays.
 	Wallet string `json:"wallet" api:"required"`
+	// Actual merchant category when known. Omit rather than invent a category.
+	MerchantCategory param.Opt[string] `json:"merchant_category,omitzero"`
+	// Actual merchant MCC when known. Omit rather than invent a code. 0000 is not
+	// accepted.
+	MerchantCategoryCode param.Opt[string] `json:"merchant_category_code,omitzero"`
 	// The merchant's ISO 3166-1 alpha-2 country code. Required for Visa cards, whose
 	// one-time code is issued for the merchant's country.
 	MerchantCountry param.Opt[string] `json:"merchant_country,omitzero"`
@@ -4142,6 +4238,10 @@ type VaultItemUnionSpec struct {
 	// This field is from variant [CardVaultItemSpecUnion].
 	CheckoutOrigin string `json:"checkout_origin"`
 	// This field is from variant [CardVaultItemSpecUnion].
+	MerchantCategory string `json:"merchant_category"`
+	// This field is from variant [CardVaultItemSpecUnion].
+	MerchantCategoryCode string `json:"merchant_category_code"`
+	// This field is from variant [CardVaultItemSpecUnion].
 	MerchantCountry string `json:"merchant_country"`
 	// This field is from variant [CredentialVaultItemSpecUnion].
 	Fields      []CredentialVaultFieldDefinition `json:"fields"`
@@ -4173,6 +4273,8 @@ type VaultItemUnionSpec struct {
 		Merchant             respjson.Field
 		CardID               respjson.Field
 		CheckoutOrigin       respjson.Field
+		MerchantCategory     respjson.Field
+		MerchantCategoryCode respjson.Field
 		MerchantCountry      respjson.Field
 		Fields               respjson.Field
 		Description          respjson.Field
@@ -4425,8 +4527,8 @@ func (r *VaultItemWalletAvailableExpansion) UnmarshalJSON(data []byte) error {
 // invoking it through the item operations endpoint.
 type VaultItemWalletAvailableOperation struct {
 	Description string `json:"description" api:"required"`
-	// Any of "authorize", "collect", "prepare_checkout", "fill",
-	// "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
+	// Any of "authorize", "confirm_transaction", "collect", "prepare_checkout",
+	// "fill", "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
 	// "1pw_recover", "1pw_update_access_token", "webmcp_invoke".
 	Type string `json:"type" api:"required"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
@@ -4526,8 +4628,8 @@ func (r *VaultItemCardAvailableExpansion) UnmarshalJSON(data []byte) error {
 // invoking it through the item operations endpoint.
 type VaultItemCardAvailableOperation struct {
 	Description string `json:"description" api:"required"`
-	// Any of "authorize", "collect", "prepare_checkout", "fill",
-	// "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
+	// Any of "authorize", "confirm_transaction", "collect", "prepare_checkout",
+	// "fill", "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
 	// "1pw_recover", "1pw_update_access_token", "webmcp_invoke".
 	Type string `json:"type" api:"required"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
@@ -5045,6 +5147,10 @@ type VaultItemOperationResponseUnionSpec struct {
 	// This field is from variant [CardVaultItemSpecUnion].
 	CheckoutOrigin string `json:"checkout_origin"`
 	// This field is from variant [CardVaultItemSpecUnion].
+	MerchantCategory string `json:"merchant_category"`
+	// This field is from variant [CardVaultItemSpecUnion].
+	MerchantCategoryCode string `json:"merchant_category_code"`
+	// This field is from variant [CardVaultItemSpecUnion].
 	MerchantCountry string `json:"merchant_country"`
 	// This field is from variant [CredentialVaultItemSpecUnion].
 	Fields      []CredentialVaultFieldDefinition `json:"fields"`
@@ -5076,6 +5182,8 @@ type VaultItemOperationResponseUnionSpec struct {
 		Merchant             respjson.Field
 		CardID               respjson.Field
 		CheckoutOrigin       respjson.Field
+		MerchantCategory     respjson.Field
+		MerchantCategoryCode respjson.Field
 		MerchantCountry      respjson.Field
 		Fields               respjson.Field
 		Description          respjson.Field
@@ -5333,8 +5441,8 @@ func (r *VaultItemOperationResponseWalletVaultItemAvailableExpansion) UnmarshalJ
 // invoking it through the item operations endpoint.
 type VaultItemOperationResponseWalletVaultItemAvailableOperation struct {
 	Description string `json:"description" api:"required"`
-	// Any of "authorize", "collect", "prepare_checkout", "fill",
-	// "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
+	// Any of "authorize", "confirm_transaction", "collect", "prepare_checkout",
+	// "fill", "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
 	// "1pw_recover", "1pw_update_access_token", "webmcp_invoke".
 	Type string `json:"type" api:"required"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
@@ -5439,8 +5547,8 @@ func (r *VaultItemOperationResponseCardVaultItemAvailableExpansion) UnmarshalJSO
 // invoking it through the item operations endpoint.
 type VaultItemOperationResponseCardVaultItemAvailableOperation struct {
 	Description string `json:"description" api:"required"`
-	// Any of "authorize", "collect", "prepare_checkout", "fill",
-	// "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
+	// Any of "authorize", "confirm_transaction", "collect", "prepare_checkout",
+	// "fill", "1pw_create_access_request", "1pw_access_request_status", "1pw_fill",
 	// "1pw_recover", "1pw_update_access_token", "webmcp_invoke".
 	Type string `json:"type" api:"required"`
 	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
@@ -6200,6 +6308,13 @@ type VaultItemPerformOperationParams struct {
 	// automatically retry provider failures or indeterminate outcomes. Checkout
 	// context is not accepted.
 	OfAuthorize *AuthorizeVaultItemOperationRequestParam `json:",inline"`
+	// This field is a request body variant, only one variant field can be set. 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.
+	OfConfirmTransaction *ConfirmTransactionVaultItemOperationRequestParam `json:",inline"`
 	// This field is a request body variant, only one variant field can be set. Return
 	// the credential item with its collection action. Supported for ready and
 	// pending_collection credential items. Always render the same form from every
@@ -6301,6 +6416,7 @@ type VaultItemPerformOperationParams struct {
 
 func (u VaultItemPerformOperationParams) MarshalJSON() ([]byte, error) {
 	return param.MarshalUnion(u, u.OfAuthorize,
+		u.OfConfirmTransaction,
 		u.OfCollect,
 		u.OfPrepareCheckout,
 		u.OfFill,