Provider guides
PayPal: configuration and operations
Connect PayPal Checkout Orders and vaulted recurring payments to Agovena.
On this page
Provider workflow
PayPal is exposed as one checkout option with the extension-owned official PayPal SVG icon. Storefront orders open PayPal's official JS SDK popup overlay. The SDK owns approval and the buyer-facing payment surface; Agovena receives onApprove, onCancel and onError callbacks and returns the buyer to the payment-status page. The callback is not treated as payment proof. Agovena's signed webhook and reconciliation flow remains authoritative, and non-storefront/API clients retain the direct PayPal approval redirect.
One-time orders use PayPal Checkout Orders v2. Automatic recurring products use PayPal Vault through the same Orders v2 checkout. The first approved capture requests store_in_vault = ON_SUCCESS. Agovena stores the resulting provider token encrypted and executes later renewal orders with vault_id and stored_credential. Renewal scheduling remains in Agovena Core. No pre-created PayPal Billing Plan is required.
Refunds support full and partial capture refunds, including recurring charges. The adapter stores the provider capture reference before allowing a refund. Refund pending, failed, duplicate and unknown outcomes remain tied to the Agovena refund record for reconciliation.
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 require deployment verification and are not claimed here 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.
Create a subscribable product capability for automatic renewals. The first automatic 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.
Provider-specific boundaries
Use https://shop.example.com/webhooks/payments/paypal for the endpoint, substituting your deployment hostname. Preserve PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG and PAYPAL-TRANSMISSION-TIME. The adapter accepts only HTTPS PayPal API certificate hosts and asks PayPal to verify the complete event.
Supported payment events include CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.*, PAYMENT.SALE.* and PayPal Vault token events. Capture payloads are checked against the Agovena payment amount and currency where PayPal supplies them. Vault deletion events revoke the local reusable authorization. Unknown event outcomes are not converted into Paid, Refunded or Failed automatically.
Configuration contract
| Field | Type | Required | Secret | Default |
|---|---|---|---|---|
client_id |
string |
Yes | No | Empty |
client_secret |
string |
Yes | Yes | Empty |
webhook_id |
string |
Yes | No | Empty |
sandbox |
boolean |
No | No | true |
Operation and failure handling
A provider redirect is not payment proof. Payment becomes Paid only after a verified and amount-compatible PayPal event. A recurring authorization is not stored until PayPal returns a successful vault result with the capture.
Refunds use capture IDs for both initial and recurring Orders v2 payments. PayPal-mutating requests carry Agovena's idempotency key as PayPal-Request-Id. A transport error or malformed provider response leaves the payment or refund in reconciliation instead of retrying blindly.
Configure the webhook separately for Sandbox and live. Do not publish client secrets, webhook data, authorization headers, vault IDs or buyer payment data.