fix(pay): handle nullable options for terminal payment states

[ignaciosantise]

Summary

• Fixes "Invalid Response Payload" error when calling get_payment_options on payments in terminal states (succeeded, failed, expired, cancelled) — the API returns "options": null in that case, which progenitor previously failed to deserialize into Vec<PaymentOption>
• Marks the options field as nullable in the OpenAPI spec for GetPaymentOptionsResponse
• Exposes options as Option<Vec<PaymentOption>> end-to-end so callers can distinguish null (terminal state — check info.status) from [] (no viable options, e.g. insufficient balance)
• Added unit test covering the null options terminal-state path

Breaking change

• PaymentOptionsResponse.options is now Option<Vec<PaymentOption>> (nullable in FFI/JSON consumers). Swift/Kotlin wallets will need to handle the optional.

Caveats

• The OpenAPI spec edit is currently a manual hand-tweak. The backend team will publish an updated spec with nullable: true on options; once that's released, this spec file should be replaced wholesale with the official version before merging.

Test plan

• All pay module tests pass (84 passed)
• Unit test exercises the "options": null path with a succeeded payment response
• Replace openapi.json with the official spec once released by the backend team
• Verify with a real succeeded payment that the SDK returns options: None + correct info.status

🤖 Generated with Claude Code

[claude]

Claude finished @ignaciosantise's task in 1m 6s —— View job

---

Review complete

• Gather context
• Read changed files
• Analyze changes
• Post review

Found 1 issue(s)

Issue 1: No unit test for null options (terminal state) case

ID: mod-null-options-test-a3f1
File: crates/yttrium/src/pay/mod.rs
Severity: LOW
Category: code_quality

Context:

• Pattern: The fix handles options: null via unwrap_or_default() (line 986), but there's no unit test exercising this path. Existing tests cover options: [...] (success) and HTTP error codes (404, 410) but not {"options": null}.
• Risk: Silent regression if the codegen or serde behavior changes (e.g., if options stops being Option<Vec<...>>).
• Impact: Future refactors could break terminal-state handling without failing tests.
• Trigger: Payment in succeeded/failed/cancelled/expired state returning null options.

Recommendation: Add a test alongside the existing ones:

#[tokio::test]
async fn test_get_payment_options_null_options_terminal_state() {
    // mock returns {"options": null, "info": {...}}
    // assert response.options.is_empty()
    // assert response.info.is_some() // status shows terminal state
}

Fix this →

The core fix is correct — marking options as nullable: true in the OpenAPI spec (while keeping it in required, meaning the key is always present but may be null) and using .unwrap_or_default() is the right approach for OpenAPI 3.0 semantics.

[Copilot]

Pull request overview

This PR updates the Pay SDK’s get_payment_options handling and the embedded OpenAPI spec to support payments in terminal states where the backend may return options: null, avoiding “Invalid Response Payload” decoding failures.

Changes:

• Mark GetPaymentOptionsResponse.options as nullable in the OpenAPI spec.
• Coerce null options into an empty vector in WalletConnectPay::get_payment_options and use that for logging/caching/response mapping.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
crates/yttrium/src/pay/openapi.json	Marks options as nullable in GetPaymentOptionsResponse to reflect backend behavior in terminal states.
crates/yttrium/src/pay/mod.rs	Adjusts get_payment_options to handle nullable options by defaulting to an empty list for downstream logic.

Comments suppressed due to low confidence (1)

crates/yttrium/src/pay/mod.rs:1001

• This change introduces new behavior for when the API returns options: null, but the existing get_payment_options tests only cover non-null arrays. Add a test case that mocks a 200 response with "options": null (and any other required fields) and asserts the SDK returns an empty options vec and clears the cache accordingly.

        let api_response = response.into_inner();
        let options = api_response.options.unwrap_or_default();
        pay_debug!(
            "get_payment_options: success, {} options",
            options.len()
        );

        // Cache the options with their raw actions
        let cached: Vec<CachedPaymentOption> = options
            .iter()
            .map(|o| CachedPaymentOption {
                option_id: o.id.clone(),
                actions: o.actions.clone(),
            })
            .collect();
        let mut cache = self.cached_options.write();
        *cache = cached;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chris13524]

Instead of defaulting to empty set of options, I think you should early return w/ the status indicating that the payment is no longer available? Idk anything other than defaulting to empty

[ignaciosantise]

i think i will just return the null value, and on wallet side check the payment status