fix(payments): load retry types and add customer_retry to sessions by armando-rodriguez-cko · Pull Request #228 · checkout/checkout-sdk-ruby

armando-rodriguez-cko · 2026-10-27T12:03:05Z

Summary
Loads the payment retry types and aligns the payment retry, hosted payments, payment links and payment sessions requests with the API reference, including Dunning and Downtime retries and customer retries on payment sessions.

Changes

lib/checkout_sdk/payments/payments.rb: requires dunning_retry_request, downtime_retry_request and payment_retry_request (the retry class was never loaded before).
lib/checkout_sdk/payments/payment_retry_request.rb: PaymentRetryRequest now has enabled, dunning and downtime.
lib/checkout_sdk/payments/dunning_retry_request.rb: new DunningRetryRequest (enabled, max_attempts, end_after_days).
lib/checkout_sdk/payments/downtime_retry_request.rb: new DowntimeRetryRequest (enabled).
lib/checkout_sdk/common/customer_retry.rb: CustomerRetry moves to CheckoutSdk::Common::CustomerRetry; CheckoutSdk::Accounts::CustomerRetry stays as a deprecated alias.
lib/checkout_sdk/payments/sessions/payment_sessions_request.rb: adds customer_retry and instruction; deprecates retry and ip_address; payment_type documented as a PaymentType string.
lib/checkout_sdk/payments/links/payment_link.rb: adds instruction and payment_method_configuration; deprecates payment_ip.
lib/checkout_sdk/payments/hosted/hosted_payments_session.rb: customer_retry documented as CheckoutSdk::Common::CustomerRetry; deprecates payment_ip.
lib/checkout_sdk/payments/payment_request.rb: retry documented.
Doc comments completed on every attribute of HostedPaymentsSession, PaymentLink and PaymentSessionsRequest, with ranges and defaults from the API reference.
spec/checkout_sdk/payments/retry_request_serialization_spec.rb: PaymentRetryRequest, DunningRetryRequest, DowntimeRetryRequest, CustomerRetry (all properties, swagger example, false and zero values, alias identity, use from the three endpoints), plus instruction and payment_method_configuration.
spec/checkout_sdk/payments/hosted/hosted_payments_integration_spec.rb: uses CheckoutSdk::Common::CustomerRetry.

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

The top-level max_attempts and end_after_day accessors are removed from PaymentRetryRequest. The class could never be loaded before this change, so no working code is affected. Use dunning.max_attempts and dunning.end_after_days.
Deprecated, still available until the next major version: PaymentSessionsRequest#retry (not part of the payment sessions request; the API ignores it), PaymentSessionsRequest#ip_address, HostedPaymentsSession#payment_ip, PaymentLink#payment_ip and the CheckoutSdk::Accounts::CustomerRetry alias.

README
Not affected: the README does not document retries or these request fields.

PaymentRetryRequest was never required by the gem, misspelled end_after_days and had no dunning or downtime. DunningRetryRequest and DowntimeRetryRequest are added, CustomerRetry moves to Common (the Accounts constant remains as a deprecated alias), and payment sessions gain customer_retry while the off-spec retry attribute is deprecated.

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

🔴 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/sessions/payment_sessions_request.rb

Operational gates

✅ jira_ticket (INT-1748)
✅ independent_review

Files analysed: 11

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

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

🔬 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/sessions/payment_sessions_request.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-27T12:03:15Z

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

This PR fixes a real NameError (PaymentRetryRequest never required), corrects the misspelled end_after_day attribute, moves CustomerRetry to the right module with a backward-compatible alias, adds customer_retry to PaymentSessionsRequest, and ships serialization tests for all new types. The diff does exactly what the description claims and no blocking problems were found.

What I checked

The load order in payments.rb correctly places dunning/downtime before payment_retry_request, which in turn sits before payment_request — no circular dependency or undefined constant at require time.
The deprecated Accounts::CustomerRetry alias is a constant assignment to the same class object, so is_a? checks and equal? identity both work; the spec explicitly verifies this.
PaymentRetryRequest drops max_attempts and end_after_day (the misspelled one) from attr_accessor — any existing callers of those methods will get NoMethodError. The PR description calls this a breaking change only for end_after_day/end_after_days, but the diff shows no deprecation shim on the class itself (only docs), so callers using the old attributes will break silently at runtime rather than getting a deprecation warning.
The hosted_payments_integration_spec fix from PaymentRetryRequest to Common::CustomerRetry is correct — the hosted payments API takes customer_retry (a CustomerRetry), not a PaymentRetryRequest.
The new serialization spec covers all three new types plus the alias and cross-class customer_retry assignment; the max_attempts = 0 edge case is explicitly tested, which is good given the minimum-0 constraint.
The diff is truncated (payment_link.rb and payment_sessions_request.rb are cut off), so the attr_accessor :customer_retry additions to those classes cannot be fully verified from the diff alone, but the spec exercises them and would fail if the accessors were missing.

⚠️ 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}

PaymentRetryRequest was never required on master, so its top-level max_attempts and end_after_day could not be used. Remove them. Document the payment sessions retry attribute as ignored by the API, fix the payment_type doc type and enum, and flag tax_amount as not in the specification. Add instruction to payment links and payment sessions and payment_method_configuration to payment links. Complete payment link and hosted payment docs with spec ranges and defaults.

The API reference marks payment_ip on hosted payments and payment links, and ip_address on payment sessions, as deprecated. Tag them in the YARD docs and assert the exact payment_method_configuration serialization with a nested card property.

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

🔴 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/sessions/payment_sessions_request.rb

Operational gates

✅ jira_ticket (INT-1748)
✅ independent_review

Files analysed: 11

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

agent-wall-e · 2026-10-28T20:58: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
`security_sensitive_path` — `lib/checkout_sdk/payments/sessions/payment_sessions_request.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-28T20:58:52Z

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

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

armando-rodriguez-cko added 3 commits October 28, 2026 21:21

fix(payments): drop non-existent retry end_after_days, complete docs

24ddd38

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

View reviewed changes

armando-rodriguez-cko merged commit 9674299 into master Nov 2, 2026
5 checks passed

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

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

Release 2.8.0 - Payment setup type, issuing updates, network token payouts #231

Merged

Navigation Menu

Repository navigation

fix(payments): load retry types and add customer_retry to sessions - #228

fix(payments): load retry types and add customer_retry to sessions#228
armando-rodriguez-cko merged 4 commits into
masterfrom
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