Marketplaces

Marketplaces permite a comercios que operan como intermediarios entre compradores y vendedores procesar pagos y liquidar fondos a los vendedores de forma automática y segura.

Autenticación y aislamiento

Usá una Secret API Key de la cuenta primaria estándar que administra el marketplace:

Authorization: Bearer <TU_SECRET_API_KEY>

La llave determina la cuenta primaria y el modo test o live de forma inmutable. Las Publishable API Keys no están permitidas para estas operaciones.

Todas las lecturas y mutaciones validan el ID de la cuenta conectada junto con la cuenta primaria, el modo y el tipo de cuenta. Un ID inexistente, de otra cuenta primaria o de otro modo retorna el mismo error 404 sin revelar si el recurso existe.

Las cuentas conectadas no reciben API keys propias. Para cobrar en nombre del vendedor, seguí usando la llave de la cuenta primaria y enviá el ID de la cuenta conectada en onBehalfOf.

Crear una cuenta conectada

Podés crear la cuenta desde la sección Marketplace del Dashboard de ONVO o mediante POST /v1/connected-accounts.

curl https://api.onvopay.com/v1/connected-accounts \
  -X POST \
  -H "Authorization: Bearer <TU_SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Tienda Conectada",
    "marketplaceAppFee": 5
  }'

businessName es obligatorio, se recorta y admite entre 1 y 50 caracteres. marketplaceAppFee es un porcentaje opcional entre 0 y 100 con un máximo de dos decimales. Por ejemplo, 5 representa un 5 %. Si lo omitís, ONVO guarda y retorna 0.

La creación retorna HTTP 201:

{
  "id": "cl502zv0d0127ebdp3zt27651",
  "mode": "test",
  "status": "pending_onboarding",
  "businessName": "Tienda Conectada",
  "marketplaceAppFee": 5,
  "createdAt": "2026-07-25T17:00:00.000Z",
  "onboardingUrl": "https://onvopay.com/setup/account_onboarding_test_example"
}

onboardingUrl solo se retorna al crear la cuenta o regenerar el enlace. Tratá este valor como sensible: entregáselo al vendedor correcto y no lo registrés en logs.

Listar, obtener y actualizar

Listá las cuentas del modo autenticado con GET /v1/connected-accounts. limit admite de 1 a 100 y usa 10 por defecto. startingAfter y endingBefore son mutuamente excluyentes, y el cursor debe pertenecer a la misma cuenta primaria, modo y filtro.

Podés filtrar por pending_onboarding, awaiting_approval, active, inactive, temporally_suspended, permanently_suspended o deleted. El valor restricted no forma parte del contrato de Secret API Key.

curl "https://api.onvopay.com/v1/connected-accounts?status=pending_onboarding&limit=10" \
  -H "Authorization: Bearer <TU_SECRET_API_KEY>"

El listado retorna el mismo objeto público dentro del envelope { data, meta }:

{
  "data": [
    {
      "id": "cl502zv0d0127ebdp3zt27651",
      "mode": "test",
      "status": "pending_onboarding",
      "businessName": "Tienda Conectada",
      "marketplaceAppFee": 5,
      "createdAt": "2026-07-25T17:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "pages": 1,
    "limit": 10,
    "cursorNext": "cl502zv0d0127ebdp3zt27651",
    "cursorBefore": "cl502zv0d0127ebdp3zt27651"
  }
}

GET /v1/connected-accounts/{id} retorna exactamente el mismo objeto público. En cuentas antiguas sin perfil comercial, businessName puede ser null; si falta la configuración de comisión, marketplaceAppFee retorna 0.

Actualizá businessName, marketplaceAppFee o ambos con POST /v1/connected-accounts/{id}. Debés enviar al menos uno:

curl https://api.onvopay.com/v1/connected-accounts/cl502zv0d0127ebdp3zt27651 \
  -X POST \
  -H "Authorization: Bearer <TU_SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Tienda Conectada Actualizada",
    "marketplaceAppFee": 6.25
  }'

Este endpoint genérico no permite modificar el estado, onboarding, frecuencia de liquidación, tarifas semanales, datos bancarios ni configuración de procesadores. Las respuestas de listado, consulta y actualización nunca incluyen onboardingUrl.

Configurar una tarifa semanal

Creá o actualizá la tarifa fija semanal con POST /v1/connected-accounts/{id}/weekly-fees. Enviá al menos uno de los campos marketplaceWeeklyFeeEnabled, marketplaceWeeklyFeeAmount o marketplaceWeeklyFeeCurrency:

curl https://api.onvopay.com/v1/connected-accounts/cl502zv0d0127ebdp3zt27651/weekly-fees \
  -X POST \
  -H "Authorization: Bearer <TU_SECRET_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "marketplaceWeeklyFeeEnabled": true,
    "marketplaceWeeklyFeeAmount": 1000,
    "marketplaceWeeklyFeeCurrency": "CRC"
  }'

