From 9ac854e2d73931cce7e4879b8505b1e11cf1e27c Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Sat, 10 Oct 2026 23:03:24 +0000 Subject: [PATCH 1/2] feat: Complete Visa vault verification and transaction reporting Stainless-Generated-From: ddefaef675badfba8cf9582b6c68d9a94df54d22 --- api.md | 1 + vaultitem.go | 192 +++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 155 insertions(+), 38 deletions(-) diff --git a/api.md b/api.md index d394537f..81a48ad4 100644 --- a/api.md +++ b/api.md @@ -542,6 +542,7 @@ Params Types: - kernel.AuthorizeVaultItemOperationRequestParam - kernel.CardVaultItemSpecUnionParam - kernel.CollectVaultItemOperationRequestParam +- kernel.ConfirmTransactionVaultItemOperationRequestParam - kernel.CredentialAccountVaultItemRequestParam - kernel.CredentialVaultFieldInputParam - kernel.CredentialVaultFieldType diff --git a/vaultitem.go b/vaultitem.go index 2110ca6a..7ba27560 100644 --- a/vaultitem.go +++ b/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, From 041e2a12a2ce6fe268b2adb5787a0450c851c363 Mon Sep 17 00:00:00 2001 From: "kernel-internal[bot]" <260533166+kernel-internal[bot]@users.noreply.github.com> Date: Sat, 10 Oct 2026 23:08:33 +0000 Subject: [PATCH 2/2] release: 0.124.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 7 +++++++ README.md | 2 +- internal/version.go | 2 +- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 58ebf7f2..cadbcc6f 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.123.0" + ".": "0.124.0" } \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index b674bd10..b5a445a4 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/README.md b/README.md index a9dd7c82..b1690f93 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Or to pin the 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' ``` diff --git a/internal/version.go b/internal/version.go index c297f99c..c867a79b 100644 --- a/internal/version.go +++ b/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