Divide un pago entre tu marketplace y un vendedor

Crea una sesión de checkout con `merchantId` y `applicationFeePercent`: te quedas con tu comisión, la parte del vendedor llega a su saldo y le pagas cuando se libera.

Qué vas a hacer

Marca un checkout con un vendedor y VEXPay lo divide cuando se paga: tu comisión queda en tu saldo y la parte del vendedor va al saldo propio del vendedor, lista para pagarle después de la retención.

Una cuenta marketplace con métodos en bolívares habilitados (los checkouts divididos aceptan solo tarjeta, Débito Inmediato y Pago Móvil).
Un vendedor activo con un método de payout verificado (mira Registrar un vendedor).

Pasos

Crea una sesión de checkout dividida
POST /v1/checkout/sessions con amountUsd, merchantId (el vendedor) y opcionalmente applicationFeePercent (0–100, hasta 4 decimales). Sin él, VEXPay usa la comisión del vendedor, luego tu comisión predeterminada, y si no, ninguna.
Envíale la url al comprador
El checkout muestra el nombre del vendedor, porque el comprador le está pagando al vendedor.
VEXPay divide al completarse
Cuando el pago se completa, tu comisión queda en tu saldo y el neto del vendedor va a su saldo pendiente. Recibes payment.completed y merchant.balance.updated.
Espera la liberación
El dinero pendiente del vendedor pasa a disponible después de lo último entre la retención del vendedor y tu retención de saldo de 24 horas.
Págale al vendedor
POST /v1/payouts con merchantId, el monto exacto en bolívares, concepto, un externalRef único y fromMerchantBalance: true. O activa autoPayoutEnabled para el vendedor.

Checkout divididobash

curl --request POST "${API_URL}/v1/checkout/sessions" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "amountUsd": 40.00,
    "description": "Pedido #7781",
    "reference": "order-7781",
    "merchantId": "MERCHANT_ID",
    "applicationFeePercent": 5
  }'

Pagarle al vendedorbash

curl --request POST "${API_URL}/v1/payouts" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "merchantId": "MERCHANT_ID",
    "monto": "1200.00",
    "concepto": "Ventas semana 44",
    "externalRef": "seller-881-w44",
    "fromMerchantBalance": true
  }'

Comprueba que funcionó

GET /v1/checkout/sessions/:id muestra status: "paid" y devuelve merchantId y applicationFeePercent.
GET /v1/merchants/:id/balance muestra el neto del vendedor en pendingVes y después en availableVes.
Después del payout llega payout.completed y el saldo disponible del vendedor baja en monto.

Si algo sale mal

Síntoma	Causa probable	Qué hacer
400 en una sesión con `usdt`, `usdc` o `cop` y `merchantId`	Los checkouts divididos aceptan solo métodos en bolívares	Quita esos métodos, o quita `merchantId`.
400 "merchantId is required when setting an application fee"	Comisión enviada sin vendedor	Agrega `merchantId`.
400 `merchantId not found or inactive for this tenant`	Id equivocado, vendedor de otra cuenta, o vendedor desactivado	Revisa `GET /v1/merchants/:id`; reactívalo con `PATCH /v1/merchants/:id`.
No se acreditó el saldo del vendedor	El pago no tenía `merchantId`, o comisión + tarifa ≥ monto	Revisa el pago; baja la comisión.
422 `insufficient_merchant_balance` en el payout	El dinero del vendedor sigue pendiente, o ya se pagó	Espera la liberación; revisa `GET /v1/merchants/:id/balance`.
Payout en estado `awaiting_approval`	En sus primeros 30 días una cuenta puede retirar hasta USD 300 en cualquier período de 24 horas (salvo que VEXPay te haya fijado otro límite); este payout lo superó	No hace falta hacer nada; VEXPay lo revisa y lo envía o devuelve los fondos.

Relacionado: Liquidación marketplace · Receta: marketplace · Comerciantes y payouts