Marketplace · Extension
PayPal
Connect PayPal Checkout Orders and vaulted recurring payments to Agovena.
About this package
What it does
PayPal is exposed as one checkout option with the official extension-owned PayPal SVG icon. Storefront checkout opens PayPal's official JS SDK popup overlay; the SDK owns approval and Agovena returns the buyer to status handling after onApprove, onCancel or onError. Signed webhooks remain authoritative. Automatic recurring checkout stores a Vault authorization during the first Orders v2 payment and Core performs later renewal orders with vault_id and stored_credential. No Billing Plan ID is required.
The extension supports full and partial capture refunds for initial and recurring Orders v2 payments. It persists provider capture references, validates amount and currency when available, preserves PayPal idempotency keys, revokes deleted vault authorizations, and defers unknown provider outcomes to reconciliation. No pre-created Billing Plan is required.
Requirements
Agovena Core ^0.0.1. Configure a PayPal application, a registered webhook and the matching Sandbox or live environment. Provider account approval, webhook delivery and live transaction processing remain deployment responsibilities.
Local adapter, API contract and lifecycle tests cover the implementation. Live PayPal checkout, webhook delivery, refund execution, recurring renewal and merchant approval remain deployment verification steps and are not claimed as executed.
Set up the package
Configure client_id, secret client_secret and webhook_id from the same PayPal application and environment. sandbox defaults to true. Register the Agovena payment webhook URL in that application. A webhook ID identifies the registered endpoint; it is not the client secret or a locally invented signing key.
Enable the subscribable product capability for automatic renewals. The first checkout requests a merchant vault authorization. Later renewals use the encrypted authorization stored by the PayPal extension. There is no subscription_plan_id or product-level PayPal plan setting.
Operation and failure handling
Webhook verification uses PayPal's verify-webhook-signature operation and accepts only PayPal HTTPS certificate hosts. A verified approval event captures before Agovena marks the payment paid. A recurring authorization is stored only when the capture returns a successful vault result.
Refunds use Orders capture IDs for both initial and recurring payments. PAYMENT.CAPTURE.REFUND.* updates the Agovena refund record. Vault deletion events revoke the local authorization. A redirect is not payment proof. Amount or currency mismatches, invalid provider references, failed refunds and unknown transport outcomes do not become successful records automatically.