Release Notes

This page lists what changed in the Kody Payments API, newest first. It covers the protocol (.proto) releases that every language SDK is generated from, so a version number here is the same number you see on your SDK package.

• Entries are grouped as Added, Changed, Deprecated and Removed.
• Versions that make no change to the APIs documented on this site are left out.
• The language SDKs are released independently and can lag behind the protocol. Before relying on something listed here, confirm your SDK has been published at that version or later — see Protocol versions and SDK releases.
• Every release is also published as a GitHub Release on kp-protocols-clientsdk; watch the repository to be notified of new ones.

---

2026

v1.8.16 · 2026-10-16

Added

• PaymentTransactionDetail.merchant_business_id and merchant_business_name — the merchant business the transaction's store belongs to. Absent when the store has none.

Changed

• PaymentTransactionDetail.kody_payout_code is renamed short_payout_id (field number unchanged): the short, shareable reference of the payout that settled the transaction. Absent until the transaction is paid out.
• failure_reason on the pre-authorisation responses is also set when status is DECLINED, not only FAILED.

Clarified

• PaymentDetails.failure_reason is reported by PayWithCardToken. GetTokenPaymentDetails does not report it: for a failed payment it answers with its error branch instead.

v1.8.15 · 2026-10-16

Added

• failure_reason — why a card was refused, as a description from the payment provider — on Online Payments PaymentDetails, Pre-Authorisation PreAuthorisationResponse and GetPreAuthorisationResponse. It is for display and logging only: its wording can change, so do not parse it or branch on it; branch on status. Not set when the payment did not fail, when no reason is available, or for payments that failed before this release.
• NOT_FOUND on Online Payments GetCardTokenResponse.Error.Type, returned when the token does not exist.

v1.8.14 · 2026-10-13

Added

• Pre-Authorisations: Capture.capture_reference — the reference you sent on CaptureAuthorisation, so a capture can be matched to its request. Not set for captures made before this release.

v1.8.13 · 2026-10-08

Changed

• GetPaymentTransactionList reports one calendar day in the store's timezone, and any day can be requested: today (what has happened so far), any earlier date, or a future date (empty). The three-day limit from v1.8.10 no longer applies. A missing or malformed transaction_date, a page_size out of range, or a cursor used with a different filter is INVALID_ARGUMENT.

v1.8.12 · 2026-09-24

Changed

• GetPaymentTransactionList: filter and filter.transaction_date are required. The endpoint reports one day at a time, so a request without a date is rejected.

v1.8.11 · 2026-09-24

Added

• PaymentTransactionDetail.kody_payout_code — the Kody payout reference linked to the transaction's settlement (renamed short_payout_id in v1.8.16).

Changed

• GetPaymentTransactionList: filter.transaction_date is now a string in ISO 8601 date form ("2026-09-16", exactly YYYY-MM-DD) instead of google.type.Date. The field number is unchanged.
• v1.8.10 could not be built in some language SDKs because of the google.type.Date dependency. Use v1.8.11 or later.

v1.8.10 · 2026-09-22

Added

• GetPaymentTransactionList (KodyEcomPaymentsService) — transaction-level Sales reporting for one store, with the same rows and values as Kody Universe > Sales > Transactions > Download.
  • Reports the three completed calendar days before today, in the store's own timezone.
  • Cursor paging with page_size from 1 to 1000 (default 100); next_cursor is absent on the last page. There is no total count.

v1.8.9 · 2026-09-18

Changed

• Six enum-typed response fields now have explicit presence (optional), so an unset field is no longer read as the enum's first value. Check presence before reading them. The wire format is unchanged.

Field	Value read when unset
PaymentDetailsResponse.PaymentData.payment_method (Online Payments)	VISA
GetCardTokenResponse.Response.payment_method (Online Payments)	VISA
TokenDetailsResponse.CardInfo.payment_method (Terminal tokens)	VISA
PaymentCard.payment_method (Pre-Authorisations)	VISA
CloseBatchResponse.status (Terminal Payments)	SUCCESS
PayResponse.PaymentData.payment_method_type (Terminal Payments)	CARD

SDKs generated before this release cannot tell "unset" from the first value; use payment_method_variant as the signal there.

v1.8.8 · 2026-09-09

Changed

• Online Payments: PaymentDetails.amount_refunded_minor_units and fully_refunded are now optional, so "not reported" can be told apart from "nothing refunded". GetPayments does not fill in the refund fields — use PaymentDetails to read a payment's refunds.

v1.8.7 · 2026-09-04

Added

• Online Payments: PaymentDetails.refunds (each with its own id, refund_psp_reference, amount, event_date and status), amount_refunded_minor_units and fully_refunded, plus the Refund.Status enum (PENDING, REQUESTED, SUCCEEDED, FAILED, CANCELLED).
• Terminal Payments: PayResponse.amount_refunded and fully_refunded, and status on each entry of PayResponse.refunds.

Deprecated

• Terminal Payments: PaymentStatus.REFUND_PENDING and REFUND_REQUESTED. A refunded payment keeps its payment status; read refunds instead.

