Payouts
Control when sub-merchants are paid — managed schedules, on-demand payouts, instant payouts, and cross-border transfers.
A payout moves funds from a sub-merchant's balance account to their external bank account (or debit card). Your platform controls payout timing.
Payout schedulesAsk
Managed (platform-controlled)
The platform sets the payout schedule for each sub-merchant. Sub-merchants cannot change it themselves unless you explicitly grant them that permission.
POST /v1/platform/sub-merchants/{id}/payout-schedule
{
"interval": "weekly",
"anchor_day": "friday",
"delay_days": 2
}Supported intervals: daily, weekly, monthly, manual.
delay_days adds a rolling hold after each settlement day — useful for building in a dispute window before funds leave the platform.
Sub-merchant-controlled
Grant the sub-merchant permission to manage their own schedule:
POST /v1/platform/sub-merchants/{id}/payout-schedule
{
"interval": "sub_merchant_managed"
}On-demand payoutsAsk
Trigger a payout immediately regardless of the standing schedule:
POST /v1/platform/sub-merchants/{id}/payouts
{
"amount": 25000,
"currency": "USD",
"bank_account_id": "ba_ext_..."
}Omit amount to pay out the full available balance. On-demand payouts are useful for milestone payments, accelerated settlement after a successful event, or correcting a missed scheduled payout.
Instant payoutsAsk
For sub-merchants with an eligible debit card or instant bank account on file, VINR can deliver funds within ~30 minutes. A small per-payout fee applies.
POST /v1/platform/sub-merchants/{id}/payouts
{
"amount": 10000,
"currency": "USD",
"destination": "card_...",
"method": "instant"
}Check eligibility before offering instant payouts in your UI:
GET /v1/platform/sub-merchants/{id}/payout-eligibility?method=instantPayout lifecycleAsk
pending → in_transit → paid
↓
failed → retry or manual reissue| Status | Meaning |
|---|---|
pending | Payout queued; waiting for next settlement window |
in_transit | Bank transfer initiated |
paid | Funds delivered |
failed | Bank rejected the transfer (invalid account, closed account, etc.) |
canceled | Payout was canceled before it left the platform |
Failure handling
On failure, VINR fires sub_merchant.payout.failed with a failure_code. The funds are returned to the sub-merchant's balance account. Common failure codes:
| Code | Cause |
|---|---|
account_closed | Bank account no longer active |
invalid_account_number | Account details incorrect |
insufficient_funds | Balance account had insufficient settled funds |
no_account | Routing + account number combination not found |
After a failure, VINR disables the failing external account and the sub-merchant must add a new one before payouts resume.
Cross-border payoutsAsk
Pay sub-merchants in their local currency from a different settlement currency. Supported for qualifying platforms.
- VINR performs FX conversion at the mid-market rate plus a conversion margin
- The FX rate is locked at payout initiation
- Sub-merchant receives local currency; your platform's balance account is debited in settlement currency
POST /v1/platform/sub-merchants/{id}/payouts
{
"amount": 100000,
"currency": "USD",
"destination_currency": "EUR"
}Payout reportsAsk
Pull a structured report of all sub-merchant payouts for reconciliation:
GET /v1/platform/payouts?from=2025-01-01&to=2025-01-31&format=csvFields: payout ID, sub-merchant ID, amount, currency, status, initiated at, completed at, failure code.
Next stepsAsk
- Fund management — reserves and balance account controls
- Platform controls — restrict payout access by sub-merchant capability
