t523: feat(paypal): PayPal PPCP integration review compliance

[superdav42]

Summary

Implements all 5 PayPal PPCP compliance requirements identified in issue #725.

Acceptance Criteria

• Disconnect dialog uses PayPal's required disclaimer text
• Error banners shown when payments_receivable=false or email_confirmed=false
• PayPal blocked from checkout when merchant status is invalid
• payee.merchant_id added to purchase_units in OAuth mode
• PayPal-Debug-Id logged from every API response

Changes

All changes are in a single commit (25ede3f1) on top of main. No conflicts with the Amazon SES integration (GH#723) — different files.

Tests

PayPal test files exist at:

• tests/WP_Ultimo/Gateways/PayPal_REST_Gateway_Test.php
• tests/WP_Ultimo/Gateways/PayPal_OAuth_Handler_Test.php
• tests/WP_Ultimo/Gateways/PayPal_Webhook_Handler_Test.php
• tests/WP_Ultimo/Gateways/Base_PayPal_Gateway_Test.php

WP test environment required to run (bin/install-wp-tests.sh).

Closes #725

---

aidevops.sh v3.5.554 plugin for OpenCode v1.3.0 with claude-sonnet-4-6 spent 14h 12m and 13,232 tokens on this as a headless worker.

Summary by CodeRabbit

Release Notes

• Bug Fixes

  • PayPal gateway now validates merchant account status and automatically disables itself if your account cannot receive payments or email is unconfirmed.
  • Improved error notifications to clearly indicate specific merchant configuration issues instead of generic success messages.

• Improvements

  • Enhanced API request logging for better troubleshooting of PayPal transactions.
  • Updated PayPal disconnection confirmation dialog text.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dc8df446-ef29-4fe2-89bd-60e8b4d2e199

📥 Commits

Reviewing files that changed from the base of the PR and between c687d32 and 25ede3f.

📒 Files selected for processing (2)

• inc/gateways/class-paypal-oauth-handler.php
• inc/gateways/class-paypal-rest-gateway.php

---

📝 Walkthrough

Walkthrough

The changes implement PayPal PPCP integration compliance requirements by modifying merchant status handling in OAuth callbacks to always persist validation flags, adding checkout gating based on merchant verification, and enhancing API response logging with PayPal debug identifiers.

Changes

Cohort / File(s)	Summary
Merchant Status Persistence and Validation inc/gateways/class-paypal-oauth-handler.php	Modified OAuth return handler to always persist paymentsReceivable and emailConfirmed as boolean values with true defaults when absent. Expanded completion log to include these flags. Replaced single success notice with conditional error notices that display when either flag is false, showing success only when both are true.
Gateway Gating and API Logging inc/gateways/class-paypal-rest-gateway.php	Added maybe_remove_for_invalid_merchant_status() checkout gating hook that unsets PayPal gateway when OAuth mode is active and either payment receivability or email confirmation status is false. Enhanced API response logging to capture and record paypal-debug-id headers with request method and endpoint.
Order Payload and UI Refinements inc/gateways/class-paypal-rest-gateway.php	Refactored create_order() to use $purchase_unit variable and conditionally include payee.merchant_id when connected via OAuth. Updated PayPal disconnect confirmation dialog text to match PayPal's required compliance wording.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant OAuth as PayPal OAuth Handler
    participant Gateway as PayPal REST Gateway
    participant Settings as Settings Storage
    participant Checkout as Checkout Flow

    User->>OAuth: Complete OAuth authorization
    OAuth->>OAuth: Extract paymentsReceivable & emailConfirmed
    OAuth->>Settings: Persist merchant status flags (default true)
    OAuth->>OAuth: Log completion with status flags
    
    alt Both flags true
        OAuth->>User: Show success notice
    else paymentsReceivable false
        OAuth->>User: Show error notice
    else emailConfirmed false
        OAuth->>User: Show error notice
    end
    
    Checkout->>Gateway: Get active gateways
    Gateway->>Gateway: Check merchant status validity
    alt Invalid merchant status
        Gateway->>Checkout: Remove PayPal gateway
    else Valid status
        Gateway->>Checkout: Include PayPal gateway
    end
    
    User->>Checkout: Browse payment methods
    Checkout->>User: Display available gateways

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Add modern PayPal REST API gateway with subscription support #305: Modifies the same PayPal OAuth handler and REST gateway files with overlapping changes to merchant status persistence, checkout gating logic, API response handling, and purchase unit construction.
• t549: Write PHPUnit tests for PayPal_OAuth_Handler to reach >=80% coverage #554: Adds PHPUnit tests that directly exercise PayPal OAuth handler's handle_oauth_return() and webhook flows, including test coverage for merchant status field handling and validation edge cases modified in this PR.

Poem

🐰 A PayPal pact, now compliant and bright,
With merchant status validated just right,
Gateways that vanish when credentials are slack,
Debug IDs logged on each API track,
Checkout flows safer—our integration's on track! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately and concisely summarizes the main change: PayPal PPCP integration review compliance requirements are being implemented.
Linked Issues check	✅ Passed	All five PayPal PPCP compliance requirements from issue #725 are implemented: disconnect disclaimer text updated, error notices for invalid merchant status, gateway removal logic added, payee.merchant_id included in orders, and PayPal-Debug-Id logging added.
Out of Scope Changes check	✅ Passed	All changes directly address the five compliance requirements specified in linked issue #725; no out-of-scope modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/725-paypal-ppcp-compliance

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔨 Build Complete - Ready for Testing!

📦 Download Build Artifact (Recommended)

Download the zip build, upload to WordPress and test:

• Build: ultimate-multisite
• ⬇️ Download from GitHub Actions
• ⬇️ Download without Github Account (nightly.link)

🌐 Test in WordPress Playground (Very Experimental)

Click the link below to instantly test this PR in your browser - no installation needed!
Playground support for multisite is very limitied, hopefully it will get better in the future.

🚀 Launch in Playground

Login credentials: admin / password

[github-actions]

Performance Test Results

Performance test results for a249148 are in 🛎️!

Note: the numbers in parentheses show the difference to the previous (baseline) test run. Differences below 2% or 0.5 in absolute values are not shown.

URL: /

Run	DB Queries	Memory	Before Template	Template	WP Total	LCP	TTFB	LCP - TTFB
0	40	37.78 MB	840.50 ms (-51.50 ms / -6% )	154.00 ms (+4.00 ms / +3% )	1017.00 ms (-48.00 ms / -5% )	1958.00 ms (-72.00 ms / -4% )	1871.20 ms (-77.50 ms / -4% )	81.40 ms (-3.65 ms / -4% )
1	56	49.02 MB	932.00 ms (-35.00 ms / -4% )	139.50 ms	1070.50 ms (-43.00 ms / -4% )	2058.00 ms (-52.00 ms / -3% )	1966.90 ms (-64.50 ms / -3% )	78.30 ms

[superdav42]

Completed via PR #726, merged to main.

Merged by deterministic merge pass (pulse-wrapper.sh). No worker summary was available — the worker either crashed before writing one or this PR predates the merge summary convention.