PayPal payouts

Install PayPal

Import the gateways

# config/services.yaml
imports:
    # ...
    - { resource: "@OdiseoSyliusMarketplacePlugin/config/services/payout/gateway/paypal.yaml" }

Follow the original PayPal documentation.

Add a payout method with the PayPal gateway in the Seller Panel

To test this configuration properly, you will need a developer account on PayPal

• Create a new payout method choosing the Paypal gateway from the gateways choice dropdown.
• Fill in the PayPal configuration form with your ID.
• Save the new payout method.

Detecting payouts that fail after being sent

PayPal Payouts is asynchronous: a successful API call only means the batch was accepted, not that the money was delivered. An item can still end up FAILED, RETURNED, BLOCKED or DENIED afterwards (e.g. the vendor's PayPal email isn't registered). Registering a webhook lets the plugin detect this and reverse the vendor's balance instead of silently overstating it as paid.

1. Import the webhook route, together with the gateway:

# config/routes.yaml
odiseo_sylius_marketplace_webhook:
    resource: "@OdiseoSyliusMarketplacePlugin/config/routing/webhook.yaml"

2. In your PayPal app dashboard, add a webhook pointing at https://your-domain.com/webhook/paypal/payout, subscribed to at least:

   • PAYMENT.PAYOUTS-ITEM.FAILED
   • PAYMENT.PAYOUTS-ITEM.RETURNED
   • PAYMENT.PAYOUTS-ITEM.BLOCKED
   • PAYMENT.PAYOUTS-ITEM.DENIED

3. Copy the webhook's ID into the marketplace Setting's PayPal Webhook ID field (Admin panel, Marketplace configuration). Until this is set, incoming webhook requests are rejected (fail closed) rather than trusted unverified.

Without this, a payout that PayPal accepted but later failed to deliver stays marked as paid in the vendor's ledger.