Reference · built on requestConnectorPayments, billing & fraud

PayPal

Orders, captures, refunds, subscriptions, invoices, and disputes from PayPal REST APIs and webhook events.

Request accessPricing ↗

About

PayPal's REST APIs cover checkout orders, authorizations and captures, refunds, subscriptions, invoices, payouts, and customer disputes. Each product publishes webhook events, named like PAYMENT.CAPTURE.COMPLETED or CUSTOMER.DISPUTE.CREATED, to up to ten listener URLs per app.

An operator on Fibric subscribes to those events, reads the order or dispute behind each one, and proposes an action: capture an approved order, refund a capture, take the next dunning step on a failed subscription payment, or provide evidence on a dispute. Nothing is sent until you approve. Each approved call is made once, with a record of what changed and how to reverse it.

This is a reference listing. It documents what Fibric would read from PayPal and what it could propose, based on the vendor's published interfaces. Fibric builds it under a managed deployment when you request it; selecting it here installs nothing.

Inputs

  • Order lifecycle events CHECKOUT.ORDER.APPROVED, CHECKOUT.ORDER.COMPLETED, and PAYMENT.AUTHORIZATION.CREATED
  • Capture and refund events: PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.REFUNDED, and PAYMENT.REFUND.FAILED
  • Dispute events CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.UPDATED, and CUSTOMER.DISPUTE.RESOLVED, plus dispute details from GET /v1/customer/disputes/{id}
  • Subscription events including BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.SUSPENDED, and BILLING.SUBSCRIPTION.PAYMENT.FAILED
  • Invoice events INVOICING.INVOICE.PAID, INVOICING.INVOICE.REFUNDED, and INVOICING.INVOICE.CANCELLED
  • Payout batch and item events such as PAYMENT.PAYOUTSBATCH.SUCCESS and PAYMENT.PAYOUTS-ITEM.RETURNED
  • Order detail from GET /v2/checkout/orders/{id} and capture detail from GET /v2/payments/captures/{capture_id}

Proposed actions

  • Target capability: propose capturing an approved order through POST /v2/checkout/orders/{id}/capture
  • Target capability: propose a refund of a capture through POST /v2/payments/captures/{capture_id}/refund
  • Target capability: propose voiding an authorization through POST /v2/payments/authorizations/{authorization_id}/void
  • Target capability: propose providing evidence, accepting a claim, or sending a message on a dispute through the Customer Disputes v1 API
  • Target capability: propose adding shipment tracking to an order through POST /v2/checkout/orders/{id}/track

Proposed actions are target capabilities. Every action runs propose-first and needs a validated deployment and the appropriate permissions.

What you can build

  • Answer a dispute with evidence

    CUSTOMER.DISPUTE.CREATED arrives. The operator reads the dispute reason and stage, collects the capture, shipment, and message history, and proposes an evidence package. After approval the connector submits it once through the Disputes API.

    With Chargeback Evidence

  • Take the next step on a failed subscription payment

    On BILLING.SUBSCRIPTION.PAYMENT.FAILED, the operator checks how many attempts have failed and proposes the next dunning step for approval, then records the decision against the subscription.

    With Payment Retry, Dunning Cadence

  • Match invoice payments to the ledger

    INVOICING.INVOICE.PAID events carry the invoice and amount. The operator matches each one to the open receivable in your accounting system and proposes the application entry.

    With Cash Application

  • Void instead of refund

    If an order is cancelled while the payment is still an authorization, the operator proposes a void rather than a capture followed by a refund the customer would have to wait for.

    With Cancellation Window

Requirements

  • A PayPal business account and a REST app created in the Developer Dashboard with a client ID and secret
  • Webhook subscriptions for the event names above, set in the Developer Dashboard or through the Webhooks Management API
  • An HTTPS listener that answers with a 2xx status; PayPal retries other responses
  • Separate sandbox and production credentials; sandbox calls go to api-m.sandbox.paypal.com
Authentication
OAuth 2.0 client credentials: the app's client ID and secret from the Developer Dashboard are exchanged at /v1/oauth2/token for a Bearer access token.

Limits

  • PayPal publishes no rate limit thresholds. Traffic that looks abusive gets HTTP 429 RATE_LIMIT_REACHED, so the connector caches access tokens and prefers webhooks to polling.
  • Webhook delivery is retried up to 25 times over 3 days, so events can arrive late and out of order.
  • Some dispute operations, such as settle and update status, exist only in sandbox.
  • An order can be updated with PATCH only while its status is CREATED or APPROVED.

Access and pricing

Reference listing. Fibric builds the connector under a managed deployment when you request it. Your quote covers the build, capabilities, usage, and support.

Request PayPal ↗

Questions and answers

How does PayPal confirm a webhook came from PayPal?
Two ways. Compute a CRC32 of the message and check its signature locally, or post the message, webhook ID, and transmission headers to PayPal's verify-webhook-signature endpoint. The connector discards events that fail the check.
How long does PayPal keep retrying a webhook?
PayPal reattempts delivery up to 25 times over 3 days or until it receives a 2xx code. After that the event is marked Failed and can be resent by hand from the Webhook Events dashboard.
Which refund path does the connector use?
Captured payments are refunded through POST /v2/payments/captures/{capture_id}/refund. Uncaptured authorizations are voided instead. The outcome arrives as PAYMENT.CAPTURE.REFUNDED, PAYMENT.REFUND.PENDING, or PAYMENT.REFUND.FAILED.
Ask about PayPal

Ask about the capabilities and requirements in this listing.

For project-specific requirements, contact Fibric.

This connector listing is developed, published, and supported by Fibric. It describes integration with PayPal through published interfaces. Third-party names and logos identify the systems an integration connects to; they are the property of their respective owners, who are not affiliated with Fibric and do not sponsor or endorse this listing. Trademark policy