Registra un vendedor y verifica su cuenta de payout

Para marketplaces: registra un vendedor, confirma su destino de Pago Móvil con dos microdepósitos y define su comisión para dividir pagos y pagarle.

Qué vas a hacer

Un vendedor es alguien por quien tu marketplace cobra. En la API un vendedor es un merchant (/v1/merchants). Antes de pagarle a un vendedor, su destino de Pago Móvil debe verificarse con dos depósitos pequeños que el vendedor lee en su banco.

Una cuenta marketplace (VEXPay define el modelo de negocio; mira Vendedor o marketplace).
El nombre del vendedor, su cédula o RIF, email y teléfono de contacto, y el banco y teléfono de su Pago Móvil.
Un endpoint de webhook suscrito a merchant.verified y merchant.rejected.

Pasos

Registra al vendedor
POST /v1/merchants con tu propio id de vendedor como externalRef (único, y la clave de idempotencia), name, identification (V/E + 8 dígitos o J/G + 9 dígitos), contactEmail, contactPhone, y bankCode (4 dígitos) + phone (celular local de 11 dígitos, por ejemplo 04121234567) para su primer método de payout. Opcionalmente agrega applicationFeePercent (su comisión) y autoPayoutEnabled.
Inicia la verificación
POST /v1/merchants/:id/payout-methods/:methodId/verify/start. VEXPay envía dos depósitos de unos céntimos al Pago Móvil del vendedor.
El vendedor lee los dos montos
Pide al vendedor ambos montos de su estado de cuenta. Tiene 2 días.
Confirma los montos
POST /v1/merchants/:id/payout-methods/:methodId/verify con amount1 y amount2. Tienes 3 intentos.
Define la comisión (opcional)
Por vendedor con PATCH /v1/merchants/:id o la columna Commission en Portal → Merchants, o una predeterminada para todos en Portal → Merchants → Default commission.

Registrarbash

curl --request POST "${API_URL}/v1/merchants" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{
    "externalRef": "seller-881",
    "name": "Panadería La Esquina",
    "identification": "J123456789",
    "contactEmail": "ventas@laesquina.example",
    "contactPhone": "04121234567",
    "bankCode": "0102",
    "phone": "04121234567",
    "applicationFeePercent": 5
  }'

Confirmar microdepósitosbash

curl --request POST "${API_URL}/v1/merchants/MERCHANT_ID/payout-methods/METHOD_ID/verify" \
  --header "content-type: application/json" \
  --header "x-api-key: ${VEXPAY_API_KEY}" \
  --data '{ "amount1": "0.37", "amount2": "0.82" }'

Comprueba que funcionó

Recibiste merchant.verified para el vendedor.
GET /v1/merchants/:id/payout-methods muestra el método como verified.
El vendedor aparece activo en Portal → Merchants con la comisión que definiste.

Si algo sale mal

Síntoma	Causa probable	Qué hacer
422 `merchant_identification_missing`	El vendedor no tiene cédula/RIF registrada	Agrega `identification` con `PATCH /v1/merchants/:id`.
422 `credit_rejected` o `merchant.rejected`	El banco rechazó el destino (banco, teléfono o cédula no coinciden)	Revisa los datos con el vendedor y agrega un método corregido.
`amounts_mismatch` con `attemptsLeft`	Montos equivocados	Vuelve a leer el estado de cuenta. Tras 3 fallos el método queda bloqueado 24 horas.
410 `window_expired`	No se confirmó en 2 días	Inicia la verificación de nuevo.
409 `external_ref_conflict`	El mismo `externalRef` enviado con datos distintos	Usa el vendedor existente (`GET /v1/merchants?externalRef=…`) o un id nuevo.

Siguiente: Dividir pagos. Relacionado: Comerciantes y payouts · Liquidación marketplace