fix(payments): align retry and customer retry types with the spec by armando-rodriguez-cko · Pull Request #701 · checkout/checkout-sdk-java

armando-rodriguez-cko · 2026-10-27T12:02:35Z

Summary
Aligns the payment retry types with the API. customerRetry on hosted payments and payment links only accepts max_attempts (0 to 5) but used PaymentRetryRequest, the retry object of POST /payments. It now uses CustomerRetry, and the old builder and setter calls still compile through deprecated overloads. PaymentRetryRequest.enabled was deprecated although it is the required switch for asynchronous retries. The retry responses were missing attempts_made, and one of them reported a max_attempts the API did not return.

Changes

payments/hosted/HostedPaymentRequest.java, payments/links/PaymentLinkRequest.java: customerRetry now uses CustomerRetry. The builder keeps customerRetry(PaymentRetryRequest) and the class keeps setCustomerRetry(PaymentRetryRequest), both @Deprecated; they convert maxAttempts to CustomerRetry (a request without maxAttempts sends the default of 5, null clears it).
handlepaymentsandpayouts/flow/entities/CustomerRetry.java, flow/requests/PaymentSessionCreateRequest.java: docs aligned with the spec.
payments/request/PaymentRetryRequest.java: enabled is no longer deprecated. maxAttempts and endAfterDays stay deprecated and now point to CustomerRetry.maxAttempts (customer_retry) or DunningRetryRequest via dunning (retry).
payments/request/DunningRetryRequest.java, DowntimeRetryRequest.java, PaymentRequest.java: docs, required markers and ranges from the spec.
payments/response/PaymentRetryResponse.java: attemptsMade added, every field documented.
payments/response/PaymentResponse.java: every property documented, subscription (PaymentSubscription) added.
payments/response/GetPaymentResponse.java: every property documented.
postpayments/.../retry/Retry.java: maxAttempts no longer defaults to 6 when the API leaves it out.
Tests: new CustomerRetrySerializationTest, PaymentRetryResponseSerializationTest (also PaymentResponse.subscription) and RetrySerializationTest; PaymentRetryRequestSerializationTest rewritten with exact JSON assertions; HostedPaymentRequestSerializationTest and PaymentLinkRequestSerializationTest check that both builder overloads and both setters send the same customer_retry.

API Reference

POST /payments (retry, response subscription): https://api-reference.checkout.com/tag/payments/POST/payments.body.retry
GET /payments/{id} (retry): https://api-reference.checkout.com/tag/payments/GET/payments/%7Bid%7D
POST /hosted-payments (customer_retry): https://api-reference.checkout.com/tag/hosted-payments-page/POST/hosted-payments.body.customer_retry
POST /payment-links (customer_retry): https://api-reference.checkout.com/tag/payment-links/POST/payment-links.body.customer_retry
POST /payment-sessions (customer_retry): https://api-reference.checkout.com/tag/flow/POST/payment-sessions.body.customer_retry

Breaking changes
Forced by the API, released as a minor.

HostedPaymentRequest.getCustomerRetry() and PaymentLinkRequest.getCustomerRetry() now return CustomerRetry instead of PaymentRetryRequest: a source break for code that reads it into a PaymentRetryRequest, and a binary break (recompile). customerRetry(PaymentRetryRequest) and setCustomerRetry(PaymentRetryRequest) still work, deprecated. Migration: CustomerRetry.builder().maxAttempts(n).build(), read getCustomerRetry().getMaxAttempts().
Retry.getMaxAttempts() on the request a payment response returns null when the API omits the field, instead of 6; Retry.builder().build() also gives null. Migration: treat null as "not returned".

README
Not affected: the README does not document these types.

agent-wall-e · 2026-10-27T12:02:42Z

🟢 Risk Classification: LOW

Approval route: AI Auto-Approval
Rollback controls: Automated Instant Rollback + feature flags

Classification reasons

no_low_class_matched
prod_source_modified
2.2.6_logical_extension:All changes are non-destructive doc/type alignment fixes (swapping one existing type for another, adding missing response fields, un-deprecating a field, removing a default value) that reuse existing code paths and abstractions without introducing new endpoints, external integrations, persisted data, auth changes, or background processes.

Operational gates

✅ jira_ticket (INT-1748)
✅ independent_review

