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.
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.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.
embedToken:
Node.js (tu servidor)
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
embedTokenes lo que le pasas acheckout.js.paymentMethodstrae 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
returnUrlno cumple las reglas, responde422 invalid_return_urly no crea nada. - Todos los errores de
POST /checkoutsyGET /checkouts/{externalDocumentId}traen{ "error": { "code", "message" } }. Un cuerpo que no cumple el formato responde400 invalid_request, con el primer campo con problema enfieldy cada problema endetails. Un fallo de Cobrix responde500 internal_error, con un mensaje genérico.
2. Consulta el cobro
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.- 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. - Copia el código que te da el panel y pásalo a quien maneja tu web.
- Solo
https. No se aceptan rutas, comodines (*) ni direcciones IP. - Cada subdominio se registra aparte:
tienda.mitienda.comno queda cubierto pormitienda.com. - Máximo 10 webs por empresa.
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:
Confirma el pago con el webhook
Marca el pedido como pagado y entrégalo desde tu servidor, cuando llegue el webhook:- Configura tus webhooks en Integraciones › Webhooks.
- Verifica la firma de cada webhook. Consulta Firma de webhooks.
- Busca el pedido con el
externalDocumentIdque trae el webhook y márcalo como pagado.
payment.succeeded y checkout.collection_document_session.completed.
Qué ve tu cliente después de pagar
Vuelve a tu web desde el link
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
checkout con tu referencia y conserva la ruta, la query y el # de tu URL:
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.
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
- Crea una llave en sandbox con
checkouts:writeycheckouts:read. - Registra la dirección de tu web de pruebas en Integraciones › Checkout embebido.
- Crea un cobro con
POST /checkoutsy guarda elembedToken. - Muestra el checkout con
checkout.jsde sandbox. - Configura un webhook y confirma que recibes
payment.succeeded.

