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

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

This pull request enhances the documentation and expands the data models related to payout destinations, account holders, and card payout processing in the SDK. It introduces new classes, adds detailed attribute documentation, and improves the clarity and completeness of API model definitions, especially for payout and refund flows.

Model and Documentation Enhancements

Expanded and clarified attribute documentation for AccountHolder, AccountHolderIdentification, and various payout destination classes, specifying required/optional fields, expected formats, and deprecation notes. [1] [2] [3] [4] [5] [6] [7] [8]
Added missing or new enum values and types, such as NETWORK_TOKEN to DestinationType, and documented the use of these types across different payout and refund destinations.

New Classes for Payout Processing

Introduced CardPayoutProcessing to encapsulate affiliate and processing speed details for card payouts.
Added CardPayoutItem to represent individual items in a card payout, supporting item-level metadata.
Created InstructionRemittance for remittance details in bank payout instructions.
Added NetworkTokenDestination to support network token-based payout destinations.

Enum and Type Additions

Added ResidentialStatusType enum for account holders' residential status, and ensured it is required in relevant contexts. [1] [2]

These changes collectively improve the SDK’s support for complex payout and refund scenarios, increase type safety, and provide clearer guidance to developers integrating with the API.

Breaking changes ⚠️

PaymentType 'Moto' has been moved to the correct form 'MOTO'

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

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 7

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

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

🔬 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` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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-28T16:46:56Z

🟠 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 adds NetworkTokenDestination, CardPayoutProcessing, CardPayoutItem, InstructionRemittance, UnreferencedRefundRequest, ResidentialStatusType, NETWORK_TOKEN to DestinationType, and PAY_LATER/MOTO rename to PaymentType, plus extensive doc comments. The structural changes look correct, but there is one breaking value change and one missing require that need resolution.

Concerns

PaymentType::MOTO changes from 'Moto' to 'MOTO' — this is a breaking wire-value change for any existing caller passing MOTO to the API; the PR body flags it as intentional, but a reviewer must confirm no deployed code or stored request templates depend on the old string 'Moto'.
PaymentType::PAY_LATER = 'PayLater' is added in payment_type.rb but there is no corresponding require or test visible in the diff, and it is not mentioned in the payments.rb require list — if PaymentType is a module constant file that is already required, this is fine, but the diff should be checked to confirm payments.rb (or equivalent) still includes it.
NetworkTokenDestination references CheckoutSdk::Payments::NetworkTokenType (VTS, MDES, APPLEPAY, GOOGLEPAY) in both the class doc and the spec, but no network_token_type.rb file or require for it appears anywhere in the truncated diff — if this file is not added, the spec will fail at runtime.
The spec in card_payout_destination_serialization_spec.rb mutates minimal_destination (a let) inside the 'full_destination' let by calling destination = minimal_destination without dup/clone, meaning both lets share the same object; this could cause test interference if RSpec memoizes them across examples, though in practice let re-evaluates per example so it is likely harmless — worth a second look.
payout_billing_descriptor.rb documents reference as both 'min 11 characters' and 'max 15 characters', which is internally inconsistent (min > max is impossible, and 'fewer than 11 characters are recommended' contradicts min 11); a reviewer should verify the correct constraint against the API spec.

⚠️ 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:12Z

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 16

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

agent-wall-e · 2026-10-28T17:23:13Z

🔬 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` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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-28T17:24:58Z

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 16

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

agent-wall-e · 2026-10-28T17:24: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
`security_sensitive_path` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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-28T17:35:06Z

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 23

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

agent-wall-e · 2026-10-28T17:35:06Z

🔬 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` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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-28T17:38:46Z

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 26

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

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

🔬 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` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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-28T18:38:22Z

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 26

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

agent-wall-e · 2026-10-28T18:38:22Z

🔬 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` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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:36:33Z

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 37

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

agent-wall-e · 2026-10-28T21:36:34Z

🔬 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` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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:35Z

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 39

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

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