marketplaceWeeklyFeeAmount es un entero expresado en la unidad menor de la moneda, entre 1 y 2147483647. La tarifa semanal está disponible para cuentas conectadas en Costa Rica, Guatemala y Perú. Las monedas soportadas son USD, CRC para Costa Rica, GTQ para Guatemala y PEN para Perú.

Para activar la tarifa, la configuración efectiva debe tener monto y moneda. Además, la cuenta primaria y la cuenta conectada deben tener una cuenta bancaria de liquidación en esa misma moneda. Podés guardar monto y moneda con la tarifa deshabilitada antes de cumplir esos requisitos; para desactivarla después, enviá marketplaceWeeklyFeeEnabled: false.

Los valores null no están permitidos. Si querés conservar el valor actual de un campo, omitilo del payload. Cada solicitud se aplica de forma atómica: la primera crea la configuración y las siguientes actualizan únicamente los valores enviados.

La respuesta retorna únicamente la configuración pública:

{
  "id": "cl502zv0d0127ebdp3zt27651",
  "marketplaceWeeklyFeeEnabled": true,
  "marketplaceWeeklyFeeAmount": 1000,
  "marketplaceWeeklyFeeCurrency": "CRC"
}

Corte y cobro

La tarifa fija semanal es independiente de marketplaceAppFee: se genera una vez por semana y no por cada pago.

Cada viernes a las 02:00 en America/Costa_Rica, ONVO toma la configuración vigente. Si la tarifa está habilitada y la cuenta conectada está active, crea la obligación completa en la moneda configurada. Un cambio realizado después del corte aplica al viernes siguiente. Si la cuenta conectada no está active en el corte, ONVO no genera la tarifa de esa semana.

Deshabilitar la tarifa antes del corte evita una nueva obligación, pero deshabilitarla no elimina obligaciones pendientes. ONVO las descuenta de las liquidaciones futuras en la misma moneda, después de las demás deducciones, y conserva al menos 100 unidades menores en la liquidación. Si no alcanza el saldo, cobra parcialmente y mantiene el remanente para liquidaciones futuras, atendiendo las obligaciones más antiguas primero.

ONVO acredita a la cuenta primaria únicamente el monto cobrado cuando la liquidación queda paid. Si una liquidación pagada se revierte, ONVO revierte el crédito correspondiente y reabre el saldo de la obligación. Los modos test y live se procesan por separado.

La referencia de configuración de tarifa semanal incluye payloads completos para valores null, monto inválido, configuración incompleta, moneda no soportada, cuentas bancarias faltantes, función no habilitada y cuenta conectada no encontrada.

Onboarding de vendedores

El vendedor debe completar el onboarding alojado por ONVO para poder recibir pagos. Durante este proceso, indica las cuentas IBAN donde recibirá liquidaciones.

El enlace expira después de 7 días. Podés regenerarlo desde el Dashboard o mediante POST /v1/connected-accounts/{id}/onboarding-link; al hacerlo, el enlace anterior queda expirado:

curl https://api.onvopay.com/v1/connected-accounts/cl502zv0d0127ebdp3zt27651/onboarding-link \
  -X POST \
  -H "Authorization: Bearer <TU_SECRET_API_KEY>"

{
  "id": "cl502zv0d0127ebdp3zt27651",
  "onboardingUrl": "https://onvopay.com/setup/account_onboarding_test_example"
}

La regeneración solo está disponible antes de completar el onboarding. Si la cuenta ya está activa, ONVO retorna 409 con marketplaces.onboarding_already_completed.

Cuando el onboarding se completa, la cuenta conectada queda habilitada para aceptar pagos en su nombre.

Errores

Los errores de dominio de Marketplaces usan un payload tipado con statusCode, type, code, message, path y timestamp; los errores de validación y autenticación usan sus propios payloads. Las referencias de POST /v1/connected-accounts, GET /v1/connected-accounts, POST /v1/connected-accounts/{id} y POST /v1/connected-accounts/{id}/weekly-fees muestran los casos 400 y 401. GET /v1/connected-accounts/{id} muestra el error 404, mientras que POST /v1/connected-accounts/{id}/onboarding-link incluye los errores específicos 409 y 500.

Este es un payload completo de ejemplo para un error de dominio:

{
  "statusCode": 404,
  "type": "OnvoAPIError",
  "code": "marketplaces.connected_account_not_found",
  "message": "The connected account was not found",
  "path": "/v1/connected-accounts/cl502zv0d0127ebdp3zt27651",
  "timestamp": "2026-07-25T17:00:00.000Z"
}

Manejá al menos estos casos:

