nestonexStart a project How do you stop a marketplace payout from failing after the work is already done?
Check eligibility before you promise anything. A payment provider only permits transfers to accounts whose onboarding and verification are complete, so checking that at dispatch moves the failure back to onboarding, where the person can still fix it rather than chase a payment that is never coming.
Because payout is the last step. A rider completes a delivery, the order closes, the money is owed, and only then does the transfer get attempted and rejected because their account was never fully verified.
Now you have someone who has done the work and cannot be paid, a support conversation, and a fix that requires them to go back through onboarding they thought they had finished. The engineering problem is small; the trust problem is not.
Payment providers expose the account's own view of whether it can transact: whether charges are enabled, whether payouts are enabled, and what outstanding requirements remain before they are.
Those requirements change over time. An account that was fine last month can move back into a restricted state when a verification document expires or a threshold is crossed, so eligibility is a current fact to be read, not a flag to be stored once at signup.
In two places. At dispatch, so no transfer is attempted against an account that cannot receive it. And at onboarding, so someone who is not yet eligible is told while they are still in the flow and motivated to finish.
The second is what actually prevents the problem. The first only stops it from becoming a failed API call.
Verification does not resolve on your schedule. Documents get reviewed, accounts move between states, and the provider tells you by webhook rather than at a moment convenient to your request cycle.
So payout state has to be durable and event-driven: record what was attempted, listen for the confirmation, and reconcile. Treating a transfer as complete because the API accepted it is a common way to end up with a ledger that disagrees with reality.
Our food delivery backend serves diners, restaurants and riders from one API with three separate auth surfaces, and riders are onboarded as connected accounts.
Transfers are gated on eligibility so the check happens before the promise, and payout confirmations arrive by webhook and are recorded against the order. Each audience has its own notification model, so a rider hears about their payment and a diner does not.
A payment account created for a vendor or contractor inside a platform's payment provider, owned by them but administered through the platform. It lets funds reach them directly rather than passing through the platform's balance, which moves most of the compliance burden to the provider.
Most often because the recipient's onboarding is incomplete or has lapsed. Verification documents expire, thresholds trigger new requirements, and an account that could receive money last month may not today. Eligibility is a current state to read, not a flag to store at signup.
Holding is usually worse than not promising. The better pattern is to surface eligibility during onboarding so the vendor completes verification before earning, rather than accruing a balance they then cannot withdraw and have to raise a support ticket about.
By webhook rather than by polling at checkout. Verification resolves asynchronously on the provider's schedule, so payout state needs to be durable and event-driven: record the attempt, listen for confirmation, reconcile against the order.