Removed

• psp_reference as an identifier on Online Payments Refund and Terminal Payments Void. Identify the payment with payment_id. A request that still sets psp_reference carries no identifier and is rejected. The field number and name are reserved.

Clarified

• RefundResponse.status says only whether the refund request was accepted. The refund's own outcome is refunds[].status.

v1.8.6 · 2026-09-04

Added

• Online Payments: RefundRequest.idempotency_uuid. Without it, a retry cannot be told apart from a second partial refund.

Deprecated

• capture_options on PaymentInitiationRequest and PayWithCardTokenRequest (and the CaptureOptions message). Delayed capture and release are no longer supported.

Clarified

• RefundResponse.paymentTransactionId is the refund's own id, not the payment's.

v1.8.5 · 2026-07-17

Added

• Online Payments: PaymentInitiationRequest.idempotency_uuid; required when tokenise_card is true.

v1.8.4 · 2026-07-17

Added

• Online Payments: InitiatePayment can tokenise the card (tokenise_card) on a payment with a non-zero amount. New request fields payer_reference and recurring_processing_model, both used with tokenise_card.
• Online Payments: GetCardTokenResponse.Response.card_expiry_date (MM/yyyy).

v1.8.0 – v1.8.3

No changes to the APIs documented here.

v1.7.36 · 2026-04-29

Added

• Online Payments: CreateTokenRequest.expiry to control the tokenisation page timeout. The default stays 30 minutes.

v1.7.34 / v1.7.35 · 2026-03-06

Added

• Terminal Payments: PayRequest.tips_amount — an explicit tip amount, included in the total.

---

2025

v1.7.x — Pre-authorisation, terminal card tokens, batch close

Version	Date	Change
v1.7.33	2025-12-24	Added Terminal Payments CloseBatch — trigger end-of-day batch settlement for chosen terminals; supports partial success.
v1.7.32	2025-12-19	Added TokenSource on PreAuthoriseWithCardToken (KODY or ADYEN).
v1.7.31	2025-12-12	Added PAYME to the Terminal Payments PaymentMethods filter.
v1.7.29	2025-11-12	Changed Pre-authorisation PreAuthoriseWithCardToken and TopUpAuthorisation now return a stream.
v1.7.25	2025-10-23	Added captured_amount_minor_units on GetPreAuthorisationResponse.
v1.7.23	2025-10-13	Added captures list on GetPreAuthorisationResponse.
v1.7.20	2025-10-08	Added exchange_rate and batch_id on Terminal Payments PaymentData.
v1.7.18	2025-10-06	Added Pre-authorisation RefundCapture.
v1.7.16	2025-10-01	Added adjustments list on GetPreAuthorisationResponse.
v1.7.12	2025-09-18	Added Pre-authorisation PreAuthoriseWithCardToken.
v1.7.10	2025-09-15	Added Terminal tokens PayWithCardToken and GetTokenPayment.
v1.7.7	2025-08-28	Added Terminal card tokens: CreateCardToken (streaming) and GetCardToken.
v1.7.5	2025-08-25	Added funding_source and card_last_4_digits on Online Payments GetCardTokenResponse.
v1.7.3	2025-08-20	Added Pre-authorisation: PreAuthorise, TopUpAuthorisation, CaptureAuthorisation, ReleaseAuthorisation, GetPreAuthorisation. Added Online Payments GetTokenPaymentDetails.
v1.7.0	2025-06-18	Added Online Payments card tokens: CreateCardToken, DeleteCardToken, GetCardTokens, PayWithCardToken, and the RecurringProcessingModel enum.

v1.6.x — Streaming for Online Payments

Version	Date	Change
v1.6.0	2025-03-13	Added Online Payments InitiatePaymentStream and PaymentDetailsStream — the server pushes status updates until the payment resolves.

v1.5.x — Void and accepted payment methods

Version	Date	Change
v1.5.5	2025-01-31	Added Terminal Payments Void.
v1.5.0	2025-01-16	Added accepts_only — an allow-list of accepted payment methods.

---

2024

v1.4.x — Online Payments refunds

Version	Date	Change
v1.4.9	2024-12-18	Added an idempotency key on Terminal Payments Refund.
v1.4.3	2024-11-25	Added Online Payments Refund.

v1.3.x — Terminal refunds and tips

Version	Date	Change
v1.3.7	2024-10-30	Added Terminal Payments Refund.
v1.3.2	2024-09-10	Added show_tips on PayRequest to display tip options on the terminal.
v1.3.1	2024-08-19	Added payment expiry timer on Online Payments PaymentInitiationRequest.

v1.2.x — Online Payments introduced

Version	Date	Change
v1.2.6	2024-07-04	Added Online Payments GetPayments (paginated list).
v1.2.1	2024-06-25	Added KodyEcomPaymentsService: InitiatePayment and PaymentDetails.

v1.0.0 · 2024-01-15

Added

• KodyPayTerminalService (Terminal Payments): Terminals, Pay (streaming), Cancel, PaymentDetails.