[ishad05]

Summary

• Adds PayPal (Orders v2) as a hosted checkout gateway.
• The shopper approves on PayPal, then we capture the payment on our side, either when they return to the store or when PayPal's CHECKOUT.ORDER.APPROVED webhook arrives.
• If the shopper pays and closes the tab, the webhook still places the order.
• PayPal is hidden for currencies it can't settle: SAR, AED, KWD, BHD, QAR and INR. The controller also checks the currency itself.
• Stacked on feat(api): describe every installed gateway for settings screens #27 (api.get_gateways()). Until feat(api): describe every installed gateway for settings screens #27 merges, its 3 commits show here too. The PayPal changes are the last 4 commits.

Changes

• PayPal Gateway Settings DocType: Sandbox/Live credentials, webhook ID, redirect URLs
• services/paypal/{base,live,stub}.py service client, with stub-driven tests
• Order creation, capture, webhook handling, full and partial refunds
• OAuth token cached per mode and client id
• Refund webhooks, so refunds made on the PayPal dashboard are recorded
• WebhookEvent.sync_status: a webhook can ask the request to sync with the gateway
• reusable_checkout = True: an approval link stays payable until the order is captured or expires

Worth a look

• Capture runs through the shared webhook pipeline. The approval webhook only queues a status sync. It never captures in the guest request, and it never captures an order that isn't ours.
• Return page and webhook can capture at the same time. Capture sends a PayPal-Request-Id, and ORDER_ALREADY_CAPTURED counts as success.
• Paid only once the capture settles. A pending capture stays Pending. A declined or denied one is Not Paid.
• Only Pending requests sync, because a sync may capture money.
• PayPal unreachable (5xx, 429, dropped connection): Frappe retries the job. A real decline is logged as Failed and can be replayed with retry_webhook.
• Webhook verification calls PayPal's verify-webhook-signature API. This is a deliberate exception to local signature checks, recorded in AGENTS.md.
• Refunds send no PayPal-Request-Id, so a second partial refund isn't replayed as the first. The row lock and refund ledger prevent double refunds.
• PAYMENT.CAPTURE.REVERSED is ignored, because PayPal can reinstate the money without sending a webhook.
• Logs keep only endpoints, IDs and statuses.

Testing

• Full suite passes locally (237 tests).
• Tested against PayPal Sandbox with a real webhook:
  • USD payment creates one capture, Sales Order, Sales Invoice and Payment Entry
  • Return page and webhook arriving together give one capture and one order
  • With the browser closed after payment, the webhook alone places the order
  • A repeated webhook is ignored
  • Partial refund, then the remaining balance, both reach PayPal; a further refund is refused
  • An unsigned webhook is rejected
  • Re-run in Sandbox after the review changes

Setup

1. Fill in PayPal Gateway Settings.
2. Register a webhook at /api/method/bwh_payments.bwh_payments.webhook.handle?gateway=PayPal for CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.REFUND.PENDING and PAYMENT.REFUND.FAILED, and save the webhook ID.
3. Enable a Payment Gateway Profile named PayPal.
4. Give the PayPal Mode of Payment a default account for each company.

IMG_5680.MOV

🤖 Generated with Claude Code

[harshtandiya]

left a few comments. the two that need fixing before merge are the capture inside the webhook and the token cache key, rest is smaller stuff.

also:

• this is a new doctype + api going into v1-stable. shouldn't it go to main and get backported?
• title says "per-gateway currency support" but supported_currencies is already on v1-stable. also get_gateways and paypal are two separate things, would be cleaner as two PRs
• docs on docs.bwh.tech need updating for get_gateways and paypal