Vendor payments

SyliusMarketplacePlugin pays vendors out of their ledger balance (see Settlement and the ledger), not per individual order. A VendorPayment represents one attempt to move that money to a vendor — it is produced either when a vendor requests a withdrawal, or when an admin pays a vendor's balance directly; it is not tied to any particular VendorOrder.

VendorPayment

A VendorPayment holds the vendor it pays, the amount/currencyCode being paid out, the method (the VendorPayoutMethod used) and a details array where the gateway can store its raw response — useful for troubleshooting.

VendorPayment state machine

Graph odiseo_marketplace_vendor_payment, places new/completed/failed/cancelled:

transitions:
    complete:
        from: [new]
        to: completed
    fail:
        from: [new]
        to: failed
    cancel:
        from: [new]
        to: cancelled

When a VendorPayment completes, a listener automatically posts a payout entry (debiting the amount) to the vendor's ledger, referencing the payment as its source.

How a VendorPayment is created

You will not normally create a VendorPayment by hand — it is built and executed by Odiseo\SyliusMarketplacePlugin\Payout\Withdrawal\WithdrawalPayoutExecutorInterface, which:

1. checks the withdrawal request (or admin-initiated payout) can still be paid,
2. re-validates the vendor's live ledger balance under a lock (so two concurrent payouts can't pay out the same funds twice),
3. creates the VendorPayment and calls the payout gateway,
4. applies complete (and posts the ledger debit) on success, or fail with the gateway's error recorded in details and reason otherwise.

Vendor Payout Methods

A VendorPayoutMethod represents a way to pay a vendor. It holds a reference to a gateway with its own configuration, configured per method using the payout method form in the seller panel.

<?php
$payoutMethod = $this->container->get('odiseo_marketplace.factory.vendor_payout_method')->createWithGateway('offline');

$this->container->get('odiseo_marketplace.repository.vendor_payout_method')->add($payoutMethod);

The executor pays through the vendor's getDefaultPayoutMethod(). Adding a new gateway (beyond the built-in offline/PayPal/Stripe ones) is covered in Payout gateways. Stripe, with Connect Express onboarding, is a separate subplugin — see Payments Pro.

Paying every vendor from the command line

To pay out the current balance of every vendor that has a positive balance (skipping the ones at zero), run:

php bin/console odiseo:marketplace:pay-all-payouts

This runs each vendor through the same withdrawal payout executor used by the admin "Pay" action, so it is safe to schedule periodically (e.g. via cron).

Troubleshooting

The gateway's raw response (or the failure reason) is stored in the details column of the odiseo_vendor_payment table — check it first when a payout doesn't behave as expected.