🔬 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` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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:51Z

🔴 Risk Classification: MAJOR

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

Classification reasons

security_sensitive_path:lib/checkout_sdk/payments/destination/token_destination.rb

Operational gates

✅ jira_ticket (INT-1714)
✅ independent_review

Files analysed: 39

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

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

🔬 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` — `lib/checkout_sdk/payments/destination/token_destination.rb`	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:06Z

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 adds card payouts to network tokens, unreferenced refunds and the missing card payout and bank payout request fields, the Payment Setup payment type, and the Dunning and Downtime payment retry types. It also makes the Issuing revoke and suspend request optional, aligns the PaymentType::MOTO value with the API, and deprecates the members the API no longer accepts on requests. Every deprecated member keeps working and will be removed in the next major version. **Added** Issuing (#225) * `IssuingClient#revoke_card` and `IssuingClient#suspend_card` can now be called without a request; the request argument is optional and an empty JSON object is sent when it is omitted. Payment Setups (#226) * `PaymentSetupPaymentType` with the lowercase values of the Payment Setups API: `REGULAR`, `RECURRING`, `MOTO`, `INSTALLMENT`, `PAY_LATER`, `UNSCHEDULED`. Use it for the `:payment_type` key of a Payment Setup create or update request. * `AccountFundingTransactionSender#reference`. Payouts and unreferenced refunds (#229) * `PaymentsClient#request_unreferenced_refund` and `UnreferencedRefundRequest`, sent to POST /payments with `payment_type` set to `UnreferencedRefund`. * `NetworkTokenDestination` and `DestinationType::NETWORK_TOKEN`, for card payouts and unreferenced refunds to a network token. * `PayoutRequest#segment`, `#items`, `#previous_payment_id` and `#processing`. * `CardPayoutProcessing` (`affiliate_id`, `affiliate_url`, `processing_speed`, `purchase_country`) and `CardPayoutItem` (`type`, `sub_type`). * `PaymentInstruction#remittance` and `InstructionRemittance` (`reference`), for bank payouts. * `CheckoutSdk::Common::ResidentialStatusType` (`RESIDENT`, `NON_RESIDENT`) for `AccountHolder#residential_status`. The field is optional and only used by bank payouts. Payments (#229) * `PaymentType::PAY_LATER` (`PayLater`). Payment retries, hosted payments, payment links and payment sessions (#228) * `PaymentRetryRequest#dunning` and `#downtime`, with the new `DunningRetryRequest` (`enabled`, `max_attempts`, `end_after_days`) and `DowntimeRetryRequest` (`enabled`). * `CheckoutSdk::Common::CustomerRetry` (`max_attempts`). * `PaymentSessionsRequest#customer_retry` and `#instruction`. * `PaymentLink#instruction` and `#payment_method_configuration`. **Changed** * `CustomerRetry` moves from `CheckoutSdk::Accounts` to `CheckoutSdk::Common`; `CheckoutSdk::Accounts::CustomerRetry` remains as an alias of the same class (#228). * `PaymentSessionsRequest#payment_type` is documented as a `PaymentType` string; it was documented as a boolean (#228). * `PayoutSource#amount` is documented as an Integer; it was documented as a String (#229). * Request fields of payouts, unreferenced refunds, Payment Setups, hosted payments, payment links and payment sessions now document whether they are required or optional per request, with the limits and enum values of the API reference (#226, #228, #229). **Fixed** * `PaymentSegment` is now loaded by the gem, so `PayoutRequest#segment`, `UnreferencedRefundRequest#segment` and `PaymentRequest#segment` can take a `PaymentSegment` object (#229). * `PaymentRetryRequest` is now loaded by the gem; it could not be referenced before (#228). **Deprecated** All deprecated members keep working and will be removed in the next major version. * `CheckoutSdk::Issuing::CardUpdateHeaders` and the `headers` argument of `IssuingClient#update_card`: the API no longer documents these headers; call `update_card(card_id, update_card_request)`. Headers that are set are still sent unchanged (#225). * `AccountFundingTransactionSender#first_name`, `#last_name`, `#country_of_birth`, `#nationality` and `#address`: not part of the Payment Setups sender; no replacement (#226). * `AccountFundingTransactionRecipient#account_type`: not part of the Payment Setups recipient; no replacement (#226). * `AccountHolder#full_name`: not in any account holder request; no replacement (#229). * `AccountHolder#gender`: not in any account holder request; no replacement (#229). * `BankAccountDestination#bank`: not in the bank payout destination; no replacement (#229). * `PaymentInstruction#charge_bearer`, `#repair` and `#quote_id`: not in the payout instruction request, still returned when retrieving a payout; no replacement (#229). * `PaymentInstruction#skip_expiry` and `#mvv`: not in the API; no replacement (#229). * `InstructionScheme::SWIFT`: the bank payout request only accepts `local` and `instant`; no replacement (#229). * `PayoutSource#amount`: not in any payout or unreferenced refund source request; no replacement (#229). * `PaymentSessionsRequest#retry`: not part of the payment sessions request and ignored by the API; no replacement (#228). * `HostedPaymentsSession#payment_ip`, `PaymentLink#payment_ip` and `PaymentSessionsRequest#ip_address`: deprecated by the API; no replacement (#228). * `CheckoutSdk::Accounts::CustomerRetry`: use `CheckoutSdk::Common::CustomerRetry` (#228). **Breaking changes required by the API** ⚠️ * `AccountFundingTransactionIdentificationType::TAX_ID` and `::OTHER` are removed, because the API rejects them with a 422. Use `DRIVING_LICENSE`, `PASSPORT` or `NATIONAL_ID` (#226). **Breaking changes (SDK alignment)** ⚠️ * `PaymentType::MOTO` sends `MOTO` instead of `Moto`. Code that uses the constant needs no change; code that compares responses or stored values with the literal `Moto` should compare with `MOTO` (#229). * `PaymentRetryRequest#max_attempts` and `#end_after_day` are removed. The class could not be loaded before this release, so no working code is affected. Use `dunning.max_attempts` and `dunning.end_after_days` (#228).

network_token as a card payout + test

7253ccc

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

e6d406c

Comment fix

75f8cd0

PaymentType PayLater value + more docs

b516112

Small payments scheme review

e7f3d08

Test enhancements

a201f4f

Schema fixes, doc updates + tests

580df4c

Deprecated fields mark up + tests

bc9b480

Comments update

880646f

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

View reviewed changes

david-ruiz-cko merged commit c3e211c into master Oct 30, 2026
5 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 2.8.0 - Payment setup type, issuing updates, network token payouts #231

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!

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 • 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!

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

Uh oh!

Assignees

Labels

david-ruiz-cko commented Oct 28, 2026 •

edited

Loading

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

edited

Loading