Files analysed: 17

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-10-27T12:02:43Z

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
`no_low_class_matched`	informational	§2.2 (fall-through)	None of the deterministic Low classes (§2.2.3, §2.2.4, §2.2.7, docs-only) applied; classifier fell through to LLM evaluation.
`prod_source_modified`	informational	§2.1 M7 (informational)	At least one file is non-doc, non-test, non-IaC — i.e. application source code was modified.
`2.2.6_logical_extension` — `All changes are non-destructive doc/type alignment fixes (swapping one existing type for another, adding missing response fields, un-deprecating a field, removing a default value) that reuse existing code paths and abstractions without introducing new endpoints, external integrations, persisted data, auth changes, or background processes.`	classifying	§2.2.6	Sonnet 4.6 evaluator promoted minor → low: the change reuses existing code paths and does not cross a trust boundary.

Kinds:

classifying — this rule contributed to the chosen tier.
informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

agent-wall-e · 2026-10-28T20:58:39Z

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

exceeds_bounded_scope:566>250

Operational gates

✅ jira_ticket (INT-1748)
✅ independent_review

Files analysed: 19

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-10-28T20:58:39Z

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
`exceeds_bounded_scope` — `566>250`	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

classifying — this rule contributed to the chosen tier.
informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

agent-wall-e · 2026-10-28T20:58:50Z

🟠 Advisory review: Concerns worth a look

This PR needs a human approval. Before you give it, these are the things I'd want resolved.

The PR aligns retry/customer-retry SDK types with the API spec, adding CustomerRetry to hosted payments and payment links, fixing PaymentRetryResponse, and removing the spurious default of 6 on Retry.maxAttempts. The changes are largely correct and well-tested, but there is one concrete bug in the deprecated compatibility path and one subtle correctness issue with the CustomerRetry default.

Concerns

In HostedPaymentRequest.toCustomerRetry() and PaymentLinkRequest.toCustomerRetry(), when PaymentRetryRequest.getMaxAttempts() is null, the code calls CustomerRetry.builder().build() which triggers the @Builder.Default and sends max_attempts=5 to the API — but the caller may have intentionally omitted maxAttempts (e.g. passing only enabled:true), and silently sending 5 is a semantic change from the old behaviour of sending nothing; the test shouldConvertDeprecatedCustomerRetryOverloadEdgeCasesForHostedPaymentRequest actually asserts this silent-5 behaviour as correct, but this could surprise callers who were relying on the API's own default.
CustomerRetry.maxAttempts has @Builder.Default = 5, meaning CustomerRetry.builder().build() always serializes {"max_attempts":5} — if a caller wants to send the object without constraining attempts (relying on the server default), there is no way to do so; the PR description says 'null clears it' but there is no way to build a CustomerRetry with null maxAttempts through the Lombok builder given @Builder.Default, which contradicts the stated behaviour.
PaymentRetryRequest.enabled has been moved from a deprecated field to the primary field at the top of the class — in Gson serialization the field declaration order determines JSON key order, and the new order (enabled, dunning, downtime, then deprecated maxAttempts/endAfterDays) is confirmed by the tests, but any existing callers who serialized and stored the JSON and now expect the old key order (dunning first) could be silently broken if they rely on field ordering.
The @Deprecated annotation on test methods (e.g. shouldSerializeDeprecatedCustomerRetryOverloadLikeCustomerRetryForHostedPaymentRequest) suppresses compiler warnings about calling deprecated APIs within those tests, which is the right approach, but @SuppressWarnings("deprecated") would be cleaner and more conventional for this purpose — minor but worth noting.
PaymentSubscription is added to PaymentResponse but the class itself (PaymentSubscription.java) is not visible in the diff; if it is a new class it needs to be confirmed present in the repo, otherwise this will fail to compile.
The diff is truncated so the full content of PaymentRetryRequestSerializationTest, GetPaymentResponse additions, and other files cannot be fully verified — the review is necessarily incomplete on those sections.

⚠️ The diff was too large to read in full, so this review covers only part of the change.

_{This is not an approval. wall-e cannot auto-approve this PR — it is an opinion to help whoever does. Advisory review · us.anthropic.claude-sonnet-4-6 · wall-e 2026.06.19-02}

