PayPal Deep Integration

PayPalOrder persists every Checkout order with paypal_order_id, intent (capture or authorize), status (created, saved, approved, voided, completed, payer_action_required), invoice_id, amount, currency, purchase_units, payer_email, payer_id, capture_id, authorization_id, the approval_url returned from PayPal, a typed PayPalOrderMetadata block (invoice_id, debtor_id, debtor_type, fee_category, season_id, custom), brand_name, sandbox flag, and an optional express_profile_id. The /paypal/orders/ CRUD surface filters by status, invoice_id, and payer_id and provides capture, void, and sync endpoints to drive the order through the PayPal lifecycle. Inbound notifications land at POST /paypal/webhooks/, which verifies each call against the PayPal Notifications API, stamps an idempotency_key from the paypal_event_id, and dispatches verified events to typed handlers (CHECKOUT.ORDER.APPROVED, CHECKOUT.ORDER.COMPLETED, CHECKOUT.ORDER.DECLINED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED, PAYMENT.CAPTURE.PENDING).

Failed verifications are stored with status=failed_verification so operators can investigate without losing the payload. PayPalRefund records every refund with paypal_refund_id, paypal_capture_id, paypal_order_id, refund_type (full or partial), reason, note_to_payer, and the seller_payable_breakdown returned by PayPal; sync endpoints reconcile state if a webhook is missed. PayPalExpressProfile stores per-user one-click metadata — paypal_payer_id, payer_email, a vault payment_token, consent_status (pending, active, revoked, expired), display_name, preferred flag, and last_used_at — with activate, revoke, and set-preferred endpoints, integrating with PayPal Vault so saved payment sources can be charged again without sending the user back to the PayPal site.