feat: integrate PayPal checkout in Commera

[ishad05]

Summary

Commera no longer names any payment gateway in code. Every gateway comes from bwh_payments or from another provider app, and this adds the Commera side of PayPal (bwhtech/bwh_payments#7) and Braintree (bwhtech/bwh_payments#23).

Changes

• Gateway cards come from bwh_payments. Settings → Payments builds a card for every gateway bwh_payments ships, from bwh_payments.api.get_gateways() (name, description, docs link, settings DocType, capabilities). The hard-coded Razorpay, Stripe, Telr and Tabby list is gone, so a new bwh_payments gateway needs no change in Commera. Cards are ordered by name.

• New hook: commera_payment_gateways, for provider apps outside bwh_payments:

  # provider app's hooks.py
  commera_api_version = [1]
  commera_payment_gateways = ["my_app.gateways.wallet"]
  # each path returns {slug, label, blurb, settings_doctype, docs_url, capabilities}

  Cards appear after bwh_payments' gateways. A card can't replace one of them, an app built for another API version is skipped, and a card that fails or is incomplete is logged and skipped, so one broken app never breaks checkout.

• reusable_checkout capability. For a gateway whose checkout link stays payable after the shopper closes the tab, such as PayPal and Braintree:

  • a returning shopper is sent back to the open link, or to the confirmation page if it's already paid, after the same checks a new checkout runs
  • the cart is kept while that payment is pending, so a late webhook can still place the order

• Currency-aware checkout. Checkout only offers gateways that can take the cart's currency, and the server refuses the others.

• Return links keep reference_id. Redirects from /en-US/, /en-GB/, /account/... and /cart now forward the query string, so shoppers with a US or UK English browser no longer see "could not confirm" after paying.

• Webhook orders belong to the shopper. A gateway order placed by a webhook (which runs as Administrator) is owned by the cart's shopper, so it shows in their account. COD orders are unchanged.

commera_payment_gateways is a new hook, so the plugin reference needs a page for it.

Testing

• Whole Commera suite: 965 tests. 14 fail, and none come from this PR: freezegun isn't installed on this bench, two test_sdk carrier tests fail on develop too, and develop still has tests written for an older bwh_payments (test_payment_hooks, plus three refund and fee tests).
• With feat: add Braintree gateway bwh_payments#23, Settings → Payments lists all six gateways from get_gateways(), and PayPal and Braintree are the ones with reusable_checkout.
• On a site with feat: add PayPal gateway bwh_payments#7, a USD cart offers PayPal and the same cart in INR doesn't.
• PayPal Sandbox with a real webhook:
  • Paying creates the Sales Order, Sales Invoice and Payment Entry
  • The return page and the webhook arriving together still produce one order
  • With the browser closed after payment, the webhook alone places the order
  • A partial refund, then the balance, both go through

Dependency

Needs bwhtech/bwh_payments#7 (api.get_gateways() and PayPal). Braintree needs bwhtech/bwh_payments#23.

IMG_5680.MOV

[NagariaHussain]

No gateway specific code should go in commera, it should be a plugin, and commera should provide necessary hooks.

@Rl0007