PayPal

Adapter 0.1.0, documentation reviewed 2026-10-25. Overall status: limited.

Capabilities

Error decoding	supported
API response parsing	supported
Webhook / notification parsing	limited
Timeline	limited
Event correlation	limited
Diagnostic rules	limited

Supported input

Format	Description	Status
`paypal.api_error`	Orders v2 and Payments v2 REST error responses (name, message, debug_id, details[].issue)	supported
`paypal.order`	Orders v2 order resources, with captures, authorizations and refunds per purchase unit	supported
`paypal.payment_resource`	Payments v2 capture, authorization and refund resources	supported
`paypal.webhook`	Webhook event envelopes for CHECKOUT.ORDER., CHECKOUT.PAYMENT-APPROVAL. and PAYMENT.* (v2)	limited
`paypal.webhook.verify_request`	verify-webhook-signature request bodies (the embedded webhook_event is analyzed; signature data is ignored)	limited
`paypal.webhook.subscription`	Subscription webhooks (BILLING.SUBSCRIPTION.*)	unsupported
`paypal.oauth_error`	OAuth token errors ({ error, error_description })	unsupported

Notification delivery

Repeated deliveries are recognized by webhook event id.
Delivery order: not documented by the provider.
Deduplicate on the webhook event id (WH-...) before acting. PayPal retries a delivery that did not get a 2xx response up to 25 times over 3 days, and deliveries can be resent manually.

Known limitations

An order with status COMPLETED is not treated as paid: the payment outcome comes from purchase_units[].payments.captures[].status, authorizations or PAYMENT.* events.
Order approval (APPROVED, CHECKOUT.ORDER.APPROVED) is shown as pending: no money has moved until a capture.
Webhook ordering and duplicate delivery are not documented by PayPal; duplicates are recognized by the event id only.
The resource shape of CHECKOUT.ORDER.* webhooks has no official sample: only the order id, status and amount are used, and embedded payments are not expanded.
Whether PAYMENT.CAPTURE.REFUNDED and PAYMENT.CAPTURE.REVERSED carry a refund or a capture resource is not documented; the resource kind is inferred from its fields.
PAYMENT.CAPTURE.DECLINED and PAYMENT.CAPTURE.DENIED are both treated as capture failures, because PayPal's documentation uses both names.
resource_type values other than capture are not documented and are not used.
A refund is linked to its capture through supplementary_data.related_ids.capture_id or the rel=up link; PayPal publishes no sample of this linkage.
Merchant references (invoice_id, custom_id, reference_id) are not used for correlation and are not copied, because they can be reused and may contain personal data.
Category and retry guidance are PandaPayLens proposals; PayPal publishes none. Unknown issue names are reported as unknown.
processor_response.response_code meanings are one-word tokens; their categories are inferred. payment_advice_code depends on the card network and is shown without interpretation.
When an error has several details[] entries, the first issue is decoded; PayPal does not document an order or priority.
Webhook signatures cannot be verified offline; a pasted payload is never proof that it came from PayPal.
Subscriptions (BILLING.SUBSCRIPTION.*) and OAuth token errors are recognized but not analyzed. Disputes, payouts, legacy v1 payments and NVP/SOAP are not supported; their events appear as unknown event types.

Examples

PayPal: order completed, capture declined: An order with status COMPLETED whose capture was declined. The order status is not the payment outcome.
PayPal: INSTRUMENT_DECLINED: An Orders v2 error with a details[].issue value.
PayPal: order and capture webhooks: Webhook events for one order, correlated through related_ids.

Provider documentation

PandaPayLens is not affiliated with PayPal. Pasted notifications are never treated as verified: PandaPayLens does not check webhook signatures.