Si tu empresa ofrece cobros online o logística, integrar una pasarela de pago o un servicio de envíos en Commercy es una de las formas de llegar a los comercios que usan la plataforma. Desde el 25 de octubre de 2026, Commercy abre su marketplace de apps de terceros, y los cobros y los envíos son dos tipos de app con su propio contrato técnico, documentado públicamente. Esta guía explica cómo funciona cada uno, qué tiene que resolver tu servicio, cuál es el modelo comercial y cómo se compara, con datos oficiales a octubre de 2026, con el programa de socios de Tiendanube.
Cómo integrar una pasarela de pago en Commercy
Una app de cobro permite que un comercio cobre en el checkout de su tienda online con tu servicio: el comprador elige tu medio de pago, Commercy lo manda a tu página de cobro y, cuando pagó, tu app avisa. La integración es HTTP en los dos sentidos y no guardamos las credenciales de tu procesador: tu app identifica al comercio por la instalación y resuelve su cuenta en tu propio proceso de alta.
El flujo de cobro
- Commercy abre la sesión. Cuando el comprador confirma, creamos la venta y llamamos a
POST <apiBaseUrl>/commercy/payments/sessioncon el monto, la moneda (siempre ARS), los ítems y unidempotency_keyque es el id de la venta. Tenés 8 segundos para responder. - Respondés con la sesión. Devolvés un
payment_idy uncheckout_url:
{ "payment_id": "pay_8f3a21", "checkout_url": "https://pagos.tuapp.com/checkout/pay_8f3a21" }
El checkout_url tiene que ser https y compartir el dominio registrable de la URL de tu app. Si la respuesta no cumple las reglas, la venta se cancela y el comprador ve que no se pudo iniciar el pago.
- El comprador paga en tu página y vuelve a la tienda por el
back_url. - Tu app avisa con un webhook
payment.updateda/api/v1/app-webhooks/<installation_id>. El webhook solo dice qué sesión cambió; el estado lo consulta Commercy a tu ruta/status. - Commercy concilia. Llama a
POST <apiBaseUrl>/commercy/payments/status(5 segundos de tope) y compara: elpayment_idy elorder_idtienen que corresponder a la venta, y para aprobar, el monto tiene que ser igual al total y la moneda, ARS.
{ "payment_id": "pay_8f3a21", "order_id": "6710d1e0e4a1f20012ab3600", "status": "approved", "amount": 25000, "currency": "ARS" }
Firma, vencimiento y estados
Todos los requests de Commercy van firmados con HMAC-SHA256 sobre <timestamp>.<cuerpo crudo> y tu webhook se firma igual, con el mismo secreto de la app. Los pasos de verificación son los mismos que en los webhooks de la API: cuerpo crudo, comparación en tiempo constante y tolerancia de 5 minutos.
El vencimiento lo fija Commercy: 60 minutos desde que el comprador confirma, y tu app no tiene que aceptar pagos después. En ese momento consultamos tu /status una última vez: si está approved, confirmamos la venta; si está pending o rejected, la cancelamos. Si queda in_process (por ejemplo, un cupón de pago en efectivo), extendemos la sesión hasta un tope de 72 horas desde que se creó la venta; pasado ese plazo se cancela. Por eso un medio de pago lento tiene que resolverse dentro de esas 72 horas.
Dos reglas que conviene tener claras desde el diseño: el payment_id identifica la sesión y es estable aunque el comprador reintente con otra tarjeta, y los reembolsos los hacés vos en tu plataforma. Commercy no recibe reembolsos de las apps e ignora el estado refunded. Si el comercio cancela la venta, tu app recibe el webhook order.cancelled y tiene que devolverle al comprador de su lado.
Integración de envíos para e-commerce en Commercy
Una app de envío le permite a un comercio ofrecer tu logística: cotizás en el checkout, creás y cancelás envíos cuando el comercio lo pide y avisás cómo avanza la entrega. Necesita el permiso write_orders (que incluye read_orders), porque las cotizaciones y las altas llevan datos del comprador.
Cotización en el checkout
Cuando el comprador carga su código postal, Commercy llama a POST <apiBaseUrl>/commercy/shipping/quote con el código postal y los ítems del carrito (peso y dimensiones cuando el producto los tiene). Hay tres reglas importantes:
- Tope de 3 segundos. El checkout nunca espera a tu app más que eso. Si no respondés a tiempo, la conexión falla o devolvés un
5xx, dejamos de ofrecerte durante aproximadamente un minuto. - El precio que ve el comprador es el que se cobra. Guardamos tu cotización 15 minutos para ese carrito, tienda y código postal. Si al confirmar tu app ya no ofrece ese
method_id, la compra se rechaza: nunca se cobra un envío de $0. - Los métodos inválidos se descartan uno por uno, y los demás se ofrecen igual.
Alta, cancelación y tracking
El comercio crea el envío desde la venta («Enviar con tu app») y Commercy llama a tu ruta de alta, con 15 segundos de tope. La idempotency_key identifica un intento de envío: si el comercio reintenta, tenés que devolver el mismo envío (el mismo code), sin crear otro. La cancelación es otra ruta y, si falla, el envío queda vigente para que el comercio reintente.
El seguimiento lo empuja tu app: Commercy no consulta el estado de los envíos. Con el token de la instalación llamás a la API pública para pasar la venta a shipped o delivered y para cargar el número y el link de seguimiento. Tené en cuenta que delivered cierra la venta (descuenta stock, mueve la caja y genera el asiento contable), así que se manda solo cuando el paquete se entregó. Si el comercio cancela la venta, no cancelamos el envío en tu sistema: escuchás order.cancelled y lo cancelás vos.
Habilitación y revisión
Los dos tipos de app pasan por el mismo proceso que cualquier app:
- Creás la app en el portal de developers y la probás en tu tienda de desarrollo, sin plan pago.
- Para habilitarla como medio de pago o como carrier, le pasás a soporte de Commercy el id de tu app y la URL base de tu API. Es un paso manual.
- La enviás a revisión con ficha, política de privacidad, soporte, video de demo y un diagrama de secuencia. El equipo responde en hasta 10 días hábiles.
El resto de los requisitos (OAuth con PKCE, los 4 webhooks obligatorios, permisos mínimos) son los de cualquier app. La guía para crear una app para Commercy recorre ese camino.
Modelo comercial: 0 % de comisión
Commercy no cobra comisión por las apps: 0 %. Si tu servicio es pago, el cobro es directo entre vos y el comerciante, fuera de Commercy. Tampoco cobramos comisión por las ventas de los comercios en ningún plan. Podés informar el modelo y el precio en la ficha, a modo orientativo.
Cómo se compara con el programa de Tiendanube
Para quien ya integró con Tiendanube, esta tabla resume lo que su propia documentación informa a octubre de 2026. No es una evaluación de calidad ni de alcance, solo de condiciones publicadas.
| Aspecto | Tiendanube | Commercy |
|---|---|---|
| Documentación | API REST, OAuth2 y webhooks, con guías de Payment Provider y Shipping Carrier | Pública, con páginas de apps de pago y de envío |
| Habilitación de pagos | La Payments API no está habilitada por defecto: hay que contactarlos, y auditan la app | Se pide a soporte que habilite la app como medio de pago; también es un paso manual |
| Modelo comercial | Programa de socios tecnológicos con contrato, integración aprobada y revenue share en apps de pagos y envíos; el porcentaje no es público. Niveles Silver, Gold y Platinum | 0 % de comisión; el cobro es directo del desarrollador al comerciante |
| Cobros vía la plataforma | El partner recibe el monto descontadas tarifas, impuestos y la comisión de la plataforma, según su ayuda (en portugués); el porcentaje no está publicado | No hay cobro intermediado |
| Publicación | Homologación con diagrama de secuencia y video demo; NubeSDK obligatorio desde el 05/06/2026 para apps que inyectan scripts | Revisión manual con video de demo y diagrama de secuencia, hasta 10 días hábiles |
Las diferencias están en el modelo comercial (revenue share con porcentaje no público, o 0 %) y en cómo se habilita cada integración. En la publicación hay más parecidos: las dos plataformas piden un diagrama de secuencia y un video demo. Si estás evaluando dónde invertir tu integración, verificá las condiciones vigentes en las fuentes de cada plataforma antes de decidir.
Preguntas frecuentes
¿Cuánto cobra Commercy por una integración de pagos o envíos?
Nada: Commercy cobra 0 % de comisión por las apps. Si tu servicio es pago, el cobro es directo entre vos y el comerciante.
¿Cómo sabe Commercy que un pago se aprobó?
Tu app avisa con un webhook firmado payment.updated, que solo indica qué sesión cambió. Commercy consulta entonces tu ruta /status y verifica que el pago corresponda a la venta, con el mismo monto y en pesos, antes de confirmarla.
¿Cuánto tiempo tiene el comprador para pagar?
La sesión vence a los 60 minutos de la confirmación. Si el pago está en proceso, Commercy lo sigue consultando hasta un tope de 72 horas desde que se creó la venta; pasado ese plazo, la venta se cancela.
¿Quién hace los reembolsos?
Tu app, desde tu plataforma. Commercy no recibe reembolsos de las apps y no mueve la plata cuando un comercio cancela una venta: tu app recibe el webhook order.cancelled y devuelve el dinero de su lado.
¿Cuánto tarda la cotización de envío en el checkout?
Commercy espera hasta 3 segundos. Si tu app no responde a tiempo o falla con un 5xx, deja de ofrecerse en el checkout por aproximadamente un minuto.
¿Tengo que pasar por soporte para habilitar mi app?
Sí. Para habilitarla como medio de pago o como carrier le pasás a soporte el id de tu app y la URL base de tu API. Mientras está en borrador, la habilitamos solo en tu tienda de desarrollo para que pruebes el flujo completo.