Skip to main content
Con el checkout embebido tu cliente paga dentro de tu web. Ve el mismo checkout de Cobrix (pago móvil, transferencia, Zelle y débito inmediato si tu empresa lo tiene activo), con el color y la letra de tu tienda.
Disponible en sandbox. Puedes integrarlo y probarlo completo hoy en sandbox. En producción todavía no está activo: te avisaremos cuando puedas cambiar las URLs.
Si prefieres que el pago sea un campo más de tu propio formulario, usa el componente de débito inmediato.

Cómo funciona

Son tres pasos:
1

Tu servidor crea el cobro

Cuando el cliente va a pagar, tu servidor llama a POST /checkouts con el monto y tu referencia del pedido. Cobrix responde con un embedToken, que tu servidor le entrega a tu página. Hazlo siempre desde el servidor: la llave de API nunca va en el navegador. El detalle está en 1. Crea el cobro.
2

Registras tu web en el panel

Por seguridad, el checkout solo se muestra en las webs que tu empresa registra.
3

Tu web muestra el checkout

Con checkout.js y el embedToken, dentro de la página o en una ventana.
Confirma el pago con el webhook, no con el evento del navegador. Tu servidor da el pago por bueno solo cuando recibe el webhook firmado payment.succeeded. Los eventos de checkout.on(...) sirven para mostrarle el resultado al cliente, nada más.

URLs por ambiente

Carga siempre checkout.js del mismo ambiente donde creaste el cobro. Un embedToken de sandbox no funciona con el script de producción.

1. Crea el cobro

  • Permiso de la llave: checkouts:write.
  • Autenticación: Bearer y firma, como en toda la API de integraciones. Consulta Firma de solicitudes.
  • Idempotency-Key: obligatorio. La misma clave devuelve el mismo cobro. Consulta Idempotencia.
Crea un cobro por cada pedido, justo antes de mostrar el pago. Este ejemplo lo crea y devuelve el embedToken:
Node.js (tu servidor)
Tu página recibe ese embedToken de tu servidor (por ejemplo, al cargar la página de pago) y se lo pasa a checkout.js en el paso 4. El cuerpo de la solicitud:
Solicitud
Respuesta 201
  • embedToken es lo que le pasas a checkout.js.
  • paymentMethods trae los métodos que tu empresa tiene activos.
  • Si enviaste returnUrl, la respuesta la trae.
  • Si la referencia ya existe y sigue abierta, Cobrix actualiza el cobro y devuelve el checkout vigente.
  • Si ya está pagada o anulada, responde 409 checkout_document_closed.
  • Si returnUrl no cumple las reglas, responde 422 invalid_return_url y no crea nada.
  • Todos los errores de POST /checkouts y GET /checkouts/{externalDocumentId} traen { "error": { "code", "message" } }. Un cuerpo que no cumple el formato responde 400 invalid_request, con el primer campo con problema en field y cada problema en details. Un fallo de Cobrix responde 500 internal_error, con un mensaje genérico.

2. Consulta el cobro

Requiere el permiso checkouts:read. Una referencia que no existe responde 404.

3. Registra tu web

En el panel, entra a Integraciones › Checkout embebido con un usuario owner o admin.
  1. Escribe la dirección de tu web como se ve en el navegador, por ejemplo mitienda.com. El panel te muestra cómo se guardará: https://mitienda.com.
  2. Copia el código que te da el panel y pásalo a quien maneja tu web.
Reglas de la dirección:
  • Solo https. No se aceptan rutas, comodines (*) ni direcciones IP.
  • Cada subdominio se registra aparte: tienda.mitienda.com no queda cubierto por mitienda.com.
  • Máximo 10 webs por empresa.
En una web que no esté registrada, el navegador bloquea el checkout.

4. Muestra el checkout

Mientras carga, checkout.js muestra una silueta gris. Si no carga en 20 segundos, muestra «No pudimos cargar el pago» con un botón para reintentar.

Apariencia

Cualquier otro valor se ignora.

5. Eventos en el navegador

Cada evento trae:
No marques el pedido como pagado con estos eventos. Ocurren en el navegador del cliente: pueden no llegar si cierra la pestaña y cualquiera puede alterarlos desde su equipo. Úsalos solo para cambiar lo que ve el cliente.

Confirma el pago con el webhook

Marca el pedido como pagado y entrégalo desde tu servidor, cuando llegue el webhook:
  1. Configura tus webhooks en Integraciones › Webhooks.
  2. Verifica la firma de cada webhook. Consulta Firma de webhooks.
  3. Busca el pedido con el externalDocumentId que trae el webhook y márcalo como pagado.
El detalle de cada webhook está en payment.succeeded y checkout.collection_document_session.completed.

Qué ve tu cliente después de pagar

Si en vez del checkout embebido mandas a tu cliente al link (checkoutUrl), envía returnUrl al crear el cobro. Así vuelve a tu web cuando termina.
Solicitud
Cuando el pago queda aprobado o en revisión, el checkout muestra «Volver a mitienda.com» y vuelve solo a los 5 segundos. Si el pago se rechaza, solo muestra el botón. Cobrix agrega checkout con tu referencia y conserva la ruta, la query y el # de tu URL:
Reglas de returnUrl:
  • Solo https, hasta 2048 caracteres, sin usuario ni contraseña.
  • Va con el checkout que abre esa llamada. Si vuelves a crear el cobro sin returnUrl, el checkout nuevo no la tiene.
El checkout embebido no redirige. Tu página recibe el resultado con los eventos del navegador.
La URL de regreso no confirma el pago. Cualquiera puede escribirla a mano. Cuando tu cliente llegue, consulta el cobro con GET /checkouts/{externalDocumentId} desde tu servidor, o espera el webhook payment.succeeded. Nunca entregues el pedido por haber recibido la visita.
Este ejemplo atiende la vuelta y consulta el estado antes de decidir qué mostrar:
Node.js (tu servidor)

Seguridad

  • Solo en tus webs: el checkout se muestra únicamente en las direcciones que registraste.
  • Sin datos de pago en tu página: tu web nunca ve los datos bancarios del cliente, solo el resultado.
  • El webhook manda: un evento del navegador puede no llegar si el cliente cierra la pestaña. El webhook firmado llega igual.
  • La URL de regreso tampoco confirma: solo dice qué cobro consultar.

Lista para probar en sandbox

  1. Crea una llave en sandbox con checkouts:write y checkouts:read.
  2. Registra la dirección de tu web de pruebas en Integraciones › Checkout embebido.
  3. Crea un cobro con POST /checkouts y guarda el embedToken.
  4. Muestra el checkout con checkout.js de sandbox.
  5. Configura un webhook y confirma que recibes payment.succeeded.