agent-wall-e · 2026-11-02T11:57:58Z

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

exceeds_bounded_scope:578>250

Operational gates

✅ jira_ticket (INT-1748)
✅ independent_review

Files analysed: 19

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-11-02T11:57:59Z

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
`exceeds_bounded_scope` — `578>250`	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

classifying — this rule contributed to the chosen tier.
informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

customer_retry on POST /hosted-payments and POST /payment-links only accepts max_attempts (0 to 5), so it now uses CustomerRetry instead of PaymentRetryRequest. PaymentRetryRequest.enabled is no longer deprecated: it is the required switch for asynchronous retries on POST /payments. The payment retry response gains attemptsMade, and the request payment retry response no longer reports a max_attempts the API did not return.

…tests

Code scanning flags calls to deprecated members from non-deprecated code. The private converter only serves the deprecated PaymentRetryRequest overloads, and the tests exercise those overloads on purpose, so both are marked deprecated instead of suppressing the warning.

agent-wall-e · 2026-11-02T11:59:42Z

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

exceeds_bounded_scope:578>250

Operational gates

✅ jira_ticket (INT-1748)
✅ independent_review

Files analysed: 19

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-11-02T11:59:43Z

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
`exceeds_bounded_scope` — `578>250`	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

Kinds:

classifying — this rule contributed to the chosen tier.
informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

sonarqubecloud · 2026-11-02T12:00:24Z

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
8.6% Duplication on New Code

See analysis details on SonarQube Cloud

