feature/INT-1714 - new payout destination types in payments (network token) by david-ruiz-cko · Pull Request #261 · checkout/checkout-sdk-python

david-ruiz-cko · 2026-10-28T16:46:54Z

This pull request introduces several improvements and additions to the payments SDK, focusing on enhanced documentation, new API support, and expanded test coverage. The most significant changes include comprehensive docstrings for key data models, the addition of support for unreferenced refund requests in the payments client, and a new test suite for bank payout request serialization.

Documentation enhancements

Added detailed docstrings and property descriptions to the AccountHolderIdentification, AccountHolder, and Instruction classes in checkout_sdk/common/common.py and checkout_sdk/payments/sessions/sessions.py, clarifying their usage, requirements, and field constraints. [1] [2]

API and client updates

Added UnreferencedRefundRequest to the imports in checkout_sdk/payments/payments_client.py and implemented the request_unreferenced_refund method to support sending unreferenced refund requests via the payments client. [1] [2]

Test coverage

Introduced a new test module, tests/payments/bank_payout_request_serialization_test.py, which provides fixtures and tests for serialization and round-trip encoding/decoding of bank payout requests, ensuring the correctness and completeness of the request payloads.

agent-wall-e · 2026-10-28T16:46:59Z

🟡 Risk Classification: MINOR

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

Classification reasons

no_low_class_matched
prod_source_modified

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 2

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

agent-wall-e · 2026-10-28T16:47:00Z

🔬 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.

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-28T16:47:06Z

🟢 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.

Adds a network_token payout destination type, UnreferencedRefundRequest client method, documentation across several model classes, and thorough serialization test suites. The implementation matches the stated intent and the tests cover the new surface area well.

What I checked

The new request_unreferenced_refund method correctly posts to __PAYMENTS_PATH with the same pattern as request_payout, and the idempotency key is threaded through — tests verify both paths.
The NetworkTokenType enum values (vts, mdes, applepay, googlepay) and PaymentDestinationType.NETWORK_TOKEN addition are consistent between the implementation and the test assertions.
PaymentRequestNetworkTokenDestination is imported and exercised in multiple test files, and the round-trip test explicitly checks every field including nested account_holder properties.
The DRIVING_LICENSE enum value is used in bank_payout_request_serialization_test.py for the sender identification, and the fixture expects 'driving_licence' (with the British spelling) — if the enum value serialises as driving_license (American spelling) that test will fail; this should be verified against the enum definition (not visible in the truncated diff).
The docstring deprecation notices on full_name, gender, charge_bearer, repair, quote_id, and InstructionScheme.SWIFT are consistent with the matching TestDeprecatedPayoutMembersSerialization tests that confirm those fields still serialise.
The diff is truncated so PaymentRequestNetworkTokenDestination, UnreferencedRefundRequest, and several other new classes referenced in tests are not visible — correctness of their field definitions and type discriminator values cannot be fully confirmed from this review.

⚠️ 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-10-28T17:23:02Z

🟡 Risk Classification: MINOR

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

Classification reasons

exceeds_bounded_scope:356>250

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 6

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

agent-wall-e · 2026-10-28T17:23: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
`exceeds_bounded_scope` — `356>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-28T17:31:36Z

🟡 Risk Classification: MINOR

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

Classification reasons

exceeds_bounded_scope:400>250

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 6

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

agent-wall-e · 2026-10-28T17:31:37Z

🔬 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` — `400>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-28T17:38:00Z

🟡 Risk Classification: MINOR

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

Classification reasons

exceeds_bounded_scope:403>250

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 6

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

agent-wall-e · 2026-10-28T17:38:01Z

🔬 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` — `403>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-28T18:37:34Z

🟡 Risk Classification: MINOR

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

Classification reasons

exceeds_bounded_scope:403>250

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 7

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

agent-wall-e · 2026-10-28T18:37:35Z

🔬 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` — `403>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-28T21:13:49Z

🟡 Risk Classification: MINOR

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

Classification reasons

exceeds_bounded_scope:418>250

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 7

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

agent-wall-e · 2026-10-28T21:13:50Z

🔬 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` — `418>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-28T21:35:27Z

🔴 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-1714)
✅ independent_review

Files analysed: 12

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

agent-wall-e · 2026-10-28T21:35:28Z

🔬 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-28T21:54:29Z

🔴 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-1714)
✅ independent_review

Files analysed: 12

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

agent-wall-e · 2026-10-28T21:54:30Z

🔬 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-30T06:25:50Z

🔴 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-1714)
✅ independent_review

Files analysed: 12

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

agent-wall-e · 2026-10-30T06:25:51Z

🔬 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-30T06:26:10Z

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.

network_token as a card payout + test

87bcaef

david-ruiz-cko requested a review from a team October 28, 2026 16:46

david-ruiz-cko changed the title ~~feature/INT-1714 - network_token as a card payout~~ feature/INT-1714 - new payout destination types in payments Oct 28, 2026

david-ruiz-cko changed the title ~~feature/INT-1714 - new payout destination types in payments~~ feature/INT-1714 - new payout destination types in payments (network token) Oct 28, 2026

Doc review + tests

6bd171c

more docs

e02b5b7

InstructionScheme swift deprecated comment

69d3d46

Test enhancements

7de2be8

Scheme fixes + tests

660c1f9

Schema fix, doc updates + tests

48c4ecb

Deprecated fields mark up + tests

1ee42b3

Comments update

57c37b1

armando-rodriguez-cko approved these changes Oct 30, 2026

View reviewed changes

david-ruiz-cko merged commit 1445d56 into main Oct 30, 2026
4 checks passed

david-ruiz-cko deleted the feature/INT-1714 branch October 30, 2026 17:51

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

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

Merged

Conversation

david-ruiz-cko commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation enhancements

API and client updates

Test coverage

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: Looks good to me

What I checked

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

🟡 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

🟡 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

🟡 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

🟡 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

🔴 Risk Classification: MAJOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 28, 2026

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!

agent-wall-e Bot commented Oct 30, 2026

🔴 Risk Classification: MAJOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 30, 2026

Uh oh!

sonarqubecloud Bot commented Oct 30, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

david-ruiz-cko commented Oct 28, 2026 •

edited

Loading

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

edited

Loading