HTTP	Código estable	Significado
`400`	`marketplaces.parent_configuration_invalid`	La cuenta primaria no tiene la configuración requerida.
`400`	`marketplaces.invalid_cursor`	El cursor es inválido, ajeno o no coincide con el filtro.
`400`	`marketplaces.invalid_status`	El filtro de estado no está soportado.
`400`	`marketplaces.unsupported_public_field`	El payload incluye un campo fuera del contrato público.
`400`	`marketplaces.weekly_fee.configuration_required`	No se envió ningún campo de configuración semanal.
`400`	`marketplaces.weekly_fee.feature_disabled`	La función no está habilitada para la cuenta primaria.
`400`	`marketplaces.weekly_fee.amount_required`	Falta el monto efectivo al activar la tarifa.
`400`	`marketplaces.weekly_fee.currency_required`	Falta la moneda efectiva al activar la tarifa.
`400`	`marketplaces.weekly_fee.currency_not_supported`	La moneda no está soportada para el país de la cuenta conectada.
`400`	`marketplaces.weekly_fee.child_bank_account_required`	La cuenta conectada no tiene una cuenta bancaria en la moneda configurada.
`400`	`marketplaces.weekly_fee.parent_bank_account_required`	La cuenta primaria no tiene una cuenta bancaria en la moneda configurada.
`401`	—	La llave es inválida, es publishable o una llave live pertenece a una cuenta primaria inactiva.
`404`	`marketplaces.connected_account_not_found`	El ID no pertenece a la cuenta primaria y modo autenticados.
`409`	`marketplaces.onboarding_already_completed`	La cuenta ya completó el onboarding.
`500`	`marketplaces.error_creating_onboarding_link`	No se pudo persistir el enlace; no quedan escrituras parciales.

Flujo de pago

Usá siempre las API keys de la cuenta primaria, es decir, la cuenta que creó el marketplace.

Los métodos de pago, clientes, productos y precios también deben crearse en la cuenta primaria. Enviá onBehalfOf con el Account ID del vendedor cuando el cobro debe pertenecer a una cuenta marketplace.

Podés usar marketplace con intenciones de pago, sesiones de Checkout de un solo uso y cargos recurrentes.

Intenciones de pago

Creá una intención de pago con el atributo onBehalfOf, usando el id retornado al crear la cuenta conectada.

{
  "amount": 10000,
  "currency": "USD",
  "onBehalfOf": "cl502zv0d0127ebdp3zt27651"
}

Confirmá la intención de pago con el paymentMethodId retornado al crear el método de pago en la cuenta primaria.

{
  "paymentMethodId": "cl502zv0d0127ebdp3zt27652"
}

Sesiones de Checkout

Creá la sesión de Checkout con onBehalfOf. ONVO guarda esa cuenta en la sesión y la usa en la intención de pago generada para el cobro.

{
  "redirectUrl": "https://example.com/success",
  "cancelUrl": "https://example.com/cancel",
  "onBehalfOf": "ma502zv0d0127ebdp3zt27651",
  "lineItems": [
    {
      "quantity": 1,
      "unitAmount": 10000,
      "currency": "USD",
      "description": "Orden #1001"
    }
  ]
}

Cargos recurrentes

Creá el cargo recurrente con onBehalfOf. ONVO usa esa cuenta marketplace en la intención de pago del primer período y en las renovaciones futuras.

{
  "customerId": "cus502zv0d0127ebdp3zt27651",
  "paymentMethodId": "pm502zv0d0127ebdp3zt27651",
  "description": "Plan Pro mensual",
  "onBehalfOf": "ma502zv0d0127ebdp3zt27651",
  "items": [
    {
      "priceId": "price502zv0d0127ebdp3zt27651",
      "quantity": 1
    }
  ]
}

Las listas de sesiones de Checkout y cargos recurrentes también pueden filtrarse por vendedor con el header onvo-on-behalf-of.

Si el cobro es exitoso, ONVO calcula comisiones, retenciones y comisión marketplace sobre el monto bruto.

Después podés obtener una intención de pago por ID o listar las intenciones de pago de la cuenta.

Ejemplo para una transacción de 100.00 USD:

Concepto	Monto
Monto bruto	`100.00 USD`
Comisión ONVO 3.5%	`3.50 USD`
Retención 2%	`2.00 USD`
Monto neto	`94.50 USD`
Comisión marketplace 5%	`5.00 USD`
Monto a liquidar al vendedor	`89.50 USD`

La comisión marketplace se deposita en la cuenta primaria y el monto neto se deposita al vendedor.

Modo de prueba y producción

Podés crear cuentas conectadas en modo de prueba o producción según la Secret API Key o el modo activo del Dashboard.

Las cuentas creadas en modo de prueba solo funcionan con llaves de prueba. Las cuentas creadas en modo producción solo funcionan con llaves live. No se puede cambiar el modo de una cuenta una vez creada.

Autenticación y aislamiento​

Crear una cuenta conectada​

Listar, obtener y actualizar​

Configurar una tarifa semanal​

Corte y cobro​

Onboarding de vendedores​

Errores​

Flujo de pago​

Intenciones de pago​

Sesiones de Checkout​

Cargos recurrentes​

Modo de prueba y producción​