Skip to main content
A vendor’s money goes through three states before reaching their payout destination.

​
The three balances

Every wallet carries three amounts, and their sum is what the account actually holds.
​
number
Credited, not yet matured. Every vendor credit lands here. Not payable, but seizable by a refund.
​
number
Available. This is the only amount that can be paid out.
​
number
Committed to a payout in flight. The money still belongs to the account, but it is reserved while the operator responds.
Do not confuse pending_balance and held_balance: “not yet matured” and “payout in progress” are two different states. Mixing them up produces no error. It simply falsifies your reconciliation.

​
The availability delay

A vendor credit carries an available_at date. At maturity, a sweep moves it from pending_balance to balance, and emits connect.funds.available. The default delay is 7 days.
The delay is not only an anti-fraud guard: it is the funding source for refunds. Pending funds are seizable; funds already paid out are not. Shortening the delay moves the refund risk onto your own balance.
You read the maturity date on the vendor’s account:

​
Pay out to a vendor

You are the one who orders the payout: a connected vendor has no dashboard.

​
Headers

​
Body

Empty. A Connect payout transfers the entire available balance.
amount is refused with a 422: there is no partial payout. The amount is the vendor’s balance at the moment of the lock.
201
The call is synchronous and waits for the operator. Expect several seconds. The status returned is the final state: succeeded or failed, never processing.An operator refusal returns 201 with status: "failed", not an HTTP error. Always read the status.
A connected vendor’s payout is free: no commission is taken on it. The destination is masked: you do not need to read your vendor’s number.

​
Preconditions

A payout is refused as long as any of these conditions is not met:
Otherwise 403 E_VERIFICATION_REQUIRED. It is the vendor’s policy that is evaluated, not yours.
Otherwise 422 E_CONNECT_VENDOR_PAYOUT_METHOD_UNAVAILABLE. It is collected during onboarding.
Otherwise 422 E_CONNECT_VENDOR_EMPTY_BALANCE. This is a nominal state (before the first allocation, or right after a payout), not an error to retry.
Otherwise 422 E_PENDING_WITHDRAW.

​
Replay

The replay contract differs from the other money routes. Within 24 h, replaying the same Idempotency-Key returns the same 201. Beyond that, you get 409 E_DUPLICATE_OPERATION: the service does not rebuild the original response.The same key on two different vendors does pay both: the key is scoped by endpoint and by vendor.

​
Automatic cadence

Rather than calling the route by hand, you can have your vendors paid automatically as soon as their balance is positive.
200
The read always returns 200, with cadence: null and enabled: false when nothing is configured. The write returns 200, not 201: the resource is your account, it already exists. Posting again simply replaces the configuration.
The cadence is the only way to guarantee your vendors a payment rhythm. In manual mode, they depend entirely on you to get paid.

​
Payout errors