Marketplace: wallets, splits and payouts

Wallets per seller, split rules on incoming funds, escrow holds, and bulk payouts.

Wallets

A wallet is a sub-account with an IBAN, a balance and a verified holder. Create one per seller after KYB.

curl https://api.neofin.tech/v1/wallets \
  -H "Authorization: Bearer $NEO_API_KEY" \
  -H "Idempotency-Key: 9a2c..." \
  -H "Content-Type: application/json" \
  -d '{ "currency": "EUR", "holder": { "type": "business", "legal_name": "Alder & Finch SARL", "kyb_id": "kyb_77AF" }, "external_ref": "seller_2210" }'

Split rules

A split rule describes how an incoming credit is divided. Rules can be attached to a checkout session, a wallet, or your whole programme.

{
  "name": "standard-8pct",
  "recipients": [
    { "wallet": "wa_PlatformRevenue", "percent": 8, "fixed": 50 },
    { "wallet": "{seller}", "remainder": true, "hold": { "until": "release" } }
  ]
}

Holds

Held funds are reserved on the seller wallet and cannot be paid out. Release on delivery, partially release for partial fulfilment, or reverse to return funds to the buyer.

curl -X POST https://api.neofin.tech/v1/holds/ho_1Kq7Zr/release \
  -H "Authorization: Bearer $NEO_API_KEY" \
  -H "Idempotency-Key: 1c9f..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 118000 }'

Holds have a maximum duration of 90 days. Set release_after to release automatically.

Payouts

Payouts go to verified beneficiaries. Create beneficiaries once per seller; the first payout to a new beneficiary triggers a name check against the wallet holder.

curl https://api.neofin.tech/v1/payout-batches \
  -H "Authorization: Bearer $NEO_API_KEY" \
  -H "Idempotency-Key: 4e8b..." \
  -H "Content-Type: application/json" \
  -d '{
    "payouts": [
      { "wallet": "wa_2Lp9Qk", "beneficiary": "be_3Rt1Xc", "amount": 118000, "currency": "EUR", "reference": "Payout w45" },
      { "wallet": "wa_5Mn3Yd", "beneficiary": "be_7Vw2Zq", "amount": 56200, "currency": "EUR", "reference": "Payout w45" }
    ]
  }'

Batches accept up to 5,000 payouts. Each payout emits payout.paid or payout.failed individually.

Negative balances

Refunds and reversals debit the seller wallet. Configure a floor per wallet: block (default) rejects movements that would breach it, net allows a negative balance to be recovered from future credits, and invoice emits an event for you to collect separately.