fix(payments): align retry types with spec, deprecate top fields by armando-rodriguez-cko · Pull Request #260 · checkout/checkout-sdk-python

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

Summary
Aligns the payment retry request types with the API. CustomerRetry is now one shared type used by hosted payments, payment links and payment sessions, and the top-level max_attempts and end_after_days of PaymentRetryRequest are deprecated in favour of dunning.

Changes

checkout_sdk/common/common.py: CustomerRetry (max_attempts, 0 to 5, default 5) now lives here and is documented from the spec.
checkout_sdk/payments/sessions/sessions.py: the duplicate CustomerRetry is removed; the module imports the shared one, so payment_sessions.CustomerRetry keeps working.
checkout_sdk/payments/payments.py: PaymentRetryRequest, DunningRetryRequest and DowntimeRetryRequest documented from the spec (required, ranges, defaults). Top-level max_attempts and end_after_days marked # Deprecated:; use dunning.max_attempts and dunning.end_after_days. They still serialize when set and will be removed in the next major version.
tests/payments/retry_request_serialization_test.py: every property, enabled=False, max_attempts=0, deprecated fields only when set, PaymentRetryRequest roundtrip with nested DunningRetryRequest and DowntimeRetryRequest, and CustomerRetry on the three endpoints plus its roundtrip.

API Reference

POST /payments (retry): https://api-reference.checkout.com/tag/payments/POST/payments.body.retry
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
None. The deprecated fields still serialize when set.

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

…fter_days The retry object of POST /payments has no max_attempts or end_after_days; they belong to dunning. Payment sessions now share CustomerRetry from common (the old import path still works). Retry and customer retry fields are documented.

agent-wall-e · 2026-10-27T12:03:00Z

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

security_sensitive_path:checkout_sdk/payments/sessions/sessions.py

Operational gates

✅ jira_ticket (INT-1748)
✅ independent_review

Files analysed: 4

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

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

🔬 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
`security_sensitive_path` — `checkout_sdk/payments/sessions/sessions.py`	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

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-27T12:03:08Z

🟢 Advisory review: Looks good to me

This PR still needs a human approval — wall-e cannot auto-approve it. For what it's worth, I read the diff and found nothing I'd block on.

Deprecates top-level max_attempts and end_after_days on PaymentRetryRequest, adds docstrings to retry types, consolidates the duplicate CustomerRetry class, and adds a thorough serialization test suite. The change matches its stated intent and introduces no breaking changes.

What I checked

Verified the duplicate CustomerRetry in sessions.py is removed and replaced by the import from common.common, and the module-level attribute is confirmed to be the same object in test_sessions_module_exposes_shared_type.
Deprecated fields are preserved on PaymentRetryRequest with inline comments; they are not removed, which is consistent with the stated non-breaking intent.
The test for enabled=False and max_attempts=0 correctly verifies that falsy values are serialized rather than dropped, which is an important edge case for the JsonSerializer.
No migration, no removal of existing tests, and no existing callers were broken — the old import path (from checkout_sdk.payments.sessions.sessions import CustomerRetry) continues to work via the re-exported name.

