Skip to main content
Con el componente, tu cliente paga con débito inmediato dentro de tu propio formulario. Escribe su banco, cédula y teléfono, recibe un código por SMS y lo confirma ahí mismo. El botón «Pagar» es el tuyo.
Disponible en sandbox. Puedes integrarlo hoy en sandbox. En producción todavía no está activo: te avisaremos cuando puedas cambiar las URLs.
Usa el mismo cobro, las mismas webs registradas y el mismo checkout.js que el checkout embebido.

Cómo funciona

1

Tu servidor crea el cobro

Llama a POST /checkouts y recibe un embedToken. Sin ese token el componente no se puede mostrar.
2

Registras tu web en el panel

El componente solo se muestra en las webs que tu empresa registra.
3

Tu formulario monta el componente

Con checkout.js y el embedToken. Tu botón «Pagar» llama a confirm().

Antes de empezar

  • Tu empresa necesita el débito inmediato activo. Si paymentMethods de POST /checkouts no trae debito_inmediato, el componente avisa que no está disponible.
  • El débito inmediato cobra en bolívares. Cobrix calcula el monto en Bs a partir del cobro.
  • Necesitas una llave de API con el permiso checkouts:write. Consulta Autenticación.

1. Crea el cobro

Cuando el cliente va a pagar, tu servidor crea el cobro y obtiene el embedToken. Hazlo siempre desde el servidor: la llave de API nunca va en el navegador.
Node.js (tu servidor)
Respuesta 201
  • embedToken es lo que le pasas a checkout.js. Tu página lo recibe de tu servidor.
  • Confirma que paymentMethods trae debito_inmediato.
  • Todos los campos, la firma y los errores están en Checkout embebido › 1. Crea el cobro.

2. Registra tu web

En el panel, entra a Integraciones › Checkout embebido y agrega la dirección de tu web, por ejemplo mitienda.com. Solo https, y cada subdominio se registra aparte. En una web que no esté registrada, el navegador bloquea el componente.

3. Monta el componente

Confirma el pago con el webhook, no con confirm(). El resultado de confirm() llega al navegador del cliente y sirve para mostrarle «gracias» o el error. Tu servidor marca el pedido como pagado solo cuando recibe el webhook firmado payment.succeeded. Consulta Confirmar el pago en tu servidor.

Qué pasa al pagar

1

El cliente llena sus datos

Banco, cédula y teléfono. Cuando están completos llega element.change con complete: true.
2

Tu botón llama a confirm()

Cobrix le pide al banco del cliente que envíe el código por SMS.
3

El cliente escribe el código

Lo escribe dentro del componente. Tu página nunca ve el código ni los datos bancarios.
4

confirm() se resuelve

Con succeeded o failed. En paralelo recibes el webhook payment.succeeded.

Métodos y eventos

Valores de step en element.change: form, otp, processing, success y error.

Resultado de confirm()

Pago aprobado
Pago no completado
Cuando el banco rechaza, error.code trae el código del banco (por ejemplo AM04, fondos insuficientes) y error.message un texto listo para mostrar. El componente ofrece «Intentar de nuevo» y tu página vuelve a llamar a confirm().

Motivos de element.unavailable

Apariencia

El componente no tiene fondo ni margen propios: sus bordes coinciden con los de tus campos. Además de primaryColor y fontFamily, appearance acepta: Un valor fuera de rango se ignora. El componente usa siempre el tema claro.

Confirmar el pago en tu servidor

No entregues el pedido con el resultado de confirm() ni con los eventos del componente. Ocurren en el navegador del cliente: pueden no llegar si cierra la pestaña y cualquiera puede alterarlos desde su equipo. Entrégalo cuando tu servidor reciba el webhook firmado.
  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.
Al aprobarse el débito llegan los mismos webhooks que con el checkout completo: payment.succeeded y, si no queda saldo, checkout.collection_document_session.completed. Los dos traen tu externalDocumentId. También puedes consultar el cobro con GET /integrations/v1/{companyId}/checkouts/{externalDocumentId}.

Lista para probar en sandbox

  1. Pide a Cobrix que active el débito inmediato en tu empresa de sandbox.
  2. Crea un cobro con POST /checkouts y confirma que paymentMethods trae debito_inmediato.
  3. Registra tu web de pruebas en Integraciones › Checkout embebido.
  4. Monta el componente y espera element.ready.
  5. Llama a confirm() desde tu botón y maneja succeeded y failed.
  6. Confirma que tu servidor recibe payment.succeeded.