…suing This release adds the Payment Setup payment type, the risk settings on the Payment Setup confirm response and the Tamara risk assessment fields. It also adds the subscription details and the retry attempt count to payment responses, and lets you revoke and suspend Issuing cards without a request body. Customer retries on hosted payments and payment links now use the type the API accepts, and the update card headers the API no longer documents are deprecated. Every deprecated member keeps working and will be removed in the next major version. **Added** Issuing (#697) * `IssuingClient#revokeCard(String cardId)`, `#suspendCard(String cardId)`, `#revokeCardSync(String cardId)` and `#suspendCardSync(String cardId)`. The existing overloads that take a `RevokeCardRequest` or `SuspendCardRequest` now accept `null`, because the request body is optional in the API. Payment Setups (#700) * `PaymentSetupPaymentType` with the values of the Payment Setups API: `REGULAR` (`regular`), `RECURRING` (`recurring`), `MOTO` (`moto`), `INSTALLMENT` (`installment`), `PAY_LATER` (`pay_later`), `UNSCHEDULED` (`unscheduled`). * `PaymentSetupsConfirmResponse#risk` (`PaymentSetupRisk`). * `Tamara#initialization` (`PaymentMethodInitialization`, default `DISABLED`) and `Tamara#riskAssessment`, with the new `TamaraRiskAssessment` (`premiumCustomer`, `riskScore`, `orderCountLast24h`, `linkedDeviceCount`). Payments (#701) * `PaymentResponse#subscription` (`PaymentSubscription`). * `PaymentRetryResponse#attemptsMade`, returned by get payment details. **Changed** * `PaymentRetryRequest#enabled` is no longer deprecated. It is the required switch for asynchronous retries on payment requests (#701). * Request and response fields of payments, payment retries, hosted payments, payment links, payment sessions and Payment Setups now document whether they are required or optional, with the limits, defaults and enum values of the API reference (#700, #701). * Payment Setup payment methods document that an update replaces the payment methods, so `initialization` must be sent as `ENABLED` again to keep a method enabled (#700). **Fixed** * The `Retry` response of a payment request no longer reports `maxAttempts` as 6 when the API did not return it (#701). **Deprecated** All deprecated members keep working and will be removed in the next major version. * `CardUpdateHeaders` and the `IssuingClient#updateCard` and `#updateCardSync` overloads that take it: the API no longer documents the `return-encrypted-cvv` and `Encryption-Key` headers. Headers that are set are still sent. Use `updateCard(String, UpdateCardRequest)` or `updateCardSync(String, UpdateCardRequest)` (#697). * `HostedPaymentRequest#setCustomerRetry(PaymentRetryRequest)` and `HostedPaymentRequestBuilder#customerRetry(PaymentRetryRequest)`: customer retries only accept `max_attempts`, so only that value is kept. Use the `CustomerRetry` overloads (#701). * `PaymentLinkRequest#setCustomerRetry(PaymentRetryRequest)` and `PaymentLinkRequestBuilder#customerRetry(PaymentRetryRequest)`: same reason. Use the `CustomerRetry` overloads (#701). **Breaking changes required by the API** ⚠️ * `PaymentSetupsRequest#paymentType`, `PaymentSetupsResponse#paymentType` and `PaymentSetupsConfirmResponse#paymentType` change from `com.checkout.payments.PaymentType` to `PaymentSetupPaymentType`. The Payment Setups API only accepts the lowercase values; the old type sent `PayLater`, which the API rejects with a 422, and read every value except `regular` as null. Migration: replace `PaymentType.X` with `PaymentSetupPaymentType.X` (#700). * `MerchantAccount#lastPaymentAmount` (Payment Setups customer) changes from `Long` to `Double`, because the API defines it as a number (for example `55.99`). Migration: pass a `Double` (for example `500d`) and read the getter as `Double` (#700). * `HostedPaymentRequest#customerRetry` and `PaymentLinkRequest#customerRetry` change from `PaymentRetryRequest` to `CustomerRetry`, because customer retries only accept `max_attempts` (0 to 5). Code that sets the field keeps compiling through the deprecated overloads; code that reads `getCustomerRetry()` now gets a `CustomerRetry`. Migration: `CustomerRetry.builder().maxAttempts(n).build()` (#701). **Dependencies** * gson 2.14.0, slf4j-api 2.0.18 and commons-codec 1.22.1, all still compatible with Java 8 (#702).

This release adds the Payment Setup payment type, the risk settings on the Payment Setup confirm response and the Tamara risk assessment fields. It also adds the subscription details and the retry attempt count to payment responses, and lets you revoke and suspend Issuing cards without a request body. Customer retries on hosted payments and payment links now use the type the API accepts, and the update card headers the API no longer documents are deprecated. Every deprecated member keeps working and will be removed in the next major version. **Added** Issuing (#697) * `IssuingClient#revokeCard(String cardId)`, `#suspendCard(String cardId)`, `#revokeCardSync(String cardId)` and `#suspendCardSync(String cardId)`. The existing overloads that take a `RevokeCardRequest` or `SuspendCardRequest` now accept `null`, because the request body is optional in the API. Payment Setups (#700) * `PaymentSetupPaymentType` with the values of the Payment Setups API: `REGULAR` (`regular`), `RECURRING` (`recurring`), `MOTO` (`moto`), `INSTALLMENT` (`installment`), `PAY_LATER` (`pay_later`), `UNSCHEDULED` (`unscheduled`). * `PaymentSetupsConfirmResponse#risk` (`PaymentSetupRisk`). * `Tamara#initialization` (`PaymentMethodInitialization`, default `DISABLED`) and `Tamara#riskAssessment`, with the new `TamaraRiskAssessment` (`premiumCustomer`, `riskScore`, `orderCountLast24h`, `linkedDeviceCount`). Payments (#701) * `PaymentResponse#subscription` (`PaymentSubscription`). * `PaymentRetryResponse#attemptsMade`, returned by get payment details. **Changed** * `PaymentRetryRequest#enabled` is no longer deprecated. It is the required switch for asynchronous retries on payment requests (#701). * Request and response fields of payments, payment retries, hosted payments, payment links, payment sessions and Payment Setups now document whether they are required or optional, with the limits, defaults and enum values of the API reference (#700, #701). * Payment Setup payment methods document that an update replaces the payment methods, so `initialization` must be sent as `ENABLED` again to keep a method enabled (#700). **Fixed** * The `Retry` response of a payment request no longer reports `maxAttempts` as 6 when the API did not return it (#701). **Deprecated** All deprecated members keep working and will be removed in the next major version. * `CardUpdateHeaders` and the `IssuingClient#updateCard` and `#updateCardSync` overloads that take it: the API no longer documents the `return-encrypted-cvv` and `Encryption-Key` headers. Headers that are set are still sent. Use `updateCard(String, UpdateCardRequest)` or `updateCardSync(String, UpdateCardRequest)` (#697). * `HostedPaymentRequest#setCustomerRetry(PaymentRetryRequest)` and `HostedPaymentRequestBuilder#customerRetry(PaymentRetryRequest)`: customer retries only accept `max_attempts`, so only that value is kept. Use the `CustomerRetry` overloads (#701). * `PaymentLinkRequest#setCustomerRetry(PaymentRetryRequest)` and `PaymentLinkRequestBuilder#customerRetry(PaymentRetryRequest)`: same reason. Use the `CustomerRetry` overloads (#701). **Breaking changes required by the API** ⚠️ * `PaymentSetupsRequest#paymentType`, `PaymentSetupsResponse#paymentType` and `PaymentSetupsConfirmResponse#paymentType` change from `com.checkout.payments.PaymentType` to `PaymentSetupPaymentType`. The Payment Setups API only accepts the lowercase values; the old type sent `PayLater`, which the API rejects with a 422, and read every value except `regular` as null. Migration: replace `PaymentType.X` with `PaymentSetupPaymentType.X` (#700). * `MerchantAccount#lastPaymentAmount` (Payment Setups customer) changes from `Long` to `Double`, because the API defines it as a number (for example `55.99`). Migration: pass a `Double` (for example `500d`) and read the getter as `Double` (#700). * `HostedPaymentRequest#customerRetry` and `PaymentLinkRequest#customerRetry` change from `PaymentRetryRequest` to `CustomerRetry`, because customer retries only accept `max_attempts` (0 to 5). Code that sets the field keeps compiling through the deprecated overloads; code that reads `getCustomerRetry()` now gets a `CustomerRetry`. Migration: `CustomerRetry.builder().maxAttempts(n).build()` (#701). **Dependencies** * gson 2.14.0, slf4j-api 2.0.18 and commons-codec 1.22.1, all still compatible with Java 8 (#702).

armando-rodriguez-cko requested a review from a team October 27, 2026 12:02

github-advanced-security Bot found potential problems Oct 27, 2026

View reviewed changes

Comment thread src/test/java/com/checkout/payments/request/PaymentRetryRequestSerializationTest.java Fixed

Comment thread src/test/java/com/checkout/payments/request/PaymentRetryRequestSerializationTest.java Fixed

github-advanced-security Bot found potential problems Oct 28, 2026

View reviewed changes

david-ruiz-cko previously approved these changes Oct 30, 2026

View reviewed changes

armando-rodriguez-cko dismissed david-ruiz-cko’s stale review via 2c216b3 November 2, 2026 11:57

armando-rodriguez-cko added 4 commits November 2, 2026 12:59

fix(payments): keep customer retry overload and document responses

b9f31e3

fix(payments): add deprecated customer retry setter and subscription …

fe2b026

…tests

armando-rodriguez-cko force-pushed the fix/INT-1748-retry-types branch from 2c216b3 to 48b757f Compare November 2, 2026 11:59

armando-rodriguez-cko requested a review from david-ruiz-cko November 2, 2026 12:03

david-ruiz-cko approved these changes Nov 2, 2026

View reviewed changes

armando-rodriguez-cko merged commit bc29578 into master Nov 2, 2026
6 checks passed

armando-rodriguez-cko deleted the fix/INT-1748-retry-types branch November 2, 2026 15:21

armando-rodriguez-cko mentioned this pull request Nov 2, 2026

Release 8.9.0 - payment setups, retries and issuing #705

Open

Conversation

armando-rodriguez-cko commented Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

agent-wall-e Bot commented Oct 27, 2026

🟢 Risk Classification: LOW

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 27, 2026

Uh oh!

Uh oh!

Uh oh!

agent-wall-e Bot commented Oct 28, 2026

🟡 Risk Classification: MINOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 28, 2026

Uh oh!

agent-wall-e Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟠 Advisory review: Concerns worth a look

Concerns

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

agent-wall-e Bot commented Nov 2, 2026

🟡 Risk Classification: MINOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Nov 2, 2026

Uh oh!

agent-wall-e Bot commented Nov 2, 2026

🟡 Risk Classification: MINOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Nov 2, 2026

Uh oh!

sonarqubecloud Bot commented Nov 2, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

armando-rodriguez-cko commented Oct 27, 2026 •

edited

Loading

agent-wall-e Bot commented Oct 28, 2026 •

edited

Loading