_{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-10-28T20:58:32Z

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

security_sensitive_path:checkout_sdk/payments/sessions/sessions.py

Operational gates

✅ jira_ticket (INT-1748)
✅ independent_review

Files analysed: 4

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

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

🔬 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
`security_sensitive_path` — `checkout_sdk/payments/sessions/sessions.py`	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

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-10-28T20:59:03Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

This release brings Payment Setups in line with the API specification, adds card payouts to card, token and network token destinations, and adds unreferenced refunds. It also documents the payment retry types and deprecates the members the API does not accept, each with its replacement where one exists. Nothing is removed: every deprecated member keeps working until the next major version. **Added** Payment Setups (#258) - `PaymentSetupPaymentType` enum with the lowercase values the Payment Setups API accepts: `regular`, `recurring`, `moto`, `installment`, `pay_later`, `unscheduled`. - `Klarna.action` (`KlarnaAction`, with `type` (`KlarnaActionType.SDK`), `client_token` and `session_id`) and `Klarna.iban`. Both are response only. - `Stcpay.action` (`StcpayAction`, with `type` (`StcpayActionType.OTP`)). Response only. - `Tamara.initialization` (`PaymentMethodInitialization`, default `disabled`) and `Tamara.risk_assessment` (`TamaraRiskAssessment`, with `premium_customer`, `risk_score`, `order_count_last24h` and `linked_device_count`). Payouts and unreferenced refunds (#261) - `PaymentsClient.request_unreferenced_refund(unreferenced_refund_request, idempotency_key=None)` and `UnreferencedRefundRequest`, sent to `POST /payments`. The constructor sets `payment_type` to `UnreferencedRefund`. - Card payout and unreferenced refund destinations: `PaymentRequestCardDestination` (type `card`), `PaymentRequestNetworkTokenDestination` (type `network_token`) and `PaymentRequestTokenDestination` (type `token`). `PaymentRequestIdDestination` (type `id`) already existed. - `PaymentDestinationType.NETWORK_TOKEN`. - `NetworkTokenType` enum: `vts`, `mdes`, `applepay`, `googlepay`. - `CardPayoutProcessing` (`affiliate_id`, `affiliate_url`, `processing_speed`, `purchase_country`), used by `PayoutRequest.processing` and `UnreferencedRefundRequest.processing`. - `CardPayoutItem` (`type`, `sub_type`), the item type of `PayoutRequest.items`. **Changed** Payment Setups (#258) - `Tamara()` now sends `"initialization": "disabled"` when you do not set it; before, it sent no `initialization` at all. This matches the API's default on create and the other payment methods that already carried this default (Klarna, stc pay, Tabby, Bizum, Blik). Set `initialization` to `PaymentMethodInitialization.ENABLED` to enable Tamara. - `PaymentSetupsRequest.payment_type` is typed `PaymentSetupPaymentType` instead of `PaymentType`. Values from `PaymentType` are capitalized (for example `PayLater`), which the Payment Setups API rejects; use `PaymentSetupPaymentType` instead. - `PaymentSetupTerminal.local_date_time` is typed `datetime` instead of `str`. Pass a timezone aware `datetime` so the offset is sent; microseconds are not sent. A string still serializes as before. - `MerchantAccount.last_payment_amount` is typed `float` instead of `int`, as in the specification. - Docs: on update the API replaces the payment methods, so send `initialization` as `enabled` again to keep a method enabled. `Ideal.description`, `Knet.language` and `Bancontact.account_holder_name` are optional in the specification, but the API keeps the method invalid until they are sent. Payouts and unreferenced refunds (#261) - `PayoutRequest.processing` is typed `CardPayoutProcessing` instead of `ProcessingSettings`, and `PayoutRequest.items` holds `CardPayoutItem` instead of `Product`. - `PaymentRequestNetworkTokenSource.token_type` is typed `NetworkTokenType` instead of `str`. Plain strings still serialize as before. Payments (#260) - `checkout_sdk.payments.sessions.sessions` now uses `CustomerRetry` from `checkout_sdk.common.common`. The import from the sessions module still works. - `PaymentRetryRequest`, `DowntimeRetryRequest`, `DunningRetryRequest` and `CustomerRetry` are documented with their ranges and defaults. **Fixed** - Card payout items: use `CardPayoutItem`. Unlike `Product`, it does not send `"type": null` and `"sub_type": null` when they are not set (#261). **Deprecated** All of these are removed in the next major version. Payment Setups (#258) - `PaymentType` imported from `checkout_sdk.payments.setups.setups`: use `PaymentSetupPaymentType`. - `Klarna.payment_method_options`: use `Klarna.action`. - `Stcpay.payment_method_options`: use `Stcpay.action`. - `Tabby.payment_method_options`: no replacement. - `Bizum.payment_method_options`: no replacement. - `PaymentMethodOptions` and `PaymentMethodOption`: use `action` on Klarna and stc pay; no replacement for the other methods. - `PaymentMethodAction.client_token`: for Klarna use `Klarna.action.client_token`; no replacement for PayPal and instrument. - `PaymentMethodAction.session_id`: for Klarna use `Klarna.action.session_id`; no replacement for PayPal and instrument. - `Bizum.initialization`: no replacement. - `Blik.initialization`: no replacement. - `PaymentSetupInstrument.phone`: no replacement (the API ignores it). - `PaymentSetupInstrument.account_holder`: no replacement (the API ignores it). - `PaymentSetupInstrument.allow_update`: no replacement (the API ignores it). Payouts and unreferenced refunds (#261) - `AccountHolder.full_name`: no replacement. - `AccountHolder.gender`: no replacement. - `InstructionScheme.SWIFT`: no replacement (the request accepts only `local` and `instant`). - `PaymentInstruction.charge_bearer`: no replacement. - `PaymentInstruction.repair`: no replacement. - `PaymentInstruction.quote_id`: no replacement. - `PaymentBankAccountDestination.bank`: no replacement. Payments (#260) - `PaymentRetryRequest.max_attempts`: use `PaymentRetryRequest.dunning.max_attempts`. - `PaymentRetryRequest.end_after_days`: use `PaymentRetryRequest.dunning.end_after_days`. **Breaking changes required by the API** ⚠️ None. **Breaking changes (SDK alignment)** ⚠️ None.

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

fix(payments): use Deprecated convention and add retry roundtrip test

ec64ade

armando-rodriguez-cko changed the title ~~deprecate(payments): deprecate top-level retry max_attempts and end_after_days~~ fix(payments): align retry types with spec, deprecate top fields Oct 28, 2026

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

View reviewed changes

armando-rodriguez-cko merged commit 3181632 into main Nov 2, 2026
4 checks passed

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

david-ruiz-cko mentioned this pull request Nov 2, 2026

Release 4.9.0 - Payment setup actions, network token payouts, unreferenced refunds #263

Merged

Navigation Menu

Repository navigation

fix(payments): align retry types with spec, deprecate top fields - #260

fix(payments): align retry types with spec, deprecate top fields#260
armando-rodriguez-cko merged 2 commits into
mainfrom
fix/INT-1748-retry-types

armando-rodriguez-cko commented Oct 27, 2026 •

edited

Loading

Uh oh!

agent-wall-e Bot commented Oct 27, 2026

Uh oh!

agent-wall-e Bot commented Oct 27, 2026

Uh oh!

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

edited

Loading

Uh oh!

agent-wall-e Bot commented Oct 28, 2026

Uh oh!

agent-wall-e Bot commented Oct 28, 2026

Uh oh!

sonarqubecloud Bot commented Oct 28, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

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: MAJOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 27, 2026

Uh oh!

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

Uh oh!

🟢 Advisory review: Looks good to me

What I checked

Uh oh!

agent-wall-e Bot commented Oct 28, 2026

🔴 Risk Classification: MAJOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 28, 2026

Uh oh!

sonarqubecloud Bot commented Oct 28, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

armando-rodriguez-cko commented Oct 27, 2026 •

edited

Loading

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